Email API

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

Category: Communication
Status: Available
Requirements: At least one bot account 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.

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

Your program: am_ key
Email API: checks sender and limits
Outgoing queue: per-company turns
Bot account mailbox: SMTP
Recipient

Sending through the API

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.

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`