> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firmhouse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send bespoke subscription messages

> Use the Firmhouse GraphQL API to send purpose-specific Liquid messages through your project's configured customer communication channel.

Use `sendSubscriptionNotification` when your integration needs to send a message for a specific purpose that is not covered by one of your configured Firmhouse email templates.

For example, you can send delivery instructions after a particular product is ordered, explain the next step after a manual review, or notify one customer about an exception that applies to their subscription. Supply the subject and Liquid template with each request.

Delivery depends on **Send emails to customers with** in **Settings > Email configuration > General**:

* **Built-in Firmhouse email notifications (default)** (`email`): the subject becomes the email subject and the Liquid template is rendered inside the standard Firmhouse email layout.
* **Custom Klaviyo metrics via the old Klaviyo integration** (`klaviyo`): the subject becomes the event name and the Liquid template must render as a JSON event payload. Without the native integration preview, this option is labeled **Custom Klaviyo metrics configured in Email configuration**.
* **Email flows via the new Klaviyo integration** (`klaviyo_native`) or **Disable sending emails or custom Klaviyo metrics** (`disabled`): this mutation records the notification but does not deliver an email or Klaviyo event.

For a bespoke event through the new Klaviyo integration, use `sendSubscriptionKlaviyoEvent` as described below.

## Requirements

* A Firmhouse API access token with write access.
* The Firmhouse subscription ID for a subscription in the same project as the access token.
* **Built-in Firmhouse email notifications (default)** or the old Klaviyo integration selected for delivery. For the old integration, the Klaviyo app must also be enabled and ready to send events.

## Send a message

Call `sendSubscriptionNotification` with the subscription ID, subject, and Liquid template:

```graphql theme={null}
mutation SendSubscriptionNotification(
  $subscriptionId: ID!
  $subject: String!
  $template: String!
) {
  sendSubscriptionNotification(input: {
    subscriptionId: $subscriptionId
    subject: $subject
    template: $template
  }) {
    subscription {
      id
    }
    errors {
      attribute
      message
    }
  }
}
```

For an email project, variables can contain an HTML message with subscription Liquid variables:

```json theme={null}
{
  "subscriptionId": "123456",
  "subject": "Your delivery needs a little extra attention",
  "template": "<p>Hi {{ subscription.first_name }},</p><p>We will contact you to arrange a suitable delivery time.</p>"
}
```

Firmhouse validates the subject and Liquid syntax before accepting the message. Always check `errors`; an empty list means the notification was accepted for processing, not that it was delivered. Delivery depends on the setting described above.

## Klaviyo v1 notification payloads

With **Custom Klaviyo metrics via the old Klaviyo integration** selected (the `klaviyo` setting), pass a template that renders as JSON instead of HTML:

```json theme={null}
{
  "subscriptionId": "123456",
  "subject": "Manual review completed",
  "template": "{\"subscription_id\":\"{{ subscription.id }}\",\"result\":\"approved\"}"
}
```

This example applies only to the old integration's notification setting. Selecting **Email flows via the new Klaviyo integration** does not deliver this notification.

Installing the Klaviyo v2 app leaves your email setting unchanged. This mutation does not enable or configure v2 lifecycle events.

## Bespoke Klaviyo events, including v2

To send a Klaviyo event independently of the project's communication channel, use `sendSubscriptionKlaviyoEvent` with `subscriptionId`, `eventName`, and a `properties` JSON object. Klaviyo must be connected and enabled. See the [GraphQL API reference](https://developer.firmhouse.com/graphql-api/api-reference) for the mutation contract and [Getting started with Klaviyo](/integrations/klaviyo/getting-started#send-lifecycle-events) for separately configured lifecycle events.

## Related

* [Generate API access tokens](/integrations/api-access-tokens)
* [Liquid documentation](https://developer.firmhouse.com/liquid/introduction)
* [Email template Liquid variables](https://developer.firmhouse.com/liquid/email-template-overview)
* [GraphQL API reference](https://developer.firmhouse.com/graphql-api/api-reference)