# Email API

Send and read email from a program with an `am_` key, through a queue with per-company turns.

Source: https://ardumaker.com/en/docs/email-api/

- Category: Communication
- Status: Available
- Requirements: At least one [bot account](https://ardumaker.com/en/docs/cuentas-bot) on a verified domain; Being a company admin to create keys
- MCP tools (Read only): `ver_api_correo`, `listar_api_keys_correo`, `ver_cola_correo`
- MCP tools (Write or modify): `crear_api_key_correo`
- MCP tools (Destructive): `cambiar_token_api_key_correo`, `revocar_api_key_correo`

## What can you do with it?

- Send email from a bot account with `POST /emails`.
- Check what was sent and each email's status by id.
- Read what bot accounts received with `GET /inbound`.
- Create keys scoped to a whole domain or a list of bots, with full or send-only permission.

## When should you use it?

For email triggered by an application: notices, confirmations, automatic replies or reading an inbox from code.

## How does it work in ArduMaker?

Each request carries `Authorization: Bearer <am_... key>`. The sender (`from`) must be a bot account the key can reach; `Name <bot@domain>` is also accepted.

```bash
curl -X POST "$BASE/emails" \
  -H "Authorization: Bearer am_..." \
  -H "Content-Type: application/json" \
  -d '{"from":"avisos@tuempresa.com","to":"cliente@ejemplo.com","subject":"Hola","text":"Mensaje"}'
```

Sending answers 202: the email is queued, not sent. The queue goes out in turns: one email per company per round, in arrival order, with a per-company cap and a global per-minute cap. The exact base URL is returned by `ver_api_correo`.

| Limit | Value |
| --- | --- |
| Recipients per email | 50 |
| Attachments per email (base64) | 10 MB |
| Queued emails per company | 1000 |
| Sends per minute per company | 10 by default |
| Sends per minute platform-wide | 20 by default |

## What actually changes?

- Each send creates a queue record with status `queued`, `sending`, `sent` or `failed`.
- What is sent stays in the bot account's mailbox, so replies arrive and are read with the same key.
- Revoking a key does not delete it: it stays disabled so history still knows who sent each email.

## Diagram

**Sending through the API**

```text
Your program (am_ key)
  ↓
Email API (checks sender and limits)
  ↓
Outgoing queue (per-company turns)
  ↓
Bot account mailbox (SMTP)
  ↓
Recipient
```

## Expected result

The program receives an id per email and checks its status until `sent` or `failed`. Recipient replies are read from the bot account mailbox.

## Errors and troubleshooting

| Response | Cause |
| --- | --- |
| 403 `remitente_no_permitido` | The `from` is not a bot account the key can reach. |
| 429 `Queue is full` | The company already has 1000 emails waiting. |
| 400 `adjunto_invalido` or `total_attachment_size` | Attachment badly encoded or above 10 MB. |
| 424 `casilla_no_lista` | The bot account's mailbox is not ready on the server. |

A `failed` email is not retried automatically. `ver_cola_correo` shows how many are waiting, how long the oldest has waited and the latest errors.

## MCP access

Keys are managed through MCP and only a company admin can create, renew or revoke them. See [/mcp/correo](https://ardumaker.com/en/mcp/correo).

| Type | Tools |
| --- | --- |
| Read | `ver_api_correo`, `listar_api_keys_correo`, `ver_cola_correo` |
| Modify | `crear_api_key_correo`, `cambiar_token_api_key_correo` |
| Destructive | `revocar_api_key_correo` |

> **PRECAUCION:** A key's token is shown only once, when it is created or renewed. Renewing invalidates the previous one.

## Related features

- [Bot accounts](https://ardumaker.com/en/docs/cuentas-bot/)
- [Professional email](https://ardumaker.com/en/docs/correo-profesional/)
- [SMTP and IMAP](https://ardumaker.com/en/docs/smtp-imap/)
- [Notifications](https://ardumaker.com/en/docs/notificaciones/)