Mail

Send one email to many recipients

Sends one templated email to many recipients in a single call. {{field}} tokens in subject, text and html are filled from each recipient's fields (a missing field renders empty; HTML values are escaped). Faivelo queues the batch, sends it at the plan's pace and tracks every recipient: the response is immediate (202) with the batch and each recipient as queued; poll GET /mailboxes/{address}/send-batch/{id} or listen to the email.delivered / email.bounced / email.complained webhooks, which carry batch_id. Every recipient counts against the monthly send allowance like a single send. The whole batch is accepted or refused: more recipients than the plan's per-call cap (422 batch_too_large; GET /usage reports the cap as batch.recipientsPerCall) or than the remaining allowance (403 send_limit_reached) queues nothing. Per-call caps: Free agents tier 20, Growth/Pro/Business 100, Developer 200, Scale 1,000 (the larger of the mail plan's and the Agents plan's applies; Starter has none). idempotencyKey is required: a repeat with the same key returns the original batch (replayed: true) instead of sending again. Requires scope mail:send; agent keys may only use mailboxes they were granted.

post/mailboxes/{address}/send-batch

Request

  • Base URL: https://faivelo.com/api/v1
  • URL: https://faivelo.com/api/v1/mailboxes/{address}/send-batch
  • Auth: HTTP bearer

Path parameters

addressstring required

Full mailbox address, e.g. user@yourdomain.com

Request body

subjectstring required

Subject line; may contain {{field}} tokens

textstring

Plain-text body; may contain {{field}} tokens. Required unless html is given.

htmlstring

HTML body; may contain {{field}} tokens (values are HTML-escaped). Required unless text is given.

replyTostring

Reply-To address — replies go here instead of the sending mailbox

fromNamestring

From display name for this batch only; the mailbox's stored name is unchanged

idempotencyKeystring required

Required. Unique to this batch (derive it from the event, not a timestamp): a repeat with the same key returns the original batch instead of sending again; the same key with a different request is a 422.

labelsstring[]

Free-form tags kept on the batch and echoed in its status and webhook events

Example request

{
  "subject": "Hi {{first_name}}, the beta opens Monday",
  "recipients": [
    {
      "email": "ada@example.com",
      "fields": {
        "first_name": "Ada",
        "code": "ADA-1"
      }
    }
  ],
  "idempotencyKey": "beta-invites-2026-10",
  "labels": [
    "beta",
    "invite"
  ]
}

Response

Batch queued (or 200 with replayed: true when the idempotency key matched an earlier batch)

successboolean

Example response

{
  "success": true,
  "data": {
    "mailbox": "updates@yourdomain.com"
  }
}

Changes

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