---
title: "Send mail"
method: POST
path: "/mailboxes/{address}/send"
tags: ["Mail"]
---

# Send mail

`POST /mailboxes/{address}/send`

## Request

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

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

## Path parameters

- `address` string, required

## Headers

- `Idempotency-Key` string

## Request body

- SendMailRequest: Request body for sending an email. Provide either `subject` with `html`/`text`, or `templateAlias` to send a stored template.
  - `to` string, required: Comma-separated recipient addresses
  - `cc` string: Comma-separated CC addresses
  - `bcc` string: Comma-separated BCC addresses
  - `subject` string: Required unless templateAlias is given, which supplies its own subject
  - `text` string: Plain-text body
  - `html` string: HTML body
  - `templateAlias` string: Alias of a transactional template to send. Supplies the subject and body, so `subject`, `html` and `text` are ignored.
  - `variables` object: 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.
  - `replyTo` string: Reply-To address — replies go here instead of the sending mailbox
  - `fromName` string: From display name for this message only; the mailbox's stored name is unchanged. Default: the mailbox's name, else the domain default.
  - `inReplyTo` string: Message-ID of the message being replied to
  - `references` string: Space-separated Message-IDs for threading
  - `attachments` object[]: File attachments (base64-encoded)
    - `filename` string, required
    - `content` string, required: Base64-encoded file content
    - `contentType` string, required
  - `sendAt` string, 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.

## Response `200`

Mail sent

- object
  - `success` boolean
  - `data` SendMailResponse: Confirmation that the email was sent
    - `messageId` string: The Message-ID of the sent email
    - `sent` boolean
    - `hint` string: Present when the email went out with no display name, so recipients saw only the address. Says how to set one.
    - `replayed` boolean: Present and true when an Idempotency-Key matched an earlier request and nothing was sent again
    - `scheduled` object: Present when `sendAt` was given: the send is waiting, `sent` is false and there is no `messageId` yet
      - `id` string: Use it to cancel the send
      - `uid` integer: The draft that will be sent, in the Drafts folder
      - `sendAt` string, date-time
      - `status` 'scheduled' | 'sending' | 'retrying' | 'sent' | 'cancelled' | 'failed'
      - `reason` string: Why it was cancelled or failed
      - `messageId` string: Message-ID of the sent email, once sent
      - `createdAt` string, date-time

## Other responses

- `401`: Missing or invalid API key
- `402`: The account's plan does not include the API (`plan_required`)
- `403`: The key lacks the required scope
- `404`: Resource not found
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/faivelo/apis/faivelo-api.md) · [All operations](https://skmtc.dev/faivelo/apis/faivelo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/faivelo/apis/faivelo-api/revisions/a7413ddea5d1?raw)