---
title: "Send a composed message from one of your aliases."
method: POST
path: "/v1/mail/send"
tags: ["Mail"]
---

# Send a composed message from one of your aliases.

`POST /v1/mail/send`

## Request

- Base URL: `https://api.inboxy.net`
- URL: `https://api.inboxy.net/v1/mail/send`
- Auth: HTTP bearer

REST mirror of the MCP `mail_send` tool. Requires `send` scope. The `From:` is locked to one of the caller's active `@inboxy.net` aliases (forced to the bound alias on address-scoped keys). Recipients are classified internal vs external; external sends enqueue onto `outbound-send` and carry the inboxy attribution footer. Plan-tier daily caps + per-user rate limits apply.

## Request body

- MailSendRequest: Compose a new message from one of the caller's @inboxy.net aliases. The recipient is classified server-side: internal recipients (another `@inboxy.net` user) bypass external SMTP and land in the recipient's inbox; external recipients enqueue via the sender worker and carry the mandatory inboxy attribution footer.
  - `from_local_part` string, required: Local-part of the alias to send from. Must be one of the caller's active aliases. When the API key is address-scoped this is forced to the bound alias and `key_scope_mismatch` is returned on conflict.
  - `to` string, required: RFC 5322 recipient address. Mailbox-syntax validated server-side.
  - `subject` string, required: Trimmed and truncated at 200 chars.
  - `text` string: Plain-text body. Required if `html` is absent.
  - `html` string: Optional HTML body.
  - `in_reply_to` string: Optional `Message-Id` to thread against. Sanitized server-side before being written to headers.

## Response `202`

Accepted — internal delivery completed, external queued.

- MailSendResult
  - `ok` true, required
  - `delivery` 'internal' | 'external', required: `internal` = recipient is another inboxy user; delivered directly. `external` = enqueued onto `outbound-send` for the sender worker.
  - `message_id` string, uuid: Present on internal delivery only — the recipient's new `messages.id`.
  - `from` string, email, required
  - `to` string, email, required
  - `subject` string, required
  - `idempotency_key` string, required

## Other responses

- `400`: Validation failure (`from_missing`, `from_not_owned`, `from_retired`, `to_missing`, `subject_missing`, `body_missing`, `body_too_long`, …).
- `403`: `key_scope_mismatch` (address-scoped key called with a different `from_local_part`) or recipient blocked by abuse rules.
- `429`: `quota_exhausted` — body includes `code` + `remaining`. The mail-send quota refills daily.

---

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