Send an email

POST/v1/send

Secret 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[]required

    Recipient address (optionally with a display name), or an array of 1–50 recipients (each gets its own message).

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

  • fromemail

    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
  • replyToemail

    Sets a Reply-To header.

  • headersobject

    Custom email headers to include on the message.

  • attachmentsobject[]

    Up to 10 attachments per message. Total request size is capped at 10 MiB.

    • filenamestringrequired
    • contentstringrequired

      Base64-encoded file content.

    • contentTypestring
  • sendAtdate-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).

  • typeenum

    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.

    transactionalmarketing

Response

Per-recipient results.

  • messagesobject | object[]required
  • testModebooleanrequired
  • replayenum

    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.

    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