Send a transactional email

Sends one message to one recipient, from a stored template or inline HTML. It ignores opt-outs and carries no unsubscribe header, so never use it for marketing.

Authorization

AuthorizationRequiredBearer <token>

API key as Bearer token: Authorization: Bearer sk_live_.... Use sk_live_ prefixed keys for production data and sk_test_ prefixed keys for sandbox/test data.

In: header

X-API-Key<token>

API key via header: X-API-Key: sk_live_.... Use sk_live_ prefixed keys for production data and sk_test_ prefixed keys for sandbox/test data.

In: header

Request Body

application/jsonRequired

toRequiredstring

Format: "email"

templateSlugstring

Slug of a stored transactional template. Mutually exclusive with html.

htmlstring

Inline body. Requires subject. Max 256 KB. Every {{token}} must have a value in variables or a {{token|fallback}} default, otherwise the request is rejected rather than sent with a blank.

subjectstring

Required for inline sends. Optional on a template send, where it overrides the template's subject. The body cannot be overridden.

textstring

Plain-text alternative. Generated from the HTML when omitted.

variablesobject

Values substituted into {{name}} tokens. Values are HTML-escaped into the body.

replyTostring

Format: "email"

fromNamestring

channelIdstring

Sending channel to use. Defaults to the template's channel, then to the workspace's oldest verified channel.

Format: "uuid"

idempotencyKeystring

Send this on anything a retry could duplicate.

Repeating a key with the same payload returns the original message and sends nothing. If that original failed, the repeat is a 409 IDEMPOTENT_REPLAY naming the key — not a replay of the old error — because a key identifies one attempt; use a new key to send again.

Repeating a key with a different payload is a 409 IDEMPOTENCY_KEY_REUSED. The payload is compared on recipient, rendered subject and rendered body.

contactIdstring

Optional CRM contact to link the message to.

Format: "uuid"

curl -X POST "https://clientsphere.io/api/v1/transactional/send" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "templateSlug": "order-receipt",
    "html": "<p>Hi {{firstName}}, order {{orderId}} is confirmed.</p>",
    "subject": "Your receipt {{orderId}}",
    "text": "string",
    "variables": {
      "firstName": "Ada",
      "orderId": "A-1234"
    },
    "replyTo": "user@example.com",
    "fromName": "string",
    "channelId": "5f6d08bc-455a-4532-98b8-19e2cee51160",
    "idempotencyKey": "order-1234-receipt",
    "contactId": "b5ec5d98-4bee-4da1-ad24-dde86346cb1d"
  }'

Sent

{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "rejected",
    "to": "user@example.com",
    "subject": "string",
    "templateSlug": "string",
    "from": "user@example.com",
    "fromName": "string",
    "replyTo": "string",
    "messageId": "string",
    "idempotencyKey": "string",
    "source": "api",
    "attemptCount": 0,
    "error": "string",
    "errorReason": "string",
    "bounceType": "Permanent",
    "createdAt": "2019-08-24T14:15:22Z",
    "sentAt": "2019-08-24T14:15:22Z",
    "deliveredAt": "2019-08-24T14:15:22Z",
    "bouncedAt": "2019-08-24T14:15:22Z",
    "complainedAt": "2019-08-24T14:15:22Z"
  }
}

Send a transactional email

Authorization

Request Body

Response

TypeScript