Docs menu

Send email

POST https://mail.flinkk.io/api/v1/emails sends one email and returns its id. Authenticate with a domain API key (Settings, API Keys) as Authorization: Bearer <key>. A key can only send from the domain it was created for.

curl -X POST https://mail.flinkk.io/api/v1/emails \
  -H "Authorization: Bearer $FLINKK_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@yourdomain.com>",
    "to": ["customer@example.com"],
    "subject": "Welcome aboard",
    "html": "<p>Glad you are here.</p>"
  }'
# 200 { "id": "ckx9..." }

Body

Field	Type	Notes
`from`	string	A verified address on your domain, optionally `Name <address>`.
`to`, `cc`, `bcc`, `reply_to`	string or string[]	Up to 50. Everyone in `to` is on the same message.
`subject`	string	Required, unless you use a `template`.
`html`, `text`	string	Send either or both. With both, clients show one of them.
`template`, `variables`	string, object	Send a template by name instead of `html`/`text`.
`headers`	object	Custom headers (max 20). Routing and authentication headers are ignored.
`attachments`	array	`{ filename, content }` with base64 content, or `{ filename, path }` with a public URL. Max 10.

Safe retries

Send an Idempotency-Key header (up to 255 characters). If a request times out and you retry with the same key and body, you get the original id back with Idempotent-Replayed: true and nothing is sent twice. The same key with a different body is a 409. Keys last 24 hours.

Batch and status

POST /api/v1/emails/batch takes an array of up to 100 emails. Every item is validated first, so one bad item sends nothing.
GET /api/v1/emails/{id} returns the email, its latest delivery status and its event timeline (sent, delivered, bounced, opened, clicked).
GET /api/v1/emails searches the log by status, recipient, subject and date. To be told about delivery events instead of polling, use webhooks.

Errors

Errors are { "error": { "code", "message" } }.

Status	Meaning
400	Invalid request (the message names the field).
401	Missing or invalid key.
403	The key is not valid for the `from` domain.
409	Idempotency key reused with a different body, or still in progress.
422	`recipient_suppressed`: an address bounced permanently or complained earlier. See Suppression list.
429	Rate limit (120 requests a minute per key, see `Retry-After`) or the daily sending limit.

The full contract is the Email API OpenAPI spec.

Older endpoint

POST /api/client/email/send with an api-key header keeps working for existing integrations. New code should use /api/v1/emails.

On this page: Body · Safe retries · Batch and status · Errors · Older endpoint