Mail

Send mail

Sends an email from the specified mailbox. Counts against the monthly send limit. Send an Idempotency-Key header to make a retry safe: a repeat of a finished request returns the first result with replayed: true instead of sending again. With sendAt the message is saved in Drafts and sent at that time instead; the response then carries sent: false and a scheduled object. Requires scope mail:send.

post/mailboxes/{address}/send

Request

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

Path parameters

addressstring required

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

Headers

Idempotency-Keystring

A unique value you choose (a UUID works), up to 256 characters. Repeating a request with the same key within 24 hours returns the first result instead of doing the work twice. The same key with a different body is a 422; a repeat while the first request is still running is a 409.

Request body

tostring required

Comma-separated recipient addresses

ccstring

Comma-separated CC addresses

bccstring

Comma-separated BCC addresses

subjectstring

Required unless templateAlias is given, which supplies its own subject

textstring

Plain-text body

htmlstring

HTML body

templateAliasstring

Alias of a transactional template to send. Supplies the subject and body, so subject, html and text are ignored.

variablesobject

Values for the template's {{variables}}. Every variable the template uses must be present, or the request fails with 422 and nothing is sent. Values are HTML-escaped before they are inserted.

A value may also be an array of objects, which fills a repeating block. That is how a receipt carries a different number of line items on every send: the template describes one row, and each array entry renders one. An empty array is allowed and renders no rows.

replyTostring

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

fromNamestring

From display name for this message only; the mailbox's stored name is unchanged. Default: the mailbox's name, else the domain default.

inReplyTostring

Message-ID of the message being replied to

referencesstring

Space-separated Message-IDs for threading

sendAtstring date-time

Send later instead of now: ISO 8601 with a timezone, at least one minute and at most 30 days ahead. The message waits in the mailbox's Drafts folder until then.

Example request

{
  "to": "alice@example.com, bob@example.com",
  "subject": "Monthly report",
  "templateAlias": "receipt",
  "variables": {
    "name": "Blair",
    "orderId": "10428",
    "total": "$38.49",
    "items": [
      {
        "label": "Annual plan",
        "value": "$32.08"
      },
      {
        "label": "Tax",
        "value": "$6.41"
      }
    ]
  },
  "attachments": [
    {
      "filename": "report.pdf",
      "contentType": "application/pdf"
    }
  ],
  "sendAt": "2026-10-05T09:00:00Z"
}

Response

Mail sent

successboolean

Example response

{
  "success": true,
  "data": {
    "sent": true,
    "scheduled": {
      "uid": 42
    }
  }
}

Changes

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