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

# Send an email

`POST /api/v1/send`

## Request

- Base URL: `https://postfleet.ai`
- URL: `https://postfleet.ai/api/v1/send`
- Auth: HTTP bearer

The single outbound path for direct and MCP sends. Requires an `api` or `mcp` key with `can_send`. Supply an optional `client_id` for idempotent duplicate protection (replay table). On a mailbox with `require_approval` enabled, the send is turned into a forced draft (`202`) instead of delivering. `to` is required unless `reply_to_message_id` is supplied; `to` must be exactly one address (multi-recipient is rejected `400`).

## Request body

- SendRequest
  - `mailbox_id` string, required: Mailbox to send from. A mailbox-bound key must match this.
  - `text` string, required: Plain-text body.
  - `to` string: Single recipient address. Required unless replying; must be exactly one address.
  - `subject` string
  - `reply_to_message_id` string: Reply in-thread to an existing message; resolves `to`/`subject`/thread from the original.
  - `client_id` string: Idempotency key for duplicate protection. Must not start with `draft:` (reserved).
  - `attachments` union[]: Optional files to attach. Each item is exactly one of base64 `content` or an HTTPS `url` (fetched at send time). Filename and content_type are optional. At most 20 files; 6 MB total inline, 30 MB total URL-backed. Bytes are not echoed on draft reads.
    - union
      - object
        - `filename` string: Basename only — no path separators. Derived from the URL path, or `attachment`, when omitted.
        - `content` string, required: File bytes, standard base64.
        - `content_type` string: MIME type. Defaults to application/octet-stream, or the URL response Content-Type.
      - object
        - `filename` string: Basename only — no path separators. Derived from the URL path, or `attachment`, when omitted.
        - `url` string, required: HTTPS URL fetched at send time. Not forwarded to the provider.
        - `content_type` string: MIME type. Defaults to application/octet-stream, or the URL response Content-Type.

## Response `200`

Idempotent replay: this `client_id` was already used with the same payload for a completed send; the stored result is returned verbatim.

- SendResult
  - `id` string, required: Stored message id.
  - `thread_id` string, required
  - `provider_message_id` string, required

## Other responses

- `201`: Sent.
- `202`: Mailbox requires approval — the send was queued as a forced draft awaiting a human.
- `400`: Validation error (missing `mailbox_id`/`text`, bad `client_id`, `to` not a single address, missing `to` when not replying) or a permanent provider rejection (`{retryable:false}`).
- `401`: Missing or invalid bearer token, or a key whose scope is not permitted for this endpoint.
- `402`: Monthly send quota exhausted (terminal for this `client_id`).
- `403`: Key cannot send / is scoped to a different mailbox (`code:key_scope`), recipient blocked by a send list (`code:send_blocked_by_list`), account sending is held (`code:sending_held` or `code:account_send_held`; owner review required), or a custom-domain entitlement rejection.
- `404`: Mailbox not found, or (when replying) the original message was not found / not visible to a mailbox-bound key.
- `409`: Idempotency conflict: same `client_id` with a different payload (`idempotency_conflict`), or a send with this `client_id` is still in progress (`idempotency_in_progress`).
- `422`: Recipient is suppressed (bounce/complaint/unsubscribe).
- `429`: Free-account daily send or distinct-recipient limit reached.
- `502`: Transient delivery failure (`{retryable:true}`) or an ambiguous provider outcome (`code:delivery_outcome_unknown`) — the send may or may not have gone out and is left for reconciliation.
- `503`: No message was delivered. Screening unavailable requires a new client_id; sending_cleanup_pending retries cleanup with the same client_id.

---

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