---
title: "Send a transactional notification"
method: POST
path: "/api/transactional.send"
---

# Send a transactional notification

`POST /api/transactional.send`

Sends a transactional notification to a contact through specified channels.
Requires authentication.

## Request body

- SendTransactionalRequest
  - `workspace_id` string, required — The ID of the workspace
  - `notification` TransactionalNotificationSendParams, required
    - `id` string, required — ID of the notification to send
    - `external_id` string, nullable — External ID for idempotency checks
    - `contact` Contact, required
      - `email` string, email, required — Email address of the contact. This is the contact's unique identifier.
      - `external_id` string, nullable — Identifier for the contact in your own system. Not unique — several contacts may share the same external_id.
      - `timezone` string, nullable — Timezone of the contact
      - `language` string, nullable — Preferred language of the contact
      - `first_name` string, nullable — First name of the contact
      - `last_name` string, nullable — Last name of the contact
      - `full_name` string, nullable — Full name of the contact (for systems that don't have separate first/last names)
      - `phone` string, nullable — Phone number of the contact
      - `address_line_1` string, nullable — First line of address
      - `address_line_2` string, nullable — Second line of address
      - `country` string, nullable — Country of the contact
      - `postcode` string, nullable — Postal code
      - `state` string, nullable — State or province
      - `job_title` string, nullable — Job title of the contact
      - `custom_string_1` string, nullable — Custom string field 1
      - `custom_string_2` string, nullable — Custom string field 2
      - `custom_string_3` string, nullable — Custom string field 3
      - `custom_string_4` string, nullable — Custom string field 4
      - `custom_string_5` string, nullable — Custom string field 5
      - `custom_number_1` number, float, nullable — Custom number field 1
      - `custom_number_2` number, float, nullable — Custom number field 2
      - `custom_number_3` number, float, nullable — Custom number field 3
      - `custom_number_4` number, float, nullable — Custom number field 4
      - `custom_number_5` number, float, nullable — Custom number field 5
      - `custom_datetime_1` string, date-time, nullable — Custom datetime field 1
      - `custom_datetime_2` string, date-time, nullable — Custom datetime field 2
      - `custom_datetime_3` string, date-time, nullable — Custom datetime field 3
      - `custom_datetime_4` string, date-time, nullable — Custom datetime field 4
      - `custom_datetime_5` string, date-time, nullable — Custom datetime field 5
      - `custom_json_1` object, nullable — Custom JSON field 1
      - `custom_json_2` object, nullable — Custom JSON field 2
      - `custom_json_3` object, nullable — Custom JSON field 3
      - `custom_json_4` object, nullable — Custom JSON field 4
      - `custom_json_5` object, nullable — Custom JSON field 5
      - `created_at` string, date-time — When the contact was created (read-only, set by server)
      - `updated_at` string, date-time — When the contact was last updated (read-only, set by server)
      - `contact_lists` ContactList[] — Lists the contact is subscribed to (read-only, included in GET responses only)
        - `email` string, email — Email address of the contact
        - `list_id` string — ID of the list
        - `list_name` string — Name of the list
        - `status` 'active' | 'pending' | 'unsubscribed' | 'bounced' | 'complained' — Subscription status
        - `created_at` string, date-time — When the contact was subscribed to this list
        - `updated_at` string, date-time — When the subscription was last updated
        - `deleted_at` string, date-time, nullable — When the subscription was deleted (null if active)
      - `contact_segments` ContactSegment[] — Segments the contact belongs to (read-only, included in GET responses only)
        - `email` string, email — Email address of the contact
        - `segment_id` string — ID of the segment
        - `version` integer — Version of the segment computation
        - `matched_at` string, date-time — When the contact was matched to this segment
        - `computed_at` string, date-time — When the segment was last computed
    - `channels` string[], required — Channels to send through (at least one required)
    - `data` object — Data to populate the template with
    - `metadata` object — Additional metadata for tracking
    - `email_options` object — Email-specific options
      - `from_name` string, nullable — Override default sender from name
      - `subject` string, nullable — Override template subject line. Supports Liquid templating variables.
      - `subject_preview` string, nullable — Override template preheader/preview text. Supports Liquid templating variables.
      - `cc` string[] — CC email addresses
      - `bcc` string[] — BCC email addresses
      - `reply_to` string, email — Reply-To email address
      - `attachments` EmailAttachment[] — Email attachments (max 20 files, 3MB per file, 10MB total)
        - `filename` string, required — Name of the file (max 255 characters, no path separators)
        - `content` string, byte, required — Base64-encoded file content (max 3MB per file)
        - `content_type` string — MIME type of the file (auto-detected if not provided)
        - `disposition` 'attachment' | 'inline' — How the attachment should be displayed (defaults to 'attachment')
        - `content_id` string — Content-ID for inline attachments, referenced from the HTML body as <img src="cid:..."> . Only allowed when disposition is 'inline'. May only contain letters, digits, and the characters . _ - @ (max 255 characters). Defaults to the filename when omitted.

## Response `200`

Notification sent successfully

- object
  - `message_id` string — Unique identifier for the sent message
  - `success` boolean — Whether the notification was sent successfully

## Other responses

- `400` — Bad request - validation failed
- `401` — Unauthorized - invalid or missing authentication token
- `500` — Internal server error

## Changes

- **2026-07-25** `76e3598f162d` — 1 info
  - added the new optional request property `notification/email_options/attachments/items/content_id`
- **2026-05-13** `1de3167ef51f` — 2 info
  - added the new optional request property `notification/email_options/subject`
  - added the new optional request property `notification/email_options/subject_preview`
- **2025-12-19** `a1331825c4e5` — 2 breaking
  - the request property `notification/channels` became required
  - the `notification/channels` request property's minItems was increased to `1`
- **2025-12-02** `c9edbbd76e08` — 4 info
  - the request optional property `notification/contact/contact_lists` became read-only
  - the request optional property `notification/contact/contact_segments` became read-only
  - the request optional property `notification/contact/created_at` became read-only
  - the request optional property `notification/contact/updated_at` became read-only
- **2025-12-01** `bca4a43d9d46` — 2 info
  - added the new optional request property `notification/contact/contact_segments`
  - added the new optional request property `notification/contact/full_name`

[Full history](https://skmtc.dev/pierre-b/apis/notifuse-api/changes/api/transactional.send/post.md)

---

[API](https://skmtc.dev/pierre-b/apis/notifuse-api.md) · [All operations](https://skmtc.dev/pierre-b/apis/notifuse-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pierre-b/notifuse-api/revisions/d26605f2fc47/schema)