Sign in
Send Messages

Send a transactional push

Send a transactional push. You send a message using a transactional_message_id for a transactional push message template composed in the user interface. You can optionally override any of the template values at send time. 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.

post/v1/send/push

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

auto_createboolean

If true and your transactional_message_id doesn't match a record, Customer.io creates an empty record using that value as the Trigger Name. The ID must be a string. If the name already belongs to another channel, the request fails with 400, and numeric IDs ignore this setting. See details.

to'all' | 'last_used' | '$device_token'

The devices you want to send this push to—all, last_used, or a custom device token from the identified profile. Defaults to all and overrides the To value from your transactional template.

titlestring

The title for your notification. This overrides the title of the transactional template (referenced by transactional_message_id).

messagestring

The message body for your notification. This overrides the notification body of the transactional template (referenced by transactional_message_id).

image_urlstring

An image URL to show in the push. This overrides Image from the transactional template (referenced by transactional_message_id).

linkstring

A deep link to open when the push is tapped. This overrides Link from the transactional template (referenced by transactional_message_id).

sound'default' | 'none'

For iOS Only: your notification can alert users with the device's default notification sound or play no sound at all.

custom_dataobject

Optional key/value pairs you want to attach to the push payload. Firebase only supports string values. This overrides the Custom Data from your transactional template.

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.

message_dataobject

An object containing the key-value pairs referenced using liquid in your message.

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.

disable_message_retentionboolean

If true, the message body is not retained in delivery history. Setting this value overrides the value set in the settings of your transactional_message_id.

send_to_unsubscribedboolean

If false, your message is not sent to unsubscribed recipients. Setting this value overrides the value set in the settings of your transactional_message_id.

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.

Example request

{
  "transactional_message_id": 44,
  "title": "Did you really login from a new location?",
  "identifiers": {
    "id": 12345
  },
  "message_data": {
    "password_reset_token": "abcde-12345-fghij-d888",
    "account_id": "123dj"
  }
}

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.