---
title: "Send an email"
method: POST
path: "/api/v1/send"
tags: ["Sending"]
---

# Send an email

`POST /api/v1/send`

## Request

- Base URL: `https://supermailos.com`
- URL: `https://supermailos.com/api/v1/send`
- Auth: HTTP bearer

Send a new message as one of your mailboxes. Every guardrail of the app applies: verified domain, suppression list, per-mailbox/workspace hourly limits, new-domain warm-up, storage quota. Supports Idempotency-Key.

## Headers

- `Idempotency-Key` string

## Request body

- SendRequest
  - `from` string, email, required: A mailbox (not an alias) the key can send as.
  - `to` union, required: Comma-separated string or array of addresses.
    - string
    - string[]
  - `cc` union
    - string
    - string[]
  - `bcc` union
    - string
    - string[]
  - `subject` string
  - `text` string: Plain-text body. `text` or `html` is required; together at most 1 MB.
  - `html` string: HTML body (scripts, handlers and javascript: URLs are stripped).
  - `idempotencyKey` string: Alternative to the Idempotency-Key header.

## Response `202`

Accepted for delivery (or a replayed earlier response).

- union
  - SendResponse
    - `ok` true, required
    - `status` 'sent': Present on sends from an agent inbox.
    - `id` string, required: RFC Message-ID (kept for compatibility; same as `messageId`).
    - `messageId` string, required: RFC 5322 Message-ID of the sent message.
    - `emailId` string, nullable, required: Internal id of the stored Sent copy.
    - `threadId` string, required
    - `mailboxId` string, required
    - `from` string, email, required
  - PendingSendResponse: An agent inbox's email that waits for a person; nothing was sent yet.
    - `ok` true, required
    - `status` 'pending_approval', required
    - `approvalId` string, required: `GET /approvals/{approvalId}` for what became of it.
    - `reasons` string[], required: Why it waits, in plain words.
    - `expiresAt` string, date-time, required
    - `mailboxId` string, required
    - `from` string, email, required

## Other responses

- `400`: The request is malformed.
- `401`: Missing, invalid or revoked API key.
- `403`: The key lacks the scope (`missing_scope`) or the access (`forbidden`).
- `404`: Not found — or not reachable with this key.
- `409`: A request with this Idempotency-Key is still in progress.
- `413`: Body over 1 MB.
- `422`: Valid JSON the server can't act on (e.g. unverified domain, suppressed recipient, reused Idempotency-Key).
- `423`: Sending is paused for this mailbox or workspace.
- `429`: Too many requests.
- `502`: The mail server didn't accept the message; nothing was sent. Safe to retry.
- `507`: The mailbox is out of storage.

---

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