---
title: "Compose and send a fresh email from a mailbox you own"
method: POST
path: "/v1/mailboxes/{mailbox_id}/send"
tags: ["send"]
---

# Compose and send a fresh email from a mailbox you own

`POST /v1/mailboxes/{mailbox_id}/send`

## Request

- Base URL: `https://mbag.ai/api`
- URL: `https://mbag.ai/api/v1/mailboxes/{mailbox_id}/send`
- Auth: HTTP bearer

Single recipient. Runs the full governance pipeline: ownership, the
mailbox's policy blocklist, its operating mode (shadow mode refuses),
and the account's tier send caps. Only a send that actually leaves
consumes quota.

## Path parameters

- `mailbox_id` integer, required

## Request body

- object
  - `html_body` string: Optional HTML part alongside the plain text.
  - `subject` string, required
  - `text_body` string, required
  - `to` string, required: Exactly one recipient email address.

## Response `200`

Sent.

- object
  - `message_id` string, required: JMAP id of the created message
  - `status` 'sent', required

## Other responses

- `400`: Invalid `to` or empty `text_body`.
- `401`: Missing or invalid credential, raised by the `ApiKeyAuth` extractor (`backend/src/api_keys.rs`) before the handler runs: no `Authorization` header, a non-`Bearer` scheme, a key that doesn't hash-match any row, or a key whose status isn't `active`. A header that isn't valid UTF-8, has no scheme token, or has `Bearer` with no key value returns 400 with this same JSON shape instead of 401.
- `403`: Recipient blocked by the mailbox policy.
- `404`: Mailbox not found (or not yours).
- `409`: Mailbox is in shadow assessment mode; sends are suppressed.
- `429`: Tier send cap reached.
- `502`: Upstream mail server rejected the send.

---

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