Send a transactional email

Send with a template

Instead of { type: "raw", subject, html, text }, content can carry a template already saved in Templates, with type: "template":

curl -X POST https://api.e-comms.dev/v1/email \
  -H "Authorization: Bearer ek_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "welcome-template-ana-2026-09-19",
    "to": ["ana@example.com"],
    "from": "hello@yourcompany.com",
    "content": {
      "type": "template",
      "templateId": "01a0ba31-6b2c-7a9f-8c3d-2e5f7a1b9c60",
      "variables": { "firstName": "Ana", "planName": "Pro" }
    }
  }'

const response = await fetch("https://api.e-comms.dev/v1/email", {
  method: "POST",
  headers: {
    Authorization: "Bearer ek_live_<your-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    idempotencyKey: "welcome-template-ana-2026-09-19",
    to: ["ana@example.com"],
    from: "hello@yourcompany.com",
    content: {
      type: "template",
      templateId: "01a0ba31-6b2c-7a9f-8c3d-2e5f7a1b9c60",
      variables: { firstName: "Ana", planName: "Pro" },
    },
  }),
})

const body = await response.json()

import requests

response = requests.post(
    "https://api.e-comms.dev/v1/email",
    headers={"Authorization": "Bearer ek_live_<your-key>"},
    json={
        "idempotencyKey": "welcome-template-ana-2026-09-19",
        "to": ["ana@example.com"],
        "from": "hello@yourcompany.com",
        "content": {
            "type": "template",
            "templateId": "01a0ba31-6b2c-7a9f-8c3d-2e5f7a1b9c60",
            "variables": {"firstName": "Ana", "planName": "Pro"},
        },
    },
)

body = response.json()

The response has the same shape as any other send’s.

Where the templateId comes from

Copy it from the template itself. Open the template in Templates → edit and use the copy button beside the id under its name, or open the actions menu of its row in the templates list and choose Copy ID. Any role that can see templates can copy it.

Only an active template can be used to send. An inactive one answers conflict — the same code a repeated idempotencyKey with a different body answers.

What a missing variable answers

If the template’s document uses a merge tag that is not among variables’s own keys, the call answers bad_request, naming the tag in details:

{
  "code": "bad_request",
  "message": "Unknown merge tag key: planName",
  "details": {
    "keys": ["planName"]
  },
  "requestId": "01a0ba31-3fe4-7cc4-a1c6-64bdaaa5d99c"
}

There is no partial substitution and no silent default: the template compiles whole, or nothing is sent at all.

Notes

• from has to match a sender exactly, not just a domain: register one in the app’s own Sending settings before calling this endpoint. A sender proved with its own one-time code sends as written; one whose domain is not yet authenticated there still sends, with the local part kept and the domain substituted, replyTo carrying the real address unless the call already supplied one.
• Rate limit: 100 requests per second per key, across all of /v1. Over that it answers 429 rate_limited, with no Retry-After header and no quota header at all — the limit is never announced ahead of time.
• /v1 answers no CORS header at all. This surface is not callable from a browser, only server to server.
• The body is strict: a field outside this list answers validation_failed, never silently ignored.
• idempotencyKey is a body attribute, not a header. The same key with the same body returns exactly the response already resolved, without re-queuing the send. The same key with a different body answers 409 conflict. Two concurrent requests with the same key: the one that loses the race also answers 409, never a duplicate send.

The error reference carries the rest of the codes this surface can answer with, including the ones no single route declares on its own.