Send an email
/v1/sendSecret key — sk_… or sk_test_… · Base URL https://api.volanea.com
Send one message (to one address or up to 50). Runs the full pipeline: suppression check, contact upsert, template render, tracking instrumentation, and dispatch. Supports scheduling via sendAt and safe retries via the Idempotency-Key header.
Reading a failure — every failure of the send pipeline keeps the top-level code send_failed, at whatever HTTP status fits (404 for a missing template, 403 for an unverified from domain). The specific cause is in details[0].code — e.g. template_not_found. Branch on code === "send_failed" for "the send did not happen", then read details[0].code when you need to tell a wrong template id in your config from a transient provider problem worth retrying. details is absent when there is no cause more specific than the message.
A 200 does not mean delivered. Each entry in messages is either an accepted message (with an id and a status) or a skip ({ to, skipped } — suppressed, unsubscribed, over quota). Skips are part of a 200 body. Accepted messages are queued: the provider round trip happens after this response returns, so track final delivery with GET /v1/emails/{id} or the email.* webhooks, not from this call.
Body
Required · application/json
toemail | object | email | object[]requiredRecipient address (optionally with a display name), or an array of 1–50 recipients (each gets its own message).
subjectstringSubject line. Supports
{{variable}}placeholders, with fallbacks:{{firstName | "there"}}.htmlstringHTML body. Supports
{{variable}}placeholders, with fallbacks:{{firstName | "there"}}.textstringPlain-text body (wrapped in
<pre>when no HTML is given).templateIdstringSend using a stored template instead of inline content.
variablesobjectValues for
{{variable}}placeholders in the subject and body. A name you omit falls back to the same-named contact field, then to the placeholder's own| "default"if it has one, then to nothing.fromemailFrom address. Must belong to a verified domain (unless in test mode). Defaults to the template's from address, or hello@ your first verified domain.
fromNamestringreplyToemailSets a Reply-To header.
headersobjectCustom email headers to include on the message.
attachmentsobject[]Up to 10 attachments per message. Total request size is capped at 10 MiB.
filenamestringrequiredcontentstringrequiredBase64-encoded file content.
contentTypestring
sendAtdate-timeSchedule delivery for a future time (ISO 8601 with offset). The message is stored
queuedwith ascheduledFor— list the pending ones withGET /v1/emails?status=scheduled, stop one withDELETE /v1/emails/{id}.createContactbooleanSet
falseto skip auto-creating a contact for unknown recipients (defaulttrue).typeenumMarketing messages get the unsubscribe footer and skip contacts who have unsubscribed. Defaults to the template's type, or
transactionalfor inline content — so promotional copy sent as inlinehtmlmust set this explicitly or it bypasses the unsubscribe check.transactionalmarketing
Response
Per-recipient results.
messagesobject | object[]requiredtestModebooleanrequiredreplayenumPresent and
trueONLY on an idempotent replay — absent on a first send, neverfalse. Nothing was dispatched for this request;messagesis the stored response from the original call, so the ids in it are the original ids. Testdata.replay === true, or read theX-Idempotent-Replayheader.true
Errors
Every failure returns the standard envelope — branch on `code`, never on the wording of `error`.
401Missing or invalid API key.403The from domain is not verified, or the project has no verified domain at all. `code` is `send_failed` — the domain is named in `error`.404Template not found. `code` is `send_failed`; `details[0].code` is `template_not_found`.409`Idempotency-Key` reused with a different body (`idempotency_key_reused`) — nothing was sent.422Request validation failed (code `validation_error`, 422).429Per-project send rate limit (`rate_limited`). Retry after the `Retry-After` header.
Request
curl https://api.volanea.com/v1/send \
-X POST \
-H "Authorization: Bearer sk_..." \
-H "Content-Type: application/json" \
-d '{
"to": "ada@example.com",
"subject": "Your order shipped",
"html": "<p>On its way, {{firstName}}.</p>"
}'Response
200 · application/json
{
"success": true,
"data": {
"messages": [
{
"id": "<id>",
"to": "ada@example.com",
"status": "sent"
}
],
"testMode": true,
"replay": true
}
}92 endpoints · OpenAPI document