Programadores
A caixa de correio não quer saber
quem está ao volante.
Tudo o que a aplicação faz, o seu código faz: 104 operações documentadas em 68 caminhos, por trás de um documento OpenAPI 3.1 que pode ler sem chave. O cliente TypeScript é confrontado com esse documento em cada compilação.
O MCP não tem chave nenhuma para colar. O cliente descobre o servidor de autorização a partir do endpoint, regista-se sozinho e envia-o para aqui para iniciar sessão.
104
operações documentadas
68
caminhos sob um só anfitrião
116
métodos do SDK, a cobrir todas elas
20
eventos de webhook, em três famílias
O documento OpenAPI 3.1 está em GET /openapi.json, e lê-lo não exige chave.
Superfícies
Três portas,
uma caixa de correio.
Uma chave de espaço de trabalho decide o que uma chamada pode fazer e a partir de que endereços pode enviar. Revogar é uma atualização e não uma eliminação, por isso uma chamada posterior fica a saber que a chave foi revogada.
Uma chave envia a partir de até 25 domínios inteiros e 50 endereços isolados. GET /ping devolve os âmbitos que detém e os âmbitos que o seu papel lhe deixou.
Aponte um cliente para o endpoint e inicie sessão. Não há chave para colar, porque o cliente se regista sozinho e o envia para aqui.
As ferramentas são construídas a partir do que quem chama pode fazer, por isso um cliente limitado à leitura não tem nenhuma ferramenta de envio. Um token continua a alcançar toda a caixa de correio.
Registe um endpoint https e a caixa de correio publica nele. As entregas são geradas pela própria caixa de correio e não por uma chamada à API, por isso escrever na aplicação e publicar na API provocam a mesma.
20 eventos em três famílias, e dez endpoints por caixa de correio.
Paridade
O cliente não pode ficar atrás
da API.
Uma verificação de paridade lê o documento OpenAPI em cada compilação e falha ao primeiro desvio: um método que aponta para uma operação que a especificação não tem, uma operação documentada sem método, ou uma lista de âmbitos que não bate certo com o que a operação exige. Imprime o que provou, e hoje isso lê-se como 116 métodos do SDK sobre as 104 operações documentadas.
A configuração, o pedido e a chamada são a mesma operação, escrita de três maneiras.
Agentes, API e MCP
O OpenEmail foi feito para ser operado tanto por software como por pessoas. A caixa de correio é a mesma de uma forma ou de outra.
Servidor MCP
Aponte o Claude, ou qualquer cliente MCP, para a sua caixa de correio.
OAuth para clientes de terceiros
Em breveRegisto de clientes em autosserviço com PKCE, para que uma aplicação possa pedir acesso como deve ser.
O consentimento e a revogação já existem; o âmbito não, por isso um token alcança toda a caixa de correio em vez da parte que a aplicação pediu.
REST API
Uma API HTTP documentada, com chaves que se emitem, se limitam e se revogam.
Guia rápido
Do nada a uma mensagem enviada.
Três passos.
- 1
Emita uma chave
Definições, Chaves de API, numa caixa de correio que lhe pertença. Escolha os seus âmbitos e limite os endereços a partir dos quais pode enviar a domínios inteiros ou a endereços isolados. O segredo é mostrado uma vez e o que fica guardado é um hash de sentido único.
GET /ping responde com os âmbitos da chave e os âmbitos que o seu papel lhe deixou. export OPENEMAIL_API_KEY=oe_live_9f2c1a4b7e05d3862c1f0a44_kX7… curl https://api.openemail.uk/ping \ -H "Authorization: Bearer $OPENEMAIL_API_KEY" - 2
Instale o cliente
Um cliente TypeScript sem dependências, publicado como ESM e CommonJS, que lê a chave de OPENEMAIL_API_KEY. Dispense-o se preferir enviar o JSON por si, porque cada endpoint é HTTP simples.
Node 18 e acima, Workers, Deno, Bun e o navegador. bun add @openemail/sdk - 3
Envie
A resposta traz o id. GET /emails/{id} resolve-o, /events tem o rasto por destinatário, e /tracking tem as aberturas e os cliques.
Uma repetição que traga a mesma Idempotency-Key devolve o primeiro resultado com Idempotency-Replayed: true. import { init, openemail } from '@openemail/sdk' init({ apiKey: process.env.OPENEMAIL_API_KEY }) const email = await openemail.emails.send({ from: 'Acme Billing <[email protected]>', to: '[email protected]', subject: 'Your September invoice', html: '<p>Invoice attached.</p>',}) console.log(email.id, email.status)
Ausente
O que ainda não faz
por si.
Cinco coisas que vale a pena saber antes de construir sobre isto, e não depois.
- Sem endpoint de carregamento
- Os anexos em linha vão em base64 com um limite total de 5 MB. Um ficheiro maior envia-se indicando pelo id um ficheiro que já está no espaço de trabalho, e que viaja como ligação de transferência.
- As devoluções ficam-se pela caixa de correio
- Um relatório de entrega é analisado, associado pelo Message-ID, etiquetado na conversa e enviado como um webhook email.bounced. Nada volta a escrever na linha de envio, por isso, através de GET /emails, uma mensagem devolvida continua a ler-se como enviada.
- O correio do compositor não está em GET /emails
- O correio enviado a partir do compositor da aplicação não aparece nessa lista, porque o compositor não escreve pelo mesmo caminho de envio.
- O OAuth tem consentimento, não âmbito
- Um pedido é mostrado antes de ser concedido e as Aplicações ligadas voltam a retirá-lo, mas um token alcança toda a sua caixa de correio e não apenas a parte que uma aplicação pediu.
- Sem fluxo de publicação
- Publicar o cliente é uma execução manual do preflight, da compilação e do bun publish, por isso uma versão chega ao npm quando alguém a executa e não quando a alteração entra.
Verificar uma entrega
Cada entrega é assinada,
e cada repetição transporta o seu id.
A assinatura é um HMAC-SHA-256 sobre a marca temporal, um ponto e o corpo em bruto. Verifique contra os bytes tal como chegaram, porque analisar e voltar a serializar reordena as chaves e quebra-a.
X-OpenEmail-Signature: t=1758240000,v1=9f0c4b2e7d1a86c3X-OpenEmail-Event: email.deliveredX-OpenEmail-Delivery: evt_4b7e05d3862c1f0a- Janela de repetição
- 300 segundos, e aplicá-la é tarefa do recetor. O verificador do SDK usa-a por omissão.
- Idempotency-Key
- Reclamada contra um índice único sobre a chave e a sua chave de API em conjunto, por isso uma repetição depois de um tempo esgotado devolve o primeiro resultado com Idempotency-Replayed: true em vez de enviar duas vezes.
- Repetições
- Cinco tentativas: no momento do evento, depois ao fim de 1 minuto, 5, 25 e 2 horas. Só se repete um tempo esgotado, uma ligação recusada, 408, 425, 429 ou um 5xx.
- X-OpenEmail-Delivery
- O id do evento é emitido uma vez e todas as tentativas o transportam, por isso um recetor que veja o mesmo id duas vezes pode descartar o segundo em vez de voltar a agir sobre ele.
Para quem é
Uma caixa de correio.
Três formas de entrar.
Um endereço grátis em openemail.uk, com o cliente por trás.
A mesma caixa de correio através de uma API, de um SDK e de MCP.
Emita uma chave.
Envie alguma coisa.
Full API, MCP and SDK access em todos os planos. Free traz 50 AI actions a day consigo.
