Skip to main content

Sending Transactional Messages

A transactional message is an event-driven message sent to a specific person in real-time. Unlike broadcasts, transactionals are triggered programmatically via API calls from your application when specific events occur—such as a user completing a purchase, resetting their password, or receiving an order confirmation.

Transactionals are best used when you need to send immediate, personalized messages triggered by user actions or system events.

How transactionals work​

A transactional message is sent to a single person when triggered by an API call. The message is delivered immediately upon execution, making it ideal for time-sensitive communications that must be sent in response to specific events.

Common use cases include:

  • Sending order confirmations after a purchase
  • Delivering password reset emails
  • Notifying users about account changes or security alerts
  • Sending receipt or invoice emails
  • Triggering push notifications for real-time updates

Creating a transactional​

Setting up a transactional involves creating a message template that can be triggered via API. During creation, you'll configure the following steps:

  1. Go to Transactionals and click Create Transactional
  2. Name your transactional
  3. Optionally set a Trigger Name (used to reference the transactional in API calls)
  4. Choose your Subscription Preference
  5. Select a Channel (Email, Push, or SMS)
  6. Create your message Content
  • For Emails refer to the Email Templates page for detailed guidance on setting up emails.
  1. Review and Save the transactional

Each step includes additional options explained below.

Trigger name​

A trigger name is a unique identifier you can use to reference your transactional when making API calls. This makes it easier to trigger messages without needing to remember transactional IDs.

  • Trigger names must be unique within your workspace
  • If you don't set a trigger name, you can still reference the transactional by its ID
  • Trigger names are useful for maintaining consistent references in your codebase

Subscription preferences​

You can choose whether to send your transactional to:

  • All subscribed people
  • All subscribed and unsubscribed people

⚠️ Important:
Sending messages to unsubscribed users may violate anti-spam regulations in your country. Misuse can result in account suspension or termination. Only include unsubscribed users when you have a clear legal basis to do so.

Content: create your message​

Transactionals can be sent through any supported channel:

  • Email
  • Push notifications
  • SMS

Choose your preferred channel to begin creating your message.

Email​

  • Use an existing email template, or
  • Create a new one from scratch
  • Optionally provide raw HTML content when triggering via API

Learn more about creating or editing email templates in the Email Templates documentation.

Push notifications​

  • Enter a title and message
  • Optionally include an image and add a deep link to direct users to a specific screen

SMS​

  • Enter the message you want to send
  • Optionally specify a recipient phone number (defaults to the person's phone if available)

You can personalise content using user data and trigger data passed via API calls.

Triggering a transactional​

Once created, transactionals are triggered via API calls to the data gateway. You can trigger a transactional in two ways:

  1. Using the transactional ID or trigger name - Reference a saved transactional template
  2. Sending raw content - Provide message content directly in the API call (for email and SMS)

API Endpoints​

Transactionals are triggered through the following endpoints:

  • Email: POST /data-gateway/transactionals/email
  • Push: POST /data-gateway/transactionals/push
  • SMS: POST /data-gateway/transactionals/sms

Using a transactional template​

When triggering with a template, you reference the transactional by its ID or trigger name:

{
  "transactional_message_id": "welcome-email",
  "identifiers": {
    "email": "[email protected]"
  },
  "message_data": {
    "user_name": "John",
    "order_id": "12345"
  }
}

The message will use the template's content, with any provided message_data available for personalization.

Sending raw content​

For email and SMS, you can send messages without a template by providing the content directly:

{
  "identifiers": {
    "email": "[email protected]"
  },
  "subject": "Order Confirmation",
  "body": "<html>Your order has been confirmed!</html>",
  "to": "[email protected]"
}

Personalization​

Transactional messages support personalization using:

  • User data - Access person attributes using {{person.attribute_name}}
  • Trigger data - Access data passed in the API call using {{trigger.field_name}}

This allows you to create dynamic, personalized messages that adapt to each recipient and the context of the trigger event.

🎉 That's it!
Once created, your transactional can be triggered via API calls whenever the corresponding event occurs in your application.