Sending with the REST API

The REST send endpoint is the easiest way to send transactional email from a modern stack. It's available on paid plans only and requires an API key.

Endpoint: https://api.sesmetric.com/v1/send

1. Create an API key

In the dashboard go to API keys → New key. Pick a name, leave the scope as email:send, click Generate. The raw sk_live_… value is shown once — copy it now.

2. Authentication

Pass the key as a bearer token:

Authorization: Bearer sk_live_…

Or, equivalently:

X-API-Key: sk_live_…

3. Basic send

curl -X POST https://api.sesmetric.com/v1/send \
  -H "Authorization: Bearer $SM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_email": "no-reply@example.com",
    "to": ["alex@customer.com"],
    "subject": "Welcome",
    "html": "<p>Welcome to Example.</p>"
  }'

Response:

{ "id": "msg_a7f0c12e9bd4", "status": "queued" }

4. Send with a system template

The catalog at /templates lists ready-to-use system templates (password reset, invoice issued, payment failed, etc.). Pass the slug and variables:

curl -X POST https://api.sesmetric.com/v1/send \
  -H "Authorization: Bearer $SM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_email": "no-reply@example.com",
    "to": ["alex@customer.com"],
    "template": "password-reset",
    "variables": {
      "user": { "first_name": "Alex", "email": "alex@customer.com" },
      "reset_url": "https://app.example.com/reset?token=abc123"
    }
  }'

Your branding (logo, colors, footer) is auto-injected from Dashboard → Branding. Subject and body are rendered with Jinja2.

5. Attachments

{
  "attachments": [
    {
      "filename": "invoice-1042.pdf",
      "content_type": "application/pdf",
      "content_base64": "JVBERi0xLjQ..."
    }
  ]
}

Total payload limit: 25 MB.

6. Request fields

Field	Type	Notes
from_email	string	Must be a verified identity in your account.
to	string[]	1–50 recipients.
cc, bcc	string[]	Optional.
reply_to	string	Optional.
subject	string	Required unless template is set.
html, text	string	At least one is required without template.
template	string	Slug of a system template or user template.
variables	object	Jinja2 context for the template.
headers	object	Custom headers (max 16).
tags	string[]	Free-form labels for analytics filtering.
attachments	object[]	base64-encoded content + content_type.

7. Errors

Code	Meaning
400	Validation failed — check error.detail.
401	Missing or revoked key.
402	Account is not on a paid plan.
403	Key missing email:send scope or identity not verified.
429	Rate limited — back off + retry.
500	Transient. Retry with exponential backoff.