Mudar do SendGrid
Mantenha o SDK do SendGrid 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/sendgrid e dê-lhe, em vez da chave do SendGrid, uma chave de API do OpenEmail com a permissão emails:send. Ela segue no mesmo cabeçalho Authorization: Bearer. As suas chamadas que enviam correio ficam como estão, e o endereço From decide se uma mensagem pode sair, como em todo o OpenEmail.
import sgMail from '@sendgrid/mail'import client from '@sendgrid/client' client.setApiKey(process.env.OPENEMAIL_API_KEY)client.setDefaultRequest('baseUrl', 'https://api.openemail.uk/compat/sendgrid')sgMail.setClient(client) await sgMail.send({ from: '[email protected]', to: '[email protected]', subject: 'Your invoice', html: '<p>Your invoice is attached.</p>',})Em Node, defina primeiro a chave no cliente, depois o URL base, e então passe o cliente ao pacote de correio. Não chame sgMail.setApiKey depois disso, porque repõe o URL base do SendGrid. O SDK avisa que a chave não começa por SG., o que é inofensivo. Em Python, Ruby e PHP, indique o host sem barra final.
O que corresponde a quê
O endpoint servido é POST /v3/mail/send. Cada entrada de personalizations torna-se uma mensagem do OpenEmail com o seu próprio id, pelo que um pedido envia no máximo 100 mensagens.
| SendGrid | No OpenEmail |
|---|---|
| from | O remetente, com o seu nome. Uma personalização pode indicar o seu próprio from. |
| personalizations | Uma mensagem cada uma. Os seus to, cc e bcc somam até 50 destinatários entre si, e os seus subject, headers, custom_args, send_at e substitutions aplicam-se apenas a essa mensagem. |
| subject | O assunto, a menos que uma personalização defina o seu. |
| content | text/plain torna-se o corpo de texto e text/html o corpo HTML. text/x-amp-html fica de fora, porque o corpo HTML já transporta a mensagem. |
| attachments | Ficheiros, no máximo 20 e 5 MB no total. Uma imagem incorporada cujo content_id o HTML usa como cid: é embutida onde aparece. Qualquer outro ficheiro incorporado chega como anexo normal. |
| reply_to | O endereço de resposta. reply_to_list também funciona enquanto tiver um único endereço. |
| headers | Cabeçalhos próprios: X-*, List-*, Reply-To, Precedence, Auto-Submitted, Importance, Priority e Feedback-ID. Uma personalização acrescenta os seus. |
| categories | Etiquetas chamadas category, category_2 e assim por diante, cada uma com uma categoria. |
| custom_args | Etiquetas com os mesmos nomes e valores. Os valores de uma personalização prevalecem. |
| send_at | Um envio agendado, com até um ano de antecedência. Uma hora já passada envia de imediato. |
| substitutions | Cada chave é substituída pelo seu valor no assunto, no corpo de texto e no corpo HTML dessa mensagem. |
| template_id | O id (tpl_...) ou o slug de um modelo do OpenEmail, preenchido a partir de dynamic_template_data. |
| tracking_settings | open_tracking.enable e click_tracking.enable ligam ou desligam o rastreio de aberturas e de cliques da mensagem. |
| mail_settings | sandbox_mode.enable verifica o pedido, o remetente e o modelo, e depois responde 200 sem enviar nada. |
Uma mensagem leva no máximo 10 etiquetas, contando categorias e custom_args em conjunto. Um pedido que precise de mais é recusado em vez de cortado, para que nada do que enviou desapareça sem aviso.
O que é recusado, e porquê
- Um id de modelo do SendGrid em
template_id, comod-…. Os modelos ficam no SendGrid, por isso recrie o modelo no OpenEmail e envie o seu id ou slug. contentao lado detemplate_id, porque um modelo do OpenEmail fornece o corpo inteiro.substitutionscom um modelo pela mesma razão: passe os valores emdynamic_template_data.- Mais de um endereço de resposta,
reply_toereply_to_listem conjunto, e tipos de conteúdo que não sejam texto e HTML. Envie um convite de calendário como anexo.ics. mail_settings.footerligado, esections, porque o OpenEmail não escreve texto na sua mensagem.- Mais de 10 etiquetas, um nome de etiqueta com algo além de letras, algarismos,
_e-, um cabeçalho fora da lista acima e mais de 100 personalizações num pedido.
asm, batch_id, ip_pool_name, as definições de bypass de mail_settings, subscription_tracking, ganalytics, click_tracking.enable_text e open_tracking.substitution_tag são aceites e não mudam nada. Os endereços da lista de supressão do espaço de trabalho são sempre ignorados, diga o que disser uma definição de bypass.
Respostas e erros
- Um envio responde 202 com o corpo vazio e o id da mensagem do OpenEmail em
X-Message-Id, o id queGET /emails/{id}e os webhooks usam. Com várias personalizações, contém o id da primeira mensagem. Um cabeçalhoIdempotency-Keyfunciona como no resto da API. - Os erros chegam como
errors, uma lista demessage,fieldehelp: 400 para um pedido que não pode ser enviado, 401 para uma chave em falta ou desconhecida, 403 para uma chave sememails:sendou um endereço From que a chave não pode usar ou cujo domínio ainda não pode enviar, 413 para um corpo acima de 30 MB ou anexos acima de 5 MB, e 429 quando o espaço de trabalho esgotou a sua quota de envio. - Quando uma personalização falha depois de outras anteriores terem sido aceites, o erro indica as mensagens já enviadas, para que uma nova tentativa as possa deixar de fora.