Inboxes

Uma inbox é um endereço de recebimento mais as regras aplicadas ao que chega nele. Oito tools, incluindo as duas que gerenciam a lista de remetentes permitidos.

Veja o modelo Inbox para o formato do objeto retornado.

---

inboxes_list

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

Lista as inboxes do workspace selecionado. Paginado por cursor.

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	active | inactive	Filtra por status.
agent_id	string (uuid)	Apenas inboxes ligadas a este agente.
slug	string	Filtra por slug.
email	string	Filtra pelo endereço de recebimento.
external_id	string	Filtra pelo id no seu sistema.
created_at_gte	string	created_at a partir deste timestamp ISO 8601.
created_at_lte	string	created_at até este timestamp ISO 8601.

inboxes_get

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

Busca uma inbox por id interno ou external_id.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id.

inboxes_create

Escrita · escopo inbox/inboxes + write · permissão inboxes.create · POST /inboxes

Cria uma inbox. O endereço de recebimento é composto no servidor como {organization}.{workspace}.{inbox}@<domínio> e fica ativo imediatamente — nenhuma chamada à AWS está envolvida. 409 em colisão de slug no mesmo workspace, 422 quando a parte local composta passa de 64 caracteres.

Parâmetro	Tipo	Descrição
label obrigatório	string	Nome de exibição, 1–120 caracteres.
slug	string	Minúsculo, com hífens, até 20 caracteres. Último segmento do endereço de recebimento; derivado do label quando omitido.
external_id	string	Id do registro no seu sistema.
agent_id	string (uuid) | null	Agente que processa os e-mails desta inbox.
allowed_recipients	string[]	Quando definido, só é aceito e-mail cujo remetente de envelope esteja nesta lista.
filters	object[]	Regras de aceitação aplicadas ao e-mail recebido.
attachments_allow	boolean	Se anexos são aceitos.
attachments_max_file_number	integer	Número máximo de anexos.
attachments_max_file_size	integer	Tamanho máximo por anexo, em bytes.
attachments_max_total_size	integer	Tamanho máximo total de anexos, em bytes.
attachments_allow_rules	array|null	Lista de anexos permitidos; cada regra precisa de extensions, filename_pattern ou os dois — ver regras de anexos permitidos. null limpa.
custom_metadata	object	JSON livre, de quem chama.
idempotency_key	string	Proteção contra replay, 8–255 caracteres.

inboxes_upsert

Escrita · escopo inbox/inboxes + write · permissão inboxes.create · PUT /inboxes

Cria ou atualiza uma inbox, casada por id, depois external_id, depois email. Campos omitidos mantêm o valor armazenado.

Parâmetro	Tipo	Descrição
id	string (uuid)	Casa primeiro pelo id interno.
email	string	Casa pelo endereço de recebimento, depois de id e external_id.
label	string	Nome de exibição, 1–120 caracteres.
slug	string	Minúsculo, com hífens, até 20 caracteres.
external_id	string	Chave de casamento no seu sistema.
agent_id	string (uuid) | null	Agente que processa os e-mails desta inbox.
allowed_recipients	string[]	Remetentes de envelope aceitos.
filters	object[]	Regras de aceitação.
attachments_allow	boolean	Se anexos são aceitos.
attachments_max_file_number	integer	Número máximo de anexos.
attachments_max_file_size	integer	Tamanho máximo por anexo, em bytes.
attachments_max_total_size	integer	Tamanho máximo total de anexos, em bytes.
attachments_allow_rules	array|null	Lista de anexos permitidos; cada regra precisa de extensions, filename_pattern ou os dois — ver regras de anexos permitidos. null limpa.
custom_metadata	object	JSON livre.
idempotency_key	string	Proteção contra replay.

inboxes_update

Escrita · escopo inbox/inboxes + write · permissão inboxes.update · PATCH /inboxes/{id}

Atualiza uma inbox. Alterar o slug repontua o endereço de recebimento — o e-mail enviado para o anterior deixa de chegar. Mudanças de filtro valem só para o e-mail futuro.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id.
label	string	Nome de exibição, 1–120 caracteres.
slug	string	Minúsculo, com hífens, até 20 caracteres.
external_id	string	Id no seu sistema.
agent_id	string (uuid) | null	Agente que processa os e-mails desta inbox.
allowed_recipients	string[]	Remetentes de envelope aceitos.
filters	object[]	Regras de aceitação.
attachments_allow	boolean	Se anexos são aceitos.
attachments_max_file_number	integer	Número máximo de anexos.
attachments_max_file_size	integer	Tamanho máximo por anexo, em bytes.
attachments_max_total_size	integer	Tamanho máximo total de anexos, em bytes.
attachments_allow_rules	array|null	Lista de anexos permitidos; cada regra precisa de extensions, filename_pattern ou os dois — ver regras de anexos permitidos. null limpa.
custom_metadata	object	JSON livre.

inboxes_delete

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

Exclui (soft-delete) uma inbox. O e-mail que chegar para aquele endereço vira recipient_unknown; o slug é liberado e pode ser reutilizado.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id.

inboxes_add_recipient

Destrutiva · escopo inbox/inboxes + write · permissão inboxes.update · POST /inboxes/{id}/recipients

Adiciona um endereço a allowed_recipients. Idempotente — 200 se já estiver presente, 201 se for novo.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id.
email obrigatório	string	Endereço a permitir.

inboxes_remove_recipient

Destrutiva · escopo inbox/inboxes + write · permissão inboxes.update · DELETE /inboxes/{id}/recipients

Remove um endereço de allowed_recipients. 404 quando o endereço não está na lista.

Parâmetro	Tipo	Descrição
id obrigatório	string	Id interno ou external_id.
email obrigatório	string	Endereço a remover.