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 7 child attributes Hide 7 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 42 child attributes Hide 42 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.

Options granted, denied, null
tracking_clicks_consent string | null

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

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 7 child attributes Hide 7 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

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 5 child attributes Hide 5 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)

Options email
data object

Data to populate the template with

metadata object

Additional metadata for tracking

email_options object

Email-specific options

Show 8 child attributes Hide 8 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.

Max length 255 Example Welcome, {{ name }}!
subject_preview string | null

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

Max 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)

Max items 20
Show 5 child attributes Hide 5 child attributes
filename string required

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

Max 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 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.

Max 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