Sign in
Send Messages

Send a transactional inbox message

Send a transactional inbox message. Inbox messages deliver raw JSON payloads to your application through our JavaScript SDK, allowing you to build custom notification centers, message feeds, and other UI components.

You send a message using a transactional_message_id for an inbox message template created in the user interface. The transactional_message_id can be either the numerical ID for the template or the Trigger Name that you assigned the template.

You can find your transactional_message_id from the code sample in the Overview tab for your transactional message in the user interface, or you can look up a list of your transactional messages through the App API.

Note: Inbox messages are currently available for web platforms only and require the Customer.io In-App Plugin to be installed.

post/v1/send/inbox_message

Headers

X-Workspace-Idinteger
Example:100

The numeric ID of the workspace you want to send a message in. This header is only needed when you authenticate with a service-account bearer token (sa_live_…). Service accounts work across workspaces, so you must supply this header so we know which workspace to send from. You can omit this header when you authenticate with a standard App API key, which is always scoped to one workspace.

Request body

message_dataobject

An object containing the key-value pairs referenced using liquid in the format {{trigger.<property_name>}} in your inbox message. These values will populate the properties field in the message received by your application.

tostring

Optional override for the recipient. This is typically not needed as the message is sent to the person identified by identifiers.

send_atinteger

A unix timestamp (seconds since epoch) determining when the message will be sent. The timestamp can be up to 90 days in the future. If this value is in the past, your message is sent immediately.

queue_draftboolean

If true, your transactional message is held as a draft in Customer.io and not sent directly to your audience. You must go to the Deliveries and Drafts page to send your message.

languagestring

Overrides language preferences for the person you want to send your transactional message to. Use one of our supported two- or four-letter language codes.

auto_createboolean

Accepted for inbox sends, but of limited use. An auto-created record has no content or layout until you populate it in the UI, so we recommend creating the inbox message in the UI instead. Your transactional_message_id must be a new string.

Example request

{
  "transactional_message_id": "order_shipped",
  "identifiers": {
    "id": "user_123"
  },
  "message_data": {
    "order_id": "ORD-5678",
    "tracking_url": "https://track.example.com/5678",
    "product_name": "Blue Widget",
    "product_image": "https://cdn.example.com/widget.jpg"
  }
}

Response

Returns a unique ID for the delivery.

delivery_idstring

A unique identifier for the message.

queued_atinteger

A Unix timestamp for when Customer.io accepted and queued your request. For scheduled messages (using send_at), this is when we received your request, not when the message sends.

send_atinteger

For a scheduled message, the Unix timestamp when the message is set to send. Returned only when you provide a future send_at.

Changes

No recorded changes to this endpoint across all 1 revision of this API.