---
title: "Send a transactional push"
method: POST
path: "/v1/send/push"
tags: ["Send Messages"]
---

# Send a transactional push

`POST /v1/send/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](/integrations/api/app/tag/transactional/).

## Headers

- `X-Workspace-Id` integer

## Request body

- Sendpush
  - `transactional_message_id` union, required — The transactional message template that you want to use for your message. You can call the template by its numerical ID or by the *Trigger Name* that you assigned to the template in the UI (case insensitive).
    - integer — The ID of the transactional message you want to send.
    - string — The name of trigger for the transactional message you want to send; you set the trigger name in the *Configure Settings* step when setting up your message. This is case insensitive.
  - `auto_create` boolean — 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](/journeys/transactional-email/#auto-create-transactional-message-records).
  - `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.
  - `title` string — The title for your notification. This overrides the title of the transactional template (referenced by `transactional_message_id`).
  - `message` string — The message body for your notification. This overrides the notification body of the transactional template (referenced by `transactional_message_id`).
  - `image_url` string — An image URL to show in the push. This overrides Image from the transactional template (referenced by `transactional_message_id`).
  - `link` string — 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_data` object — 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.
  - `custom_device` object — Device information common to the v1 and v2 APIs.
    - `token` string, required — The device token.
    - `last_used` integer — The `timestamp` when you last identified this device. If you don't pass a timestamp when you add or update a device, we use the time of the request itself. Our SDKs identify a device when a person launches their app.
    - `platform` 'ios' | 'android', required — The device/messaging platform.
    - `attributes` object — Attributes that you can reference to segment your audience—like a person's attributes, but specific to a device. These can be either the attributes defined below or custom key-value attributes.
      - `device_os` string — The operating system, including the version, on the device.
      - `device_model` string — The model of the device a person uses.
      - `app_version` string — The version of your app that a customer uses. You might target app versions to let people know when they need to update, or expose them to new features when they do.
      - `cio_sdk_version` string — The version of the Customer.io SDK in the app.
      - `_last_status` '' | 'bounced' | 'sent' | 'suppressed' — The delivery status of the last message sent to the device—sent, bounced, or suppressed. An empty string indicates that that the device hasn't received a push yet.
      - `device_locale` string — The device's [IETF language code](/journeys/channels/localization/getting-started/#supported-languages), such as `en-MX` or `es-ES`.
      - `push_enabled` 'true' | 'false' — If `"true"`, the device is opted-in and can receive push notifications.
  - `custom_payload` object — Optional key/value pairs you want to attach to the push payload. Firebase only supports string values. This overrides all other payload values, including the Custom Payload from your transactional template.
    - `ios` union — Your payload changes depending on whether you send to iOS devices through Google's Firebase Cloud Messaging (FCM) or Apple's Push Notification service (APNs).
      - object
        - `message` object, required — The base object for all FCM payloads.
          - `apns` object, required — Defines a payload for iOS devices sent through Firebase Cloud Messaging (FCM).
            - `headers` object — Headers defined by [Apple's payload reference](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/sending_notification_requests_to_apns) that you want to pass through FCM.
            - `payload` object, required — Contains a push payload.
              - …
      - object
        - `CIO` object — Contains options supported by the Customer.io SDK.
          - `push` object, required — Describes push notification options supported by the CIO SDK.
            - `link` string — A deep link (to a page in your app), or a link to a web page.
            - `image` string — The URL of an HTTPS image that you want to use for your message.
        - `aps` IosSharedOptions — A push payload intended for an iOS device.
          - `alert` union
            - string — A simple alert message.
            - object
              - …
          - `badge` integer — The number you want to display on your app's icon. Set to 0 to remove the current badge, if any.
          - `sound` union
            - string — The name of a sound file in your app’s main bundle or in the Library/Sounds folder of your app’s container directory. Use “default” to play the system sound. For critical alerts, you'll pass an object instead.
            - object
              - …
          - `thread-id` string — An identifier to group related notifications.
          - `category` string — The notification’s type. This string must correspond to the identifier of one of the `UNNotificationCategory` objects you register at launch time.
          - `content-available` integer — The background notification flag. Use `1` without an `alert` to perform a silent update. `0` indicates a normal push notification.
          - `mutable-content` integer — Set this to `1` if you use the Customer.io SDK, so you can support images and delivered metrics in your push notifications. It passes the notification to your service extension before delivery.
          - `target-content-id` string — The identifier of the window brought forward.
          - `interruption-level` 'passive' | 'active' | 'time-sensitive' | 'critical' — Indicates the importance and delivery timing of a notification.
          - `relevance-score` number — A number between 0 and 1. The highest score is considered the "most relevant" and is featured in the notification summary.
    - `android` FcmAndroidWithoutSdk — A custom push payload for Android devices.
      - `message` object, required — The parent object for Android custom push payloads.
        - `notification` object — Contains the push body and title.
          - `title` string — The title of your push notification.
          - `body` string — The body of your push notification.
        - `data` object — Contains key-value pairs that your app interprets.
        - `android` object — Contains custom push options for your notification.
          - `notification` CustomAndroidProps — Properties supported specifically by Android on FCM.
            - `icon` string — Sets the notification icon to `myicon` for drawable resource `myicon`. If you don't send this key, FCM displays the launcher icon from your app manifest.
            - `sound` string — The sound that plays when the device receives the notification. Supports `"default"` or the filename of a sound resource bundled in your app. Sound files must reside in `/res/raw/`.
            - `tag` string — An identifier you use to replace an existing notification. If a notification with the same tag is already showing, the new one replaces it. Leave it empty to create a new notification each time.
            - `color` string — The notification's icon color in `#rrggbb` format.
            - `click_action` string — The action that occurs when a user taps on the notification. Launches an activity with a matching intent filter when a person taps the notification.
            - `body_loc_key` string — String resource key used to localize the body text. See Android [String resources](https://developer.android.com/guide/topics/resources/string-resource/).
            - `body_loc_arg` string — Variable string values used in place of the format specifiers in `body_loc_key` to localize the body text to the user's current localization. See Formatting and Styling for more information.
            - `title_loc_key` string — String resource key used to localize the title text. See Android [String resources](https://developer.android.com/guide/topics/resources/string-resource/).
            - `title_loc_arg` string — Variable string values used in place of the format specifiers in `title_loc_key` to localize the title text to the user's current localization. See Formatting and Styling for more information.
  - `language` string — 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](/journeys/channels/localization/getting-started/#supported-languages).
  - `identifiers` union, required — Identifies the person represented by your transactional message by one of, and only one of, `id`, `email`, or `cio_id`.
    - object
      - `id` string, required — The identifier for the person represented by the transactional message. **NOTE**: If your workspace identifies people by email, use the `email` identifier instead.
    - object
      - `email` string, required — The identifier for the person represented by the transactional message. Use this option if your workspace identifies people by email rather than by `id`.
    - object
      - `cio_id` string, required — A unique, immutable identifier for a person, set by Customer.io when you add a person.
  - `message_data` object — An object containing the key-value pairs referenced using liquid in your message.
  - `send_at` integer — 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_retention` boolean — 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_unsubscribed` boolean — 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_draft` boolean — 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.

## Response `200`

Returns a unique ID for the delivery.

- object
  - `delivery_id` string — A unique identifier for the message.
  - `queued_at` integer — 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_at` integer — For a scheduled message, the Unix timestamp when the message is set to send. Returned only when you provide a future `send_at`.

## Other responses

- `400` — The request was malformed.
- `403` — You don't have push enabled for your workspace.

---

[API](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference.md) · [All operations](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/customer/customer-io-journeys-api-reference/revisions/4b391af7cb06/schema)