Transactional

Send a transactional notification

POST https://demo.notifuse.com/api/transactional.send

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

Authorizations

Authorization string header required

Bearer authentication header of the form Bearer <token>, where <token> is your API key.

Body application/json

workspace_id string required

The ID of the workspace

  • Example: ws_1234567890
notification object required
Show child attributes
id string required

ID of the notification to send

  • Example: welcome_email
external_id string | null

External ID for idempotency checks

  • Example: txn_12345
contact object required
Show child attributes
email string<email> required

Email address of the contact. This is the contact's unique identifier.

  • Example: user@example.com
external_id string | null

Identifier for the contact in your own system. Not unique — several contacts may share the same external_id.

  • Example: user_12345
timezone string | null

Timezone of the contact

  • Example: America/New_York
language string | null

Preferred language of the contact

  • Example: en-US
first_name string | null

First name of the contact

  • Example: John
last_name string | null

Last name of the contact

  • Example: Doe
full_name string | null

Full name of the contact (for systems that don't have separate first/last names)

  • Example: John Doe
phone string | null

Phone number of the contact

  • Example: +15551234567
address_line_1 string | null

First line of address

  • Example: 123 Main St
address_line_2 string | null

Second line of address

  • Example: Apt 4B
country string | null

Country of the contact

  • Example: US
postcode string | null

Postal code

  • Example: 10001
state string | null

State or province

  • Example: NY
job_title string | null

Job title of the contact

  • Example: Software Engineer
tracking_opens_consent string | null

The contact's own choice about open tracking; null means unknown.

  • Available options: granted, denied, null
tracking_clicks_consent string | null

The contact's own choice about click tracking; null means unknown.

  • Available options: granted, denied, null
tracking_consent_updated_at string<date-time> | null

When a tracking choice last changed.

tracking_consent_source string | null

Where the last tracking choice came from (api, console, import, notification_center, email_link, subscribe_form).

custom_string_1 string | null

Custom string field 1

  • Example: Premium tier
custom_string_2 string | null

Custom string field 2

custom_string_3 string | null

Custom string field 3

custom_string_4 string | null

Custom string field 4

custom_string_5 string | null

Custom string field 5

custom_number_1 number<float> | null

Custom number field 1

  • Example: 42
custom_number_2 number<float> | null

Custom number field 2

custom_number_3 number<float> | null

Custom number field 3

custom_number_4 number<float> | null

Custom number field 4

custom_number_5 number<float> | null

Custom number field 5

custom_datetime_1 string<date-time> | null

Custom datetime field 1

  • Example: 2023-06-01T09:00:00Z
custom_datetime_2 string<date-time> | null

Custom datetime field 2

custom_datetime_3 string<date-time> | null

Custom datetime field 3

custom_datetime_4 string<date-time> | null

Custom datetime field 4

custom_datetime_5 string<date-time> | null

Custom datetime field 5

custom_json_1 any

Custom JSON field 1. Any JSON value, or null.

custom_json_2 any

Custom JSON field 2. Any JSON value, or null.

custom_json_3 any

Custom JSON field 3. Any JSON value, or null.

custom_json_4 any

Custom JSON field 4. Any JSON value, or null.

custom_json_5 any

Custom JSON field 5. Any JSON value, or null.

created_at string<date-time> read-only

When the contact was created (read-only, set by server)

  • Example: 2023-01-15T10:30:00Z
updated_at string<date-time> read-only

When the contact was last updated (read-only, set by server)

  • Example: 2023-04-22T15:45:00Z
contact_lists object[] read-only

Lists the contact is subscribed to (read-only, included in GET responses only)

Show child attributes
email string<email>

Email address of the contact

  • Example: user@example.com
list_id string

ID of the list

  • Example: newsletter
list_name string

Name of the list

  • Example: Newsletter
status string

Subscription status

  • Available options: active, pending, unsubscribed, bounced, complained
  • Example: active
created_at string<date-time>

When the contact was subscribed to this list

  • Example: 2023-01-15T10:30:00Z
updated_at string<date-time>

When the subscription was last updated

  • Example: 2023-01-15T10:30:00Z
deleted_at string<date-time> | null

When the subscription was deleted (null if active)

contact_segments object[] read-only

Segments the contact belongs to (read-only, included in GET responses only)

Show child attributes
email string<email>

Email address of the contact

  • Example: user@example.com
segment_id string

ID of the segment

  • Example: premium_users
version integer<int64>

Version of the segment computation

  • Example: 1
matched_at string<date-time>

When the contact was matched to this segment

  • Example: 2023-01-15T10:30:00Z
computed_at string<date-time>

When the segment was last computed

  • Example: 2023-01-15T10:30:00Z
channels string[] required

Channels to send through (at least one required)

  • Available options: email
data object

Data to populate the template with

metadata object

Additional metadata for tracking

email_options object

Email-specific options

Show child attributes
sender_id string

ID of one of the transactional email integration's senders. The email leaves from this sender instead of the template's. An ID that is not one of the integration's senders is refused with a 400 before the contact is created or updated. from_name still applies on top of it.

  • Example: 3f1c2a9e-7b4d-4e1a-9c2f-5d8e6a0b1c3d
from_name string | null

Override default sender from name

  • Example: Support Team
subject string | null

Override template subject line. Supports Liquid templating variables.

  • Maximum length: 255
  • Example: Welcome, {{ name }}!
subject_preview string | null

Override template preheader/preview text. Supports Liquid templating variables.

  • Maximum length: 255
  • Example: Your order has been confirmed
cc string<email>[]

CC email addresses

bcc string<email>[]

BCC email addresses

reply_to string<email>

Reply-To email address. Takes the place of the template's reply-to for this message.

  • Example: support@example.com
attachments object[]

Email attachments (max 20 files, 3MB per file, 10MB total)

  • Maximum items: 20
Show child attributes
filename string required

Name of the file (max 255 characters, no path separators)

  • Maximum length: 255
  • Example: invoice.pdf
content string<byte> required

Base64-encoded file content (max 3MB per file)

  • Example: JVBERi0xLjQKJeLjz9MKMy4uLg==
content_type string

MIME type of the file (auto-detected if not provided)

  • Example: application/pdf
disposition string

How the attachment should be displayed (defaults to 'attachment')

  • Default: attachment
  • Available options: attachment, inline
  • Example: attachment
content_id string

Content-ID for inline attachments, referenced from the HTML body as . Only allowed when disposition is 'inline'. May only contain letters, digits, and the characters . _ - @ (max 255 characters). Defaults to the filename when omitted.

  • Maximum length: 255
  • Example: checkInQr

Response

200 Notification sent successfully object
message_id string

Unique identifier for the sent message

  • Example: msg_1234567890abcdef
success boolean

Whether the notification was sent successfully

  • Example: true
400 Bad request - validation failed object
error string required

Error message

401 Unauthorized - invalid or missing authentication token object
error string required

Error message

403 The API key lacks a permission the send requires. `transactional:write` is always required; `contacts:read` is required in addition when the request sets `cc` or `bcc`, because the subject is rendered against the contact. object
error string required

Error message

422 The email cannot be built from the template and the data of the send: a Liquid error, such as a filter that fails or a comparison of a text with a number, or an MJML error. Nothing is sent. The template or the data has to change; sending again fails the same way. object
error string required

Error message

500 Internal server error object
error string required

Error message