Messages

Transactional messages are one-off sends triggered by the recipient’s own action: order confirmations, shipping notices, receipts, password resets, appointment reminders. Senderz exposes one endpoint per channel, plus two endpoints for reading back what happened to a message after it was queued. Two channels are available on the public API: email and SMS. There is no public push, WhatsApp or voice send endpoint. One-time passcodes have their own surface, documented in OTP API. Every request uses the X-Sender-Tenant and X-API-Key headers against https://api.senderz.app/api/v1.

What “transactional” changes, and what it does not

Both send endpoints return 202 Accepted. The message row is created, the job is queued at elevated priority, and the send pipeline runs it asynchronously. A 202 means accepted for processing, not delivered. Use delivery status to find out what actually happened. Marking a message transactional relaxes the marketing gates only. It does not relax the identity, cost or abuse gates.

Gate	Transactional
Marketing consent on the contact	Skipped
Frequency caps	Skipped
Israeli quiet hours and Shabbat windows	Skipped
Workspace-level sending suspension	Skipped
Contact-plan overflow parking	Skipped
Channel feature toggles	Skipped
Open and click tracking injection	Not applied
Unsubscribe footer, `List-Unsubscribe` headers, SMS unsubscribe trailer	Not applied
SMS link shortening	Not applied
Suppression list	Applies, narrowed
Verified From domain and verified sender inbox (email)	Applies
Approved SMS Sender name (SMS)	Applies
SMS credit wallet	Applies

Suppression still applies, but a narrower set of reasons blocks a transactional message. Only hard_bounce, invalid_address and global_blocklist stop it. A marketing unsubscribe, a spam complaint, an SMS STOP reply, a repeated soft bounce, a list cleanup and a revoked push endpoint do not stop a transactional send. A blocked message is recorded with status suppressed and the suppression reason.

Send email

POST /api/v1/public/messages/email

Recipient

Provide to or contactId. If both are sent, contactId wins and to is ignored. If to does not match an existing contact, a new contact is created for that address.

string

Recipient email address. Trimmed and lowercased before lookup.

string

UUID of an existing contact. Returns 404 if it does not exist or has been deleted.

Sender

string

required

From address. Must be a valid email, on a verified sending domain, with a verified sender inbox for that exact local part.

string

Display name. Max 255 characters. On the template path this falls back to the template’s own sender name when omitted.

string

Reply-to address. Must be a valid email. Not subject to the verification rules above.

Content

Send either manual content or a template. See Sending from a template.

string

default:"manual"

Either manual or template. Optional. If you pass a templateId the template path is taken whether or not you set this. Setting contentMode: "manual" together with a templateId is rejected.

string

Subject line. Max 500 characters. Required on the manual path. Ignored when a templateId is present, because the subject then comes from the template.

string

HTML body. Max 500,000 characters. Required on the manual path. Ignored when a templateId is present.

string

Plain-text alternative. Max 500,000 characters. Optional. Ignored when a templateId is present, because the template renders its own plain-text part.

string

UUID of an email template in this workspace. Must be a template whose channel is email.

object

Flat object of merge values for the template. Values may be strings, numbers, booleans or null.

Response

Status 202 Accepted.

string

The queued message’s UUID. Pass it to GET /public/messages/{id} to read delivery status. It is a plain UUID with no prefix.

curl -X POST https://api.senderz.app/api/v1/public/messages/email \
  -H "X-Sender-Tenant: acme-store" \
  -H "X-API-Key: $SENDERZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "dana@example.com",
    "fromEmail": "orders@acme-store.com",
    "fromName": "Acme Store",
    "replyTo": "support@acme-store.com",
    "subject": "Order #10482 is on its way",
    "html": "<p>Hi Dana, your order shipped. Tracking: RR123456789IL</p>",
    "text": "Hi Dana, your order shipped. Tracking: RR123456789IL"
  }'

const res = await fetch(
  "https://api.senderz.app/api/v1/public/messages/email",
  {
    method: "POST",
    headers: {
      "X-Sender-Tenant": process.env.SENDERZ_WORKSPACE,
      "X-API-Key": process.env.SENDERZ_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      to: "dana@example.com",
      fromEmail: "orders@acme-store.com",
      fromName: "Acme Store",
      subject: "Order #10482 is on its way",
      html: "<p>Hi Dana, your order shipped. Tracking: RR123456789IL</p>",
    }),
  },
);
const { data } = await res.json();
console.log(data.messageId);

import os, requests

res = requests.post(
    "https://api.senderz.app/api/v1/public/messages/email",
    headers={
        "X-Sender-Tenant": os.environ["SENDERZ_WORKSPACE"],
        "X-API-Key": os.environ["SENDERZ_API_KEY"],
    },
    json={
        "to": "dana@example.com",
        "fromEmail": "orders@acme-store.com",
        "fromName": "Acme Store",
        "subject": "Order #10482 is on its way",
        "html": "<p>Hi Dana, your order shipped. Tracking: RR123456789IL</p>",
    },
)
print(res.json()["data"]["messageId"])

{
  "success": true,
  "data": { "messageId": "9f3c1b2e-5a47-4d18-9c0b-7e2a6d4f8b31" }
}

Sender requirements

The From address is checked synchronously, before the message is queued. Three separate conditions must hold, and each has its own error code.

The domain is added and verified

The domain part of fromEmail must exist in this workspace and be in the verified state. Otherwise 400 with code from_domain_not_verified. See Domains and authentication.

The domain is not blocklisted

A domain currently listed on the Spamhaus domain blocklist is refused with 400 and code from_domain_blacklisted.

The exact mailbox is confirmed

A sender address row for that exact local part must exist and be verified. Adding orders@acme-store.com sends a confirmation email to that mailbox, and until someone clicks the link in it, sending from it returns 400 with code sender_inbox_not_verified. See Sender addresses and names.

GET /public/sender-addresses returns exactly the addresses that will pass all three checks. Its value field is the address to put in fromEmail.

Errors

Status	Code	Message	Cause
`400`		Validation message	Body failed validation, or carried an unknown property.
`400`		`Provide a contactId, email, or phone`	Neither `to` nor `contactId` was sent.
`400`	`invalid_from_address`	`Invalid from address`	`fromEmail` has no usable local part or domain.
`400`	`from_domain_not_verified`	`From address must use a verified sending domain`	The domain is missing from the workspace, or not verified.
`400`	`from_domain_blacklisted`	Names the domain and the blocklist	The sending domain is on the Spamhaus domain blocklist.
`400`	`sender_inbox_not_verified`	`This sender address has not been verified. Confirm it from the verification email before sending.`	No confirmed sender inbox for that local part.
`400`	`message_content_required`	`Manual email content requires subject and HTML`	Manual path with `subject` or `html` missing.
`400`	`content_mode_mismatch`	`Manual content mode cannot use a template`	`contentMode: "manual"` sent together with a `templateId`.
`400`	`template_channel_mismatch`	`Select an email template`	The template’s channel is not `email`.
`401`		`Missing tenant or API key` / `Invalid API key`	Auth headers missing or wrong.
`404`		`Contact not found`	`contactId` does not exist in this workspace.
`404`	`template_not_found`	`Template not found`	`templateId` does not exist in this workspace.
`429`			Rate limited.

The recipient is resolved before the From address is checked. A request that fails on sender_inbox_not_verified may still have created the contact named in to. Retrying the same request after verifying the mailbox reuses that contact rather than creating a second one.

Send SMS

POST /api/v1/public/messages/sms

Recipient

Provide to or contactId. If both are sent, contactId wins and to is ignored. If to does not match an existing contact, a new contact is created for that number.

string

Recipient phone number. Max 32 characters.

string

UUID of an existing contact. Returns 404 if it does not exist or has been deleted.

Send to in E.164 form, for example +972501234567. The contact lookup is an exact string match against the stored number, and stored numbers are always E.164. A local form such as 0501234567 will not match the existing contact, so Senderz tries to create a second one, normalises it to +972501234567, finds the number already taken and returns 409 with code contact_phone_taken.

Sender

string

required

The branded Sender name the SMS is sent from. Required. Max 11 characters. It must be one of your workspace’s own active Sender names. Matching is case-insensitive.

There is no default and no platform fallback. Omitting senderId fails validation. Sending an empty value, or one of the shared platform names SENDER, INFO or SHOP, returns 400 with code sender_id_required. Sending a name that is not approved for your workspace returns 400 with code sender_id_not_approved. Request and track Sender names at SMS Sender names, or list the approved ones with GET /public/sms-sender-ids.

Content

string

default:"manual"

Either manual or template. Same rules as email.

string

Message text. Max 1600 characters. Required on the manual path. Ignored when a templateId is present.

string

UUID of an SMS template in this workspace. Must be a template whose channel is sms.

object

Flat object of merge values for the template. Values may be strings, numbers, booleans or null.

Response

Status 202 Accepted.

string

The queued message’s UUID.

curl -X POST https://api.senderz.app/api/v1/public/messages/sms \
  -H "X-Sender-Tenant: acme-store" \
  -H "X-API-Key: $SENDERZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+972501234567",
    "senderId": "ACMESTORE",
    "body": "Acme Store: order 10482 shipped. Track it at acme-store.com/t/10482"
  }'

const res = await fetch("https://api.senderz.app/api/v1/public/messages/sms", {
  method: "POST",
  headers: {
    "X-Sender-Tenant": process.env.SENDERZ_WORKSPACE,
    "X-API-Key": process.env.SENDERZ_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+972501234567",
    senderId: "ACMESTORE",
    body: "Acme Store: order 10482 shipped.",
  }),
});
const { data } = await res.json();
console.log(data.messageId);

import os, requests

res = requests.post(
    "https://api.senderz.app/api/v1/public/messages/sms",
    headers={
        "X-Sender-Tenant": os.environ["SENDERZ_WORKSPACE"],
        "X-API-Key": os.environ["SENDERZ_API_KEY"],
    },
    json={
        "to": "+972501234567",
        "senderId": "ACMESTORE",
        "body": "Acme Store: order 10482 shipped.",
    },
)
print(res.json()["data"]["messageId"])

{
  "success": true,
  "data": { "messageId": "2b7d904a-1c63-4f52-a8e1-63d0c5a9f7b4" }
}

Credits

Transactional SMS is paid from the prepaid credit wallet, exactly like marketing SMS. See SMS for how credits are bought and counted. The wallet is checked twice.

Pre-flight, on the request

The rendered body is measured and priced at one credit per 268 billable characters, minimum one credit. If the workspace balance is lower than that, the request is rejected with 403 and code insufficient_credits before the recipient is resolved and before anything is queued. An under-funded workspace fails fast rather than silently dropping the message later.

A real hold, at send time

The pipeline places a hold for the same number of credits and commits it on provider acknowledgement. If the balance ran out between the two checks, the message ends with status skipped and failure reason insufficient_credits instead of returning an error, because the request already returned 202.

Non-GSM text, including Hebrew, is measured as Unicode, so the same character count costs more. Merge values are substituted before the count is taken, so a template with long merge values can cost more than the raw template text suggests.

Errors

Checks run in this order: Sender name, template rendering, credits, recipient.

Status	Code	Message	Cause
`400`		Validation message	Body failed validation, or carried an unknown property. `senderId` is required and capped at 11 characters.
`400`	`sender_id_required`	`SMS sender ID is required and must be approved`	`senderId` was empty, or one of the shared platform names.
`400`	`sender_id_not_approved`	`SMS sender ID is required and must be approved`	The name is not an `active` Sender name in this workspace.
`400`	`message_content_required`	`Manual SMS content requires a body`	Manual path with `body` missing.
`400`	`content_mode_mismatch`	`Manual content mode cannot use a template`	`contentMode: "manual"` sent together with a `templateId`.
`400`	`template_channel_mismatch`	`Select an SMS template`	The template’s channel is not `sms`.
`400`		`Provide a contactId, email, or phone`	Neither `to` nor `contactId` was sent.
`400`	`contact_phone_invalid`	`The phone number is not valid`	`to` could not be parsed into an E.164 number.
`401`		`Missing tenant or API key` / `Invalid API key`	Auth headers missing or wrong.
`403`	`insufficient_credits`	`Insufficient SMS credits`	Wallet balance is below the credit cost of this message.
`404`		`Contact not found`	`contactId` does not exist in this workspace.
`404`	`template_not_found`	`Template not found`	`templateId` does not exist in this workspace.
`409`	`contact_phone_taken`	`A contact with this phone already exists`	`to` was sent in a non-E.164 form that already exists as a contact. Resend in E.164.
`429`			Rate limited.

The Sender name is checked again at send time. If approval is revoked in the window between the 202 and the actual dispatch, the message ends with status failed and failure reason sender_id_not_approved. It is never quietly rerouted to a different Sender name.

Sending from a template

Pass a templateId on either endpoint to render a Senderz template server-side instead of supplying the body yourself. This keeps content out of your codebase and lets non-developers edit it.

Find the template

GET /public/templates lists templates as value and label pairs and accepts a channel filter. The value is the templateId.

Find its merge tags

GET /public/templates/{id}/merge-fields returns { "items": [...] }, the list of merge tag keys the template actually uses.

Send it

Pass templateId plus a flat templateFields object supplying the values for those keys.

How merge values resolve

A merge tag looks like {{orderNumber}}. A tag may carry a fallback after a pipe character, used when the value is missing or empty. Values are resolved from three sources, later ones winning:

The resolved contact: {{firstName}}, {{lastName}}, {{email}}, {{phone}}.
The contact’s custom properties, as {{custom.yourKey}}.
Your templateFields, as {{yourKey}}.

Because templateFields is applied last, a key that collides with a contact field overrides it for this one message. A templateFields value of null is skipped entirely, so the contact value or the tag’s fallback is used instead. Values that are objects or arrays are dropped rather than stringified, so nested data will render as empty.

On the SMS endpoint the merge context is built from an existing contact only. If to is a number Senderz has never seen, the contact is created after rendering, so contact tags such as {{firstName}} render as empty or fall back on that first message. The email endpoint resolves or creates the contact before rendering, so contact tags always resolve there. Supply the values through templateFields if you need them on a first-touch SMS.

curl -X POST https://api.senderz.app/api/v1/public/messages/email \
  -H "X-Sender-Tenant: acme-store" \
  -H "X-API-Key: $SENDERZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "dana@example.com",
    "fromEmail": "orders@acme-store.com",
    "contentMode": "template",
    "templateId": "6a1f0c74-2d38-49b1-b0a5-8e5c3f21d9aa",
    "templateFields": {
      "orderNumber": "10482",
      "trackingCode": "RR123456789IL",
      "itemCount": 3,
      "giftWrapped": false
    }
  }'

{
  "success": true,
  "data": { "messageId": "c04e7d31-9b8a-4a6f-84f2-0f1de5b73c92" }
}

Check delivery status

A 202 only confirms the message was accepted. These two endpoints report what the pipeline did with it.

Get one message

GET /api/v1/public/messages/{id}

string

required

The messageId returned by a send. Must be a UUID, otherwise the request fails validation.

string

Message UUID.

string

One of email, sms, push, voice, whatsapp.

string

One of queued, sent, delivered, bounced, complained, failed, suppressed, skipped.

string | null

Machine-readable reason when the message did not send. null on the happy path.

string | null

The sending provider’s own identifier, once the provider has accepted the message.

string

ISO 8601. When the message was queued.

string | null

ISO 8601. When the provider accepted it.

string | null

ISO 8601. When delivery was confirmed.

string

ISO 8601. Last status change.

curl https://api.senderz.app/api/v1/public/messages/9f3c1b2e-5a47-4d18-9c0b-7e2a6d4f8b31 \
  -H "X-Sender-Tenant: acme-store" \
  -H "X-API-Key: $SENDERZ_API_KEY"

{
  "success": true,
  "data": {
    "id": "9f3c1b2e-5a47-4d18-9c0b-7e2a6d4f8b31",
    "channel": "email",
    "status": "delivered",
    "failureReason": null,
    "providerMessageId": "0102019a4c7f31b8-6d2e4a05-1f3c-4b7a-9e18-2c5d0a7f4b63-000000",
    "createdAt": "2026-08-26T09:14:02.118Z",
    "sentAt": "2026-08-26T09:14:04.902Z",
    "deliveredAt": "2026-08-26T09:14:07.431Z",
    "updatedAt": "2026-08-26T09:14:07.431Z"
  }
}

{
  "success": true,
  "data": {
    "id": "2b7d904a-1c63-4f52-a8e1-63d0c5a9f7b4",
    "channel": "sms",
    "status": "skipped",
    "failureReason": "insufficient_credits",
    "providerMessageId": null,
    "createdAt": "2026-08-26T09:20:11.004Z",
    "sentAt": null,
    "deliveredAt": null,
    "updatedAt": "2026-08-26T09:20:11.588Z"
  }
}

Errors: 400 if id is not a UUID, 401 on bad auth, 404 Message not found if the id belongs to another workspace or does not exist, 429 if rate limited.

List messages

GET /api/v1/public/messages

Returns every message the workspace has sent, newest first. This is not limited to messages sent through this API: campaign and automation sends appear here too.

integer

default:"50"

Page size. Range 1 to 100.

integer

default:"0"

Records to skip.

limit and offset are the only accepted query parameters. There is no status, channel or date filter, and sending one returns 400. Filter client-side, or subscribe to webhooks for delivery events instead of polling.

The response is the standard paginated shape; each item has the same fields as a single message.

curl "https://api.senderz.app/api/v1/public/messages?limit=2&offset=0" \
  -H "X-Sender-Tenant: acme-store" \
  -H "X-API-Key: $SENDERZ_API_KEY"

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "2b7d904a-1c63-4f52-a8e1-63d0c5a9f7b4",
        "channel": "sms",
        "status": "sent",
        "failureReason": null,
        "providerMessageId": "019-88213470",
        "createdAt": "2026-08-26T09:20:11.004Z",
        "sentAt": "2026-08-26T09:20:12.640Z",
        "deliveredAt": null,
        "updatedAt": "2026-08-26T09:20:12.640Z"
      },
      {
        "id": "9f3c1b2e-5a47-4d18-9c0b-7e2a6d4f8b31",
        "channel": "email",
        "status": "delivered",
        "failureReason": null,
        "providerMessageId": "0102019a4c7f31b8-6d2e4a05-1f3c-4b7a-9e18-2c5d0a7f4b63-000000",
        "createdAt": "2026-08-26T09:14:02.118Z",
        "sentAt": "2026-08-26T09:14:04.902Z",
        "deliveredAt": "2026-08-26T09:14:07.431Z",
        "updatedAt": "2026-08-26T09:14:07.431Z"
      }
    ],
    "limit": 2,
    "offset": 0,
    "total": 341,
    "has_more": true,
    "next_cursor": "2"
  }
}

Reading a blocked message

When status is not sent or delivered, failureReason explains why. The values a transactional message can carry include:

`failureReason`	Status	Meaning
`hard_bounce`	`suppressed`	The address previously hard bounced and is suppressed.
`invalid_address`	`suppressed`	The address is suppressed as invalid.
`global_blocklist`	`suppressed`	The address is on the platform-wide blocklist.
`no_recipient`	`skipped`	The contact no longer has a usable address or number for this channel.
`insufficient_credits`	`skipped`	The SMS wallet ran out between acceptance and dispatch.
`sender_id_required`	`failed`	The Sender name was rejected at dispatch.
`sender_id_not_approved`	`failed`	Sender name approval was revoked after acceptance.
`ambiguous_delivery`	`failed`	The provider connection dropped after the message may already have been accepted. It is deliberately not retried, to avoid sending twice.

Rather than polling, subscribe to delivery webhooks and treat these endpoints as the reconciliation path.

Companion endpoints

Endpoint	Use it for
`GET /public/sender-addresses`	The exact `fromEmail` values that will pass verification.
`GET /public/sms-sender-ids`	The exact `senderId` values that are approved.
`GET /public/templates`	Template ids, filterable by channel.
`GET /public/templates/{id}/merge-fields`	The merge tag keys a template uses.
`GET /public/profiles`	Look up or create a contact before sending.
`POST /otp/send`	One-time passcodes over SMS or voice.

See Errors and rate limits for the shared error envelope and rate-limit behaviour.

Introduction

Ingest & transactional

Public API

What “transactional” changes, and what it does not

Send email

Recipient

Sender

Content

Response

Sender requirements

Errors

Send SMS

Recipient

Sender

Content

Response

Credits

Errors

Sending from a template

How merge values resolve

Check delivery status

Get one message

List messages

Reading a blocked message

Companion endpoints

​What “transactional” changes, and what it does not

​Send email

​Recipient

​Sender

​Content

​Response

​Sender requirements

​Errors

​Send SMS

​Recipient

​Sender

​Content

​Response

​Credits

​Errors

​Sending from a template

​How merge values resolve

​Check delivery status

​Get one message

​List messages

​Reading a blocked message

​Companion endpoints

What “transactional” changes, and what it does not

Send email

Recipient

Sender

Content

Response

Sender requirements

Errors

Send SMS

Recipient

Sender

Content

Response

Credits

Errors

Sending from a template

How merge values resolve

Check delivery status

Get one message

List messages

Reading a blocked message

Companion endpoints