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.

Categoria: Comunicação
Estado: Disponível
Requisitos: Pelo menos uma conta 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>.

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

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

Envio por API

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.

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`