E-mails

As mensagens que chegaram nas suas inboxes, seu conteúdo interpretado e seu estado de processamento. Cinco tools.

Veja o modelo Email para o formato do objeto retornado e a máquina de estados received → approved | rejected → processing → processed | failed.

---

emails_list

Leitura · escopo inbox/emails · permissão emails.list · GET /emails

Lista os e-mails recebidos no workspace selecionado. Paginado por cursor. Os corpos não vêm incluídos — para eles, use emails_get.

Parâmetro	Tipo	Descrição
cursor	string	Cursor opaco de uma página anterior.
limit	integer	Tamanho da página, padrão 25, máximo 100.
sort	string	Chaves de ordenação, prefixo - para descendente.
status	received | approved | rejected | processing | processed | failed	Filtra por status de processamento.
inbox_id	string (uuid)	Apenas o e-mail recebido nesta inbox.
agent_id	string (uuid)	Apenas o e-mail processado por este agente.
message_id	string	Filtra pelo Message-ID (RFC 5322).
from	string	Casamento exato no remetente.
to	string	Casa quando o endereço aparece no array de destinatários.
created_at_gte / created_at_lte	string	Intervalo ISO 8601 sobre created_at.
received_at_gte / received_at_lte	string	Intervalo ISO 8601 sobre received_at.
processed_at_gte / processed_at_lte	string	Intervalo ISO 8601 sobre processed_at.

emails_get

Leitura · escopo inbox/emails · permissão emails.show · GET /emails/{id}

Busca um e-mail, incluindo os corpos texto e HTML já interpretados.

Parâmetro	Tipo	Descrição
id obrigatório	string (uuid)	Id do e-mail.

emails_download_eml

Leitura · escopo inbox/emails · permissão emails.download · GET /emails/{id}/eml

Retorna uma URL pré-assinada de vida curta para o .eml original, com todos os headers, partes MIME e anexos. A URL expira em 60 segundos e não pode ser buscada de novo — baixe antes que ela caduque.

A mensagem bruta deliberadamente não é devolvida embutida: o resultado de uma tool entra no contexto do modelo e pode ser persistido pelo cliente.

Parâmetro	Tipo	Descrição
id obrigatório	string (uuid)	Id do e-mail.

emails_reprocess

Destrutiva · escopo inbox/emails + write · permissão emails.reprocess · POST /emails/{id}/reprocess

Reenfileira um e-mail para o agente dele. Aceita apenas approved, processed ou failed; qualquer outro status é 422. Responde 202 — a execução acontece no worker, não nesta chamada.

Parâmetro	Tipo	Descrição
id obrigatório	string (uuid)	Id do e-mail.
agent_id	string (uuid)	Sobrepõe o agente para esta execução; o padrão é o agente atual da inbox.
idempotency_key	string	Proteção contra replay, 8–255 caracteres.

emails_delete

Destrutiva · escopo inbox/emails + write · permissão emails.delete · DELETE /emails/{id}

Exclui (soft-delete) um e-mail. O registro deixa de aparecer em todos os caminhos de leitura.

Parâmetro	Tipo	Descrição
id obrigatório	string (uuid)	Id do e-mail.