Mudar do Mailgun
Mantenha o SDK do Mailgun e envie através do OpenEmail. Altere o URL base e a chave, e o seu código de envio fica como está.
O que mudar
Aponte o SDK para https://api.openemail.uk/compat/mailgun e dê-lhe, em vez da chave do Mailgun, uma chave de API do OpenEmail com a permissão emails:send. Ela segue como palavra-passe do mesmo início de sessão HTTP Basic, e o nome de utilizador não é verificado. O domínio no caminho tem de ser um dos domínios do espaço de trabalho, e o endereço From decide se uma mensagem pode sair, como em todo o OpenEmail.
import formData from 'form-data'import Mailgun from 'mailgun.js' const mailgun = new Mailgun(formData)const mg = mailgun.client({ username: 'api', key: process.env.OPENEMAIL_API_KEY, url: 'https://api.openemail.uk/compat/mailgun',}) await mg.messages.create('acme.com', { from: 'Acme Billing <[email protected]>', to: ['[email protected]'], subject: 'Your invoice', html: '<p>Your invoice is attached.</p>',})Em Ruby, o segundo argumento é o host e o caminho sem esquema. Em PHP, o SDK guarda apenas o host do endpoint que recebe, por isso o caminho entra através do AddPathPlugin do php-http, que o SDK já instala. O pacote oficial de Python pode registar um aviso de que o host não é o do Mailgun, e envia na mesma. Também repete um pedido que falhou com 429 ou um 5xx, por isso o OpenEmail responde 400 em vez de 5xx quando parte de um lote já saiu.
O que corresponde a quê
O endpoint servido é POST /v3/{domain}/messages, como multipart/form-data, de que os anexos precisam, ou como application/x-www-form-urlencoded. Um nome de campo que termine em [] é lido sem esse final.
| Mailgun | No OpenEmail |
|---|---|
| from | O remetente, com o seu nome. |
| to | Destinatários, repetidos ou separados por vírgulas. Com cc e bcc, até 50 por mensagem. |
| subject | O assunto. |
| html | O corpo HTML. text torna-se o corpo de texto, e um dos dois, ou template, é obrigatório. |
| attachment | Ficheiros, no máximo 20 e 5 MB no total. |
| inline | Uma imagem que o HTML usa como cid: com o seu nome de ficheiro é embutida onde aparece. Qualquer outro ficheiro incorporado chega como anexo normal. |
| o:tag | Etiquetas chamadas tag, tag_2 e assim por diante, cada uma com uma etiqueta. |
| v: | Cada variável torna-se uma etiqueta com o seu nome e valor. Com o:tag, no máximo 10 por mensagem. |
| o:deliverytime | Um envio agendado, com até um ano de antecedência. Uma hora já passada envia de imediato. |
| o:tracking | Com o:tracking-clicks e o:tracking-opens, liga ou desliga o rastreio da mensagem. htmlonly conta como ligado. |
| o:testmode | yes regista a mensagem como enviada sem a entregar, como faz uma chave oe_test_. |
| h:Reply-To | O endereço de resposta. Qualquer outro campo h: torna-se um cabeçalho próprio: X-*, List-*, Precedence, Auto-Submitted, Importance, Priority e Feedback-ID. |
| recipient-variables | Um envio em lote. Cada endereço de to recebe a sua própria mensagem, com %recipient.key% preenchido a partir das suas variáveis e %recipient% com o seu endereço, e cc e bcc vão em cada uma. Um marcador sem valor fica como está. |
| template | O slug ou o id (tpl_...) de um modelo do OpenEmail, preenchido a partir de t:variables, ou então de h:X-Mailgun-Variables. t:version escolhe uma versão pelo seu número. |
O que é recusado, e porquê
- Um
templatecomhtmloutext, porque um modelo do OpenEmail fornece o corpo inteiro, e umt:versionque não seja um número de versão. o:deliverytime-optimize-periodeo:time-zone-localize, porque o OpenEmail não escolhe uma hora de envio para cada destinatário. Outros cabeçalhosh:X-Mailgun-, que são instruções para o Mailgun: use antes a opçãoo:correspondente.amp-htmlsozinho. Ao lado dehtmloutextfica de fora, porque estes já transportam a mensagem.- Mais de um endereço de resposta, mais de 10 etiquetas, um nome de etiqueta com algo além de letras, algarismos,
_e-, e um lote de mais de 100 destinatários. O Mailgun aceita 1000, por isso divida os lotes maiores.
o:dkim, o:require-tls, o:skip-verification, o:sending-ip, o:sending-ip-pool, o:tracking-pixel-location-top, o:archive-to, o:deliver-within e t:text são aceites e não mudam nada.
Respostas e erros
- Um envio responde 200 com a mensagem
Queued. Thank you.e umid: o id da mensagem do OpenEmail entre parênteses angulares, queGET /emails/{id}e os webhooks usam sem eles. Um envio em lote cria uma mensagem por destinatário, cada uma com o seu próprio id, e responde com o primeiro. Um cabeçalhoIdempotency-Keyfunciona como no resto da API. - Uma chave em falta ou desconhecida responde 401 com o texto simples
Forbidden, e um domínio que o espaço de trabalho não tem responde 404 comDomain not found. Tudo o resto chega como umamessage: 400 para uma mensagem que não pode ser enviada, 403 para uma chave sememails:send, um endereço From que a chave não pode usar, um domínio que ainda não pode enviar ou um espaço de trabalho que esgotou a sua quota de envio, e 413 para um corpo acima de 25 MB ou anexos acima de 5 MB. - Quando um destinatário de um lote falha depois de outros terem sido aceites, o erro indica as mensagens já enviadas e responde 400, para que um SDK que repete pedidos não as envie duas vezes.