# API de email

Enviar e ler email a partir de um programa com uma chave `am_`, através de uma fila com turnos por empresa.

Fonte: https://ardumaker.com/pt/docs/email-api/

- Categoria: Comunicação
- Estado: Disponível
- Requisitos: Pelo menos uma [conta bot](https://ardumaker.com/pt/docs/cuentas-bot) em um domínio verificado; Ser admin da empresa para criar chaves
- Ferramentas MCP (Só leem): `ver_api_correo`, `listar_api_keys_correo`, `ver_cola_correo`
- Ferramentas MCP (Escrevem ou modificam): `crear_api_key_correo`
- Ferramentas MCP (Destrutivas): `cambiar_token_api_key_correo`, `revocar_api_key_correo`

## O que permite fazer?

- Enviar email a partir de uma conta bot com `POST /emails`.
- Consultar o enviado e o estado de cada email pelo id.
- Ler o que as contas bot receberam com `GET /inbound`.
- Criar chaves com âmbito em um domínio inteiro ou em uma lista de bots, com permissão completa ou só de envio.

## Quando convém usar?

Para email disparado por uma aplicação: avisos, confirmações, respostas automáticas ou ler uma caixa de entrada a partir de código.

## Como funciona na ArduMaker?

Cada pedido leva `Authorization: Bearer <chave am_...>`. O remetente (`from`) tem de ser uma conta bot que a chave alcance; aceita-se também `Nome <bot@dominio>`.

```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"}'
```

Enviar responde 202: o email fica em fila, não enviado. A fila sai por turnos: um email por empresa por volta, por ordem de chegada, com limite por empresa e limite global por minuto. O URL base exato é devolvido por `ver_api_correo`.

| Limite | Valor |
| --- | --- |
| Destinatários por email | 50 |
| Anexos por email (base64) | 10 MB |
| Emails em fila por empresa | 1000 |
| Envios por minuto por empresa | 10 por omissão |
| Envios por minuto em toda a plataforma | 20 por omissão |

## O que muda realmente?

- Cada envio cria um registro na fila com estado `queued`, `sending`, `sent` ou `failed`.
- O que é enviado fica na caixa da conta bot, por isso as respostas chegam e leem-se com a mesma chave.
- Revogar uma chave não a apaga: fica desativada para que o histórico continue a saber quem enviou cada email.

## Esquema

**Envio por API**

```text
O seu programa (chave am_)
  ↓
API de email (valida remetente e limites)
  ↓
Fila de saída (turnos por empresa)
  ↓
Caixa da conta bot (SMTP)
  ↓
Destinatário
```

## Resultado esperado

O programa recebe um id por email e consulta o estado até `sent` ou `failed`. As respostas dos destinatários leem-se na caixa da conta bot.

## Erros e resolução

| Resposta | Causa |
| --- | --- |
| 403 `remitente_no_permitido` | O `from` não é uma conta bot que a chave alcance. |
| 429 `Queue is full` | A empresa já tem 1000 emails à espera. |
| 400 `adjunto_invalido` ou `total_attachment_size` | Anexo mal codificado ou acima de 10 MB. |
| 424 `casilla_no_lista` | A caixa da conta bot não está pronta no servidor. |

Um email `failed` não é repetido sozinho. `ver_cola_correo` mostra quantos esperam, há quanto tempo espera o mais antigo e os erros mais recentes.

## Relação com MCP

As chaves geram-se via MCP e só um admin da empresa pode criá-las, renová-las ou revogá-las. Ver [/mcp/correo](https://ardumaker.com/pt/mcp/correo).

| Tipo | Ferramentas |
| --- | --- |
| Leitura | `ver_api_correo`, `listar_api_keys_correo`, `ver_cola_correo` |
| Modificam | `crear_api_key_correo`, `cambiar_token_api_key_correo` |
| Destrutiva | `revocar_api_key_correo` |

> **PRECAUCION:** O token de uma chave só é mostrado uma vez, ao criá-la ou renová-la. Renovar invalida o anterior.

## Funcionalidades relacionadas

- [Contas bot](https://ardumaker.com/pt/docs/cuentas-bot/)
- [Email profissional](https://ardumaker.com/pt/docs/correo-profesional/)
- [SMTP e IMAP](https://ardumaker.com/pt/docs/smtp-imap/)
- [Notificações](https://ardumaker.com/pt/docs/notificaciones/)