# Send an email

Source: https://docs.maylee.app/api-reference/drafts/send-email

`POST https://api.maylee.app/api/v1/drafts/send`

Scope: `write`. Also requires `allowOutboundSend` (the Send emails permission of the key).

The only irreversible action in this API: it leaves the system and reaches a third party.

Requires the `write` scope AND `allowOutboundSend` enabled on the key: the scope alone is
deliberately not enough. Always send an `Idempotency-Key`: a retry after a network timeout
would otherwise deliver the message twice.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | A unique value per operation, such as a UUID. Replays the stored response for 24h. Reusing a key with a different body returns 409. 0 to 255 characters. |

## Request body

`application/json`, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `body` | object | yes | `{ "html" }`, `{ "text" }` or both. |
| `body.html` | string | no |  |
| `body.text` | string | no |  |
| `mailboxId` | string | yes | The sending mailbox, from `GET /mailboxes`. 1 to n characters. |
| `to` | array of object | yes | At least one recipient. Each entry is `{ "email", "name" }`, `name` optional. |
| `to[].email` | string (email) | yes |  |
| `to[].name` | string | no |  |
| `bcc` | array of object | no | Each entry is `{ "email", "name" }`, `name` optional. |
| `bcc[].email` | string (email) | yes |  |
| `bcc[].name` | string | no |  |
| `cc` | array of object | no | Each entry is `{ "email", "name" }`, `name` optional. |
| `cc[].email` | string (email) | yes |  |
| `cc[].name` | string | no |  |
| `from` | object | no | Optional send-as alias. It must be a verified alias of the mailbox; otherwise the send is refused (`INVALID_SENDER_ALIAS`) rather than rewritten by the provider. |
| `from.email` | string (email) | yes |  |
| `from.name` | string | no |  |
| `inReplyTo` | string | no | `messageId` of the email you answer, to reply in the same conversation. 0 to 998 characters. |
| `references` | array of string | no | The answered email's `references` followed by its `messageId`, in that order. |
| `signature` | string | no | `default` (or omitted): the signature the user would get in the app for the sending address. `none`: no signature. Otherwise the id of a signature from `GET /signatures` (`SIGNATURE_NOT_FOUND` if it does not exist). 1 to 128 characters. |
| `subject` | string | no | Defaults to an empty subject. No line breaks. 0 to 2000 characters. Default: `""`. |

## Example request

```bash
curl -X POST "https://api.maylee.app/api/v1/drafts/send" \
  -H "Authorization: Bearer $MAYLEE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "body": {
    "text": "Hello Jane, here is the quote you asked for."
  },
  "inReplyTo": "<CAF3k9x1@mail.example.com>",
  "mailboxId": "cmbx1a2b3c4d5e6f7g8h9i0j",
  "references": [
    "<CAF3k9x1@mail.example.com>"
  ],
  "subject": "Re: Quote request",
  "to": [
    {
      "email": "client@acme.com",
      "name": "Jane Client"
    }
  ]
}'
```

## Responses

### 201

Sent. Returns the message id.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `messageId` | string | yes | RFC `Message-ID` of the email that was sent. |
| `threadId` | string or null | yes | Provider conversation id, when the provider exposes one. |

```json
{
  "messageId": "<20260825140233.1a2b3c@your-company.com>",
  "threadId": "18c2f5a9e7b1d3c4"
}
```

### 400

Invalid payload, or sender alias not verified for the mailbox.

### 401

Missing, malformed, revoked or expired API key.

### 403

Key lacks the required scope, or outbound sending is not enabled on it.

### 404

Mailbox not found. Call `GET /mailboxes` for valid ids.

### 409

Idempotency key reused with a different body, or original call still in flight.

### 429

Per-minute rate limit (`RATE_LIMIT_EXCEEDED`) or monthly quota (`QUOTA_EXCEEDED`) exhausted.

Errors use the format `{ "code", "error", "details" }`: see [Errors](/errors.md).