Send

Send an email

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.

post/v1/send

Request

  • Base URL: https://api.volanea.com
  • URL: https://api.volanea.com/v1/send
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

A unique key for this logical send; a repeat replays the stored response instead of sending again.

Request body

subjectstring

Subject line. Supports {{variable}} placeholders, with fallbacks: {{firstName | "there"}}.

htmlstring

HTML body. Supports {{variable}} placeholders, with fallbacks: {{firstName | "there"}}.

textstring

Plain-text body (wrapped in <pre> when no HTML is given).

templateIdstring

Send using a stored template instead of inline content.

variablesobject

Values 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.

fromstring email

From address. Must belong to a verified domain (unless in test mode). Defaults to the template's from address, or hello@ your first verified domain.

fromNamestring
replyTostring email

Sets a Reply-To header.

headersobject

Custom email headers to include on the message.

sendAtstring date-time

Schedule delivery for a future time (ISO 8601 with offset). The message is stored queued with a scheduledFor — list the pending ones with GET /v1/emails?status=scheduled, stop one with DELETE /v1/emails/{id}.

createContactboolean

Set false to skip auto-creating a contact for unknown recipients (default true).

type'transactional' | 'marketing'

Marketing messages get the unsubscribe footer and skip contacts who have unsubscribed. Defaults to the template's type, or transactional for inline content — so promotional copy sent as inline html must set this explicitly or it bypasses the unsubscribe check.

Response

Per-recipient results.

testModeboolean required
replaytrue

Present and true ONLY on an idempotent replay — absent on a first send, never false. Nothing was dispatched for this request; messages is the stored response from the original call, so the ids in it are the original ids. Test data.replay === true, or read the X-Idempotent-Replay header.

Changes

No recorded changes to this operation across all 1 revision of this API.