API Reference · Emails

Send email

Send a transactional email. The call is accepted immediately and the message is queued for delivery; track it via events or webhooks.

POST/v1/messages

Headers

Authorizationstringrequired
Your API key as a bearer token: Bearer rk_your_api_key. You can also use the X-Api-Key header.
Idempotency-Keystringoptional
Recommended. Retries with the same key return the original message instead of sending twice. Reusing a key with different attachments returns 409 IDEMPOTENCY_KEY_REUSED.

Body parameters

tostringrequired
Recipient email address.
fromstringoptional
Sender on one of your verified domains, e.g. Acme <noreply@acme.co>. Defaults to your domain's noreply@.
subjectstringoptional
Email subject. Required unless you send from a template.
htmlstringoptional
The HTML version of the message. Provide html, text, or a template.
textstringoptional
The plain-text version of the message.
templateIdstringoptional
Render the message from a saved template's current version.
templateVersionIdstringoptional
Pin a specific template version instead of the current one.
variablesobjectoptional
Values for {{ placeholders }} in the template.
attachmentsarrayoptional
Files to attach, each { filename, contentType, contentBase64 }. Up to 10 files and 7 MB in total before encoding, and the whole message must fit in 10 MB once encoded. Allowed types: text/calendar (for example invite.ics), text/plain, text/csv, application/pdf, application/json, application/rtf, application/zip, application/gzip, common images (PNG, JPEG, GIF, WebP, BMP, TIFF) and Word, Excel and PowerPoint documents without macros. Anything else, or a filename with an executable extension, returns 422.

Request

curl -X POST https://api.raanse.com/v1/messages \
  -H "Authorization: Bearer rk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
        "from": "Acme <noreply@acme.co>",
        "to": "customer@example.com",
        "subject": "Welcome to Acme",
        "html": "<h1>Hello 👋</h1><p>Thanks for signing up.</p>"
      }'

Response

201
{
  "success": true,
  "message": "Resource created",
  "statusCode": 201,
  "data": {
    "id": "01JABCDXYZ0000000000000000",
    "status": "Queued",
    "to": "customer@example.com",
    "fromAddress": "noreply@acme.co",
    "subject": "Welcome to Acme",
    "providerMessageId": null,
    "templateVersionId": null,
    "attempts": 0,
    "createdAt": "2026-07-02T12:00:00Z"
  }
}