Base de conhecimento

API REST

Uma API HTTP documentada com chaves emitíveis, delimitáveis por âmbito e revogáveis.

Detalhes

Ligada, em todo o lado. A API serve 104 operações documentadas em 68 caminhos (emails, conversas, rascunhos, etiquetas, contactos, audiências, domínios, modelos, regras, funções, membros, definições, calendário, rastreio, webhooks e a conta) atrás de um documento OpenAPI 3.1 assumido que pode ler sem chave em GET /openapi.json. O acesso é decidido pela chave do espaço de trabalho que emite nas Definições.
A durabilidade por que isto costumava estar à espera está feita. Um envio escreve uma linha antes de algo ser despachado, com um id público com a forma msg_ seguido de 24 caracteres hexadecimais, e GET /emails/{id} resolve-o, juntamente com /events para o rasto por destinatário e /tracking para aberturas e cliques. Uma Idempotency-Key de 1 a 255 caracteres é reclamada contra um índice único sobre a chave e a sua chave de API em conjunto, pelo que uma repetição após um tempo-limite devolve o primeiro resultado com Idempotency-Replayed: true em vez de enviar duas vezes. Um envio com chave responde 200 assim que estiver estabilizado e 202 enquanto ainda estiver em fila ou agendado.
As chaves são criadas, delimitadas por âmbito, rodadas e revogadas em Definições → Chaves API. Todas as chaves que a consola emite são oe_live_. O prefixo oe_test_ é compreendido pelo verificador e pelo caminho de envio, onde um envio em modo de teste é registado e respondido como enviado sem chegar a qualquer transporte, mas ainda nada consegue criar uma, e oferecer a opção antes de o transporte inócuo ficar acima do Durable Object entregar-lhe-ia uma chave de teste que entrega a sério. Uma chave leva um âmbito de envio de até 25 domínios inteiros e 50 endereços individuais, em que um domínio inteiro também cobre endereços acrescentados mais tarde, uma validade opcional entre 1 e 3650 dias e, opcionalmente, uma função. A função é um teto e não uma segunda concessão: GET /ping devolve tanto os âmbitos que estão na chave como os âmbitos que a função lhe deixou, pelo que um 403 para um âmbito que a sua chave nomeia claramente tem uma causa visível. Revogar é uma atualização e não uma eliminação, pelo que uma chamada posterior recebe revoked_api_key em vez de simplesmente falhar a autenticação. Rodar mantém tudo na chave exceto o segredo: o id, os âmbitos, o âmbito de envio e o histórico de pedidos continuam, o segredo antigo morre no instante em que o novo é criado, e uma chave com keys:write pode rodar-se a si própria pela API. As mesmas ações de listar, rodar, revogar e ativar estão no servidor MCP para quem tenha uma função que possa gerir chaves.
O que falta mesmo: a API não tem um endpoint de carregamento próprio. Os anexos em linha vão em base64 sob um limite total de 5 MB, e um ficheiro maior é enviado indicando pelo id um ficheiro que já esteja no espaço de trabalho, que viaja como ligação de transferência. As devoluções são tratadas na caixa de correio e não no registo de envios: um relatório de entrega é analisado, associado ao original pelo Message-ID, etiquetado na conversa e enviado como webhook email.bounced, mas nada escreve de volta na linha de envio, cujo estado não tem um valor de devolução, pelo que, através de GET /emails, uma mensagem devolvida continua a ler-se como enviada. O correio enviado a partir do editor da aplicação também não aparece em GET /emails, porque o editor não escreve pelo mesmo caminho de envio.