> ## 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.

Firmhouse delivers the message through the customer communication channel configured for the project:

* **Email:** the subject becomes the email subject and the Liquid template is rendered inside the standard Firmhouse email layout.
* **Klaviyo:** the subject becomes the event name and the Liquid template must render as a JSON event payload.
* **Disabled:** Firmhouse records the notification without delivering an email or Klaviyo event.

## Requirements

* A Firmhouse API access token with write access.
* The Firmhouse subscription ID for a subscription in the same project as the access token.
* The project's customer communication channel configured for email or Klaviyo.

## 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`; when it is empty, the notification has been queued for delivery.

## Klaviyo payloads

For Klaviyo projects, 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\"}"
}
```

The mutation uses the current project channel automatically, so your integration does not need separate email and Klaviyo delivery logic.

## Related

* [Generate API access tokens](/configure/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)