Base de conhecimento
API de email
Envie uma mensagem ou cem por chamada, agora ou mais tarde, e repita sem enviar duas vezes.
Detalhes
- POST /emails envia uma mensagem e POST /emails/batch até 100 independentes. Um lote nunca é tudo ou nada: um endereço errado no item 7 faz falhar o item 7, o resto segue na mesma, e a resposta dá conta de cada item à parte.
- O conteúdo vem de uma só fonte: html e/ou text, um modelo guardado por id ou slug (fixe a versão quando o texto for de outra pessoa) ou um rascunho existente. Até 10 etiquetas seguem com ele e são devolvidas em cada leitura.
- scheduledAt segura uma mensagem até 365 dias, como instante ISO 8601 ou duração como PT1H. cancellableForSeconds dá a um envio imediato uma margem para anular de até 900 segundos. Ambos podem ser cancelados, e um envio agendado reagendado, até sair.
- Cada envio leva um Idempotency-Key reservado antes de qualquer despacho, por isso uma repetição depois de um tempo esgotado devolve o primeiro resultado com Idempotency-Replayed: true. A mesma chave com outro conteúdo é recusada como idempotency_key_reuse.
- Cada envio tem um id msg_ desde o momento em que é aceite. GET /emails/{id} lê-o, /events dá o rasto de cada destinatário e /tracking as aberturas e cliques.
- Acrescente translate e a mensagem é entregue na língua do destinatário. É traduzida quando o pedido é aceite, por isso um envio agendado leva o texto que aprovou, e uma tradução que não se consegue produzir recusa o envio em vez de recorrer ao original.
- Anexos: até 20 ficheiros, os incorporados com um máximo de 5 MB no total. Um ficheiro maior envia-se indicando o id de um ficheiro do espaço de trabalho e segue como link de transferência.
- O que falta: ainda não há modo de teste, por isso cada chave entrega a sério, e o registo do envio não tem estado de devolução. Uma devolução é etiquetada na conversa e emitida como webhook email.bounced, enquanto GET /emails continua a mostrar sent.
- A lista de supressão, Endereços bloqueados nas Definições, também está na API. GET /suppressions lê-a com uma pesquisa e um filtro por motivo, POST /suppressions bloqueia um endereço à mão e DELETE /suppressions/{id} volta a permitir um, exceto um bounce permanente, que fica. O SDK e o servidor MCP fazem o mesmo, e cada alteração dispara o webhook suppression.added ou suppression.removed.