API Documentation - Destinatarium

Quick start

One request and your email is on its way

Destinatarium exposes a REST API over HTTPS. Before sending, prepare these three pieces.

01
Verify your domain
The domain used in from must be active in your account.
02
Create an API key
The key needs the emails:send permission.
03
Send the request
Use JSON and include at least text or html content.

Authentication

Authorize every request

Send your API key as a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Keep the key on your server

Do not expose your API key in browser JavaScript, mobile apps, or public repositories.

Emails

Send an email

Creates a transactional email and schedules it for delivery.

POST https://api.destinatarium.com/api/v1/emails/

cURL

curl --request POST \
  --url https://api.destinatarium.com/api/v1/emails/ \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-1842-confirmation' \
  --data '{
    "from": "My App <notifications@your-domain.com>",
    "to": "user@example.com",
    "subject": "Your verification code",
    "html": "<h1>123456</h1>",
    "text": "Your verification code is 123456",
    "scheduled_at": "2099-01-15T09:30:00+01:00",
    "scheduled_timezone": "Europe/Paris"
  }'

Retry without duplicates

The optional Idempotency-Key header identifies the operation for 24 hours. Generate a new key for each operation and reuse it, with the same JSON, only for that operation's retries.

JSON body

Main parameters

Unknown fields are rejected to help you catch integration mistakes.

Parameters accepted in the JSON body when sending an email
Field	Type	Description
`from`Required	`string`	One sender address, with an optional display name. The domain must be verified and active.
`to`Required	`string \| string[]`	One or more recipients. Up to 50 in this field.
`subject`Required	`string`	A non-empty subject of up to 998 characters.
`html`Conditional	`string`	HTML content. Required when `text` is not provided.
`text`Conditional	`string`	Plain-text content. Required when `html` is not provided.
`cc`, `bcc`Optional	`string \| string[]`	Carbon-copy or blind-carbon-copy recipients. Up to 50 per field and 100 unique recipients total across to, cc, and bcc.
`reply_to`Optional	`string \| string[]`	A single address where replies will be sent.
`scheduled_at`Optional	`string`	A future RFC 3339 timestamp. It must include `Z` or an explicit numeric UTC offset.
`scheduled_timezone`Optional	`string`	The IANA time zone used to schedule delivery, for example `Europe/Paris`. Requires `scheduled_at`, whose offset must match.
`headers`Optional	`object`	Up to 100 custom, non-reserved headers with string values; 64 KiB total maximum.
`attachments`Optional	`object[]`	Up to 20 attachments. Each requires `filename` and exactly one of `content` (Base64) or `path` (public HTTPS URL); supports `content_type` and `content_id`.

Response

Request accepted

A valid request returns HTTP 200, the unique identifier, and normalized scheduling data.

200 OK application/json

JSON

{
  "data": {
    "email": {
      "id": "0198a1b2-c3d4-7000-8000-000000000001",
      "status": "scheduled",
      "scheduled_at": "2099-01-15T08:30:00.000Z",
      "scheduled_timezone": "Europe/Paris"
    }
  },
  "status": "success",
  "statusCode": "200"
}

“Accepted” means Destinatarium created and scheduled the email. Processing is asynchronous and does not guarantee delivery or inbox placement.

Errors

Status codes to handle

Error responses include a stable error.errorKey so your integration can decide what to do.

400

The JSON or one of its fields is invalid.

401

The API key is missing or invalid.

403

The key lacks permission or the sender domain is not active.

409

The idempotent operation is still in progress or the key was reused with a different payload.

413

The body or complete message exceeds the allowed size.

422

A recognized field shape cannot be processed yet.

429

The request limit or email quota has been reached.

5xx

Some 500, 502, 503, or 504 errors may be transient; retry with backoff and the same idempotency key.

Ready to send?

Create your API key and make the first request.

Start free

Send email from your application