guia · API do SendGrid

Como uma equipe de produto deve implementar a API do SendGrid com segurança?

Implemente a API do SendGrid por trás de um serviço de e-mail no servidor, usando um domínio de envio autenticado e uma chave de API limitada à permissão Mail Send. Valide cada mensagem antes de chamar `POST /v3/mail/send`, persista seu próprio registro de envio e capture o `X-Message-ID` da resposta. Processe os payloads assinados do Event Webhook a partir dos bytes brutos, elimine eventos duplicados e respeite bounces, denúncias de spam e descadastros. Trate `202 Accepted`, a entrega ao servidor de destino e a chegada à caixa de entrada como estados separados, com novas tentativas limitadas apenas para falhas transitórias.

Defina uma tarefa de envio restrita e legítima

A API v3 Mail Send do SendGrid é um endpoint de provedor para e-mail de saída, e não uma caixa postal de uso geral. Coloque-a atrás de um serviço confiável da aplicação ou de um worker de fila e defina quais eventos do produto podem criar mensagens, como uma verificação de conta, um recibo, um aviso de segurança ou uma notificação solicitada. Não exponha a chave do provedor a navegadores, clientes móveis, templates, prompts ou logs. Separe as mensagens transacionais das campanhas que dependem de consentimento no nível do modelo de dados, para que as expectativas dos destinatários, o tratamento de preferências e a reputação possam ser operados de forma independente. Antes da implementação, decida quem é dono do domínio de remetente, quem aprova os templates, quais ambientes podem enviar para fora e quais destinatários são permitidos em desenvolvimento. Esse escopo se torna o limite para as permissões das chaves de API, a configuração de domínio, os registros de auditoria, os alertas e a resposta a incidentes. Ele também torna possível uma migração de provedor, porque o código do produto solicita uma operação de e-mail aprovada em vez de montar requisições arbitrárias ao SendGrid por toda a aplicação.

Autentique um domínio de envio dedicado

Configure o Domain Authentication do SendGrid para um domínio ou subdomínio de finalidade específica que você controla e publique exatamente os registros DNS gerados para essa identidade, verificando-os no SendGrid. A documentação do provedor observa que subdomínios não herdam uma identidade autenticada do domínio pai; por isso, verifique o domínio realmente usado nos endereços From. Revise os registros SPF e DMARC existentes antes de mudar o DNS; não crie uma segunda política SPF para o mesmo hostname nem substitua a política DMARC existente de uma organização sem o responsável por ela. Mantenha o tráfego transacional e o promocional em identidades escolhidas deliberadamente quando os públicos e os riscos forem diferentes. Confirme em uma mensagem de teste recebida o endereço From visível, o return path, o domínio de assinatura DKIM, o caminho de resposta e o comportamento do link branding. A autenticação estabelece a identidade autorizada e os sinais de alinhamento, mas não determina a pasta final no sistema de destino. Continue monitorando bounces, reclamações, expectativas dos destinatários e conteúdo depois que a verificação de DNS for concluída.

Emita chaves de API com privilégio mínimo por ambiente

Crie uma chave de API Custom Access apenas com as permissões de que a carga de trabalho precisa, normalmente o acesso Mail Send para um worker de envio. Não dê a um remetente rotineiro Full Access a templates, supressões, membros da equipe, estatísticas, configuração de IP ou administração da conta. Use chaves separadas para desenvolvimento, staging e produção, com nomes que identifiquem o serviço responsável e a finalidade da rotação. O SendGrid exibe uma nova chave uma única vez; por isso, coloque-a diretamente no gerenciador de segredos do ambiente e nunca a copie para o controle de versão ou para um documento compartilhado. Em tempo de execução, leia-a de uma configuração apoiada no gerenciador de segredos e passe-a apenas no cabeçalho `Authorization: Bearer` via HTTPS. Teste a rotação de chaves como uma sequência operacional: crie uma substituta com permissões restritas equivalentes, implante a substituta, verifique tráfego controlado bem-sucedido e então revogue a chave antiga. Crie alertas para respostas 401 ou 403 inesperadas, porque elas podem indicar uma chave ausente, uma credencial revogada, uma permissão incompatível ou uma mudança de configuração insegura.

Monte e registre cada requisição Mail Send

Crie um registro interno de saída antes de contatar o SendGrid. Dê a ele uma chave estável de evento da aplicação, tenant, identidade do remetente, destinatários aprovados, classe de mensagem, versão do template e estado. Monte o payload do provedor a partir desse registro usando `personalizations`, `from`, `subject` e pelo menos uma parte de conteúdo suportada ou um dynamic template aprovado. Valide a sintaxe dos endereços, a quantidade de destinatários, o tamanho dos anexos, os dados do template e os cabeçalhos personalizados antes da chamada de rede. A visão geral atual do Mail Send do SendGrid limita o tamanho total da requisição, incluindo anexos, a menos de 30 MB e o total de destinatários entre To, Cc e Bcc a no máximo 1.000. Requisições menores e com finalidade específica são mais fáceis de auditar e recuperar. Em uma resposta `202 Accepted`, capture o cabeçalho `X-Message-ID` e vincule-o ao registro de saída. Não coloque dados pessoais em categories ou unique arguments; o SendGrid avisa que esses valores podem ser retidos e visualizados fora das proteções esperadas para o conteúdo das mensagens.

Verifique e processe o Event Webhook

Configure o Event Webhook do SendGrid em um endpoint HTTPS capaz de reter o corpo bruto da requisição. Habilite a assinatura criptográfica, o OAuth 2.0 ou ambos. Na entrega assinada, verifique o timestamp e o `X-Twilio-Email-Event-Webhook-Signature` em relação aos bytes brutos exatos antes do parsing do JSON; a Twilio avisa que serializar o payload novamente pode alterar os bytes e invalidar a verificação. Rejeite entradas não autenticadas, aplique um limite razoável de tamanho da requisição e evite replay de acordo com a política de timestamp escolhida pela equipe. Após a verificação, coloque na fila ou armazene de forma durável o lote de eventos antes de retornar sucesso. Elimine duplicatas com `sg_event_id` e então correlacione o `sg_message_id`, o `X-Message-ID` armazenado e um valor de correlação interno não sensível. Torne as transições de estado monotônicas, para que um evento processed atrasado não sobrescreva um resultado delivered ou bounce posterior. Mantenha o evento original do provedor em armazenamento restrito para diagnóstico, mas limite a retenção de endereços, textos de resposta e dados de engajamento ao que o produto e a política realmente exigem.

Modele com precisão a aceitação, a entrega e a chegada à caixa de entrada

O HTTP `202 Accepted` do SendGrid significa que a requisição foi aceita e colocada na fila para processamento. Ele não diz que o destino aceitou a mensagem. Um evento de webhook `processed` significa que o SendGrid aceitou a mensagem e pode tentar entregá-la. Um evento `delivered` significa que o SendGrid informa que o servidor de e-mail de destino a aceitou, muitas vezes com uma resposta SMTP. Isso ainda não comprova a chegada à caixa de entrada, porque o sistema de destino pode classificar o e-mail aceito em uma aba da caixa de entrada, em quarentena, na pasta de lixo eletrônico ou em outro local. Mantenha esses estados separados no armazenamento e nas interfaces: solicitado, aceito pelo provedor, processado, adiado, aceito pelo servidor de destino, bounce, descartado, reclamação ou suprimido. Evite traduzir toda resposta HTTP sem erro como “entregue”. Sinais de engajamento, como aberturas, também não são prova de entrega e podem ser afetados por recursos de privacidade. Nomes de estado precisos tornam mais seguras as investigações de suporte, as novas tentativas e as decisões de entregabilidade.

Classifique as falhas antes de tentar novamente

Trate os erros do provedor por classe, em vez de tentar novamente toda resposta diferente de 202. Um 400 geralmente exige corrigir o payload, o remetente, os dados do template ou cabeçalhos reservados. Um 401 aponta para autenticação; um 403 pode indicar permissão insuficiente ou política da conta; um 413 exige reduzir o tamanho da mensagem. O SendGrid documenta cabeçalhos de limite de taxa por endpoint e retorna 429 quando a franquia do período de renovação se esgota; então, espere até o horário de reset e adicione jitter, em vez de criar novas tentativas sincronizadas. Tente novamente falhas 5xx e de transporte com backoff exponencial, número finito de tentativas e um alerta operacional. Timeouts ambíguos exigem cuidado especial: o provedor pode ter aceitado a requisição mesmo que o cliente tenha perdido a resposta. Mantenha o registro de saída em estado desconhecido, procure eventos correlacionados e exija uma regra de reconciliação deliberada antes de reenviar. As APIs de provedores não eliminam a necessidade de prevenção de duplicatas no nível do produto. Nunca tente novamente um destino com bounce permanente conhecido, destinatário inválido, descadastro ou denúncia de spam como se fosse um erro transitório de infraestrutura.

Respeite as supressões e as escolhas dos destinatários

Ingira eventos de bounce, dropped, denúncia de spam, descadastro e descadastro de grupo em um modelo de segurança de destinatários. O SendGrid oferece supressões globais e unsubscribe groups para diferentes classes de mensagem. Associe cada mensagem promocional ou opcional ao grupo correto, ofereça um caminho de preferências compreensível e interrompa os envios quando a supressão relevante se aplicar. Não use opções de desvio de supressão como técnica rotineira de entrega. Uma mensagem crítica para o produto pode precisar de uma política jurídica e operacional documentada à parte, mas essa política não deve sobrepor silenciosamente a escolha promocional de uma pessoa nem uma salvaguarda de reputação do provedor. Proteja as ferramentas de suporte que removem uma supressão com autorização forte, um motivo visível e uma trilha de auditoria. Acompanhe separadamente as falhas de entrega permanentes e temporárias e revise qualquer reativação manual antes do próximo envio. Esses controles protegem os destinatários e reduzem tentativas repetidas para destinos que já rejeitaram ou recusaram o tráfego. Eles também evitam que o envio transacional herde comportamentos inseguros de campanhas.

Teste o ciclo de vida completo antes do tráfego de produção

Comece com uma chave do SendGrid de fora da produção e um subdomínio autenticado controlado. Verifique o DNS e então envie variantes em texto simples e HTML para caixas de entrada da própria equipe. Confirme a resposta `202` e o `X-Message-ID` e verifique se os eventos de webhook assinados se correlacionam com o registro de saída local. Exercite os caminhos de payload inválido, chave revogada, permissão ausente, anexo grande demais, limite de taxa, adiamento, bounce, descarte e evento duplicado sem usar endereços reais de clientes. Confirme que a verificação do webhook rejeita um corpo modificado e que o handler só confirma o recebimento após a captura durável. Teste a rotação de chaves, o rollback de templates, a aplicação da supressão e um timeout ambíguo no cliente. Adicione painéis para falhas de requisição, atraso de eventos, adiamentos, bounces, denúncias de spam e falhas de assinatura do webhook, com identificadores de tenant e de mensagem, mas sem credenciais nem conteúdo completo. Por fim, revise a documentação atual do SendGrid e os limites da conta no lançamento, porque direitos do plano, recursos regionais, cotas e políticas do provedor podem mudar independentemente do código da aplicação.

Compare dependências específicas do provedor

Uma integração direta com o SendGrid é apropriada quando uma equipe depende deliberadamente de campos de requisição, templates, controles de conta, formatos de webhook, supressões e responsabilidade operacional específicos do SendGrid. A documentação pública do SendHQ descreve uma API de e-mail com escopo por workspace, com envio com domínio verificado, e-mail de entrada, templates hospedados, eventos de entrega, supressões e um painel web. Antes de migrar, revise os payloads, eventos, controles de identidade, supressões, requisitos regionais e identificadores de provedor armazenados dos dois provedores.

Perguntas frequentes

O 202 Accepted do SendGrid significa que o e-mail foi entregue?

Não. Significa que o SendGrid aceitou a requisição da API para processamento. Use os eventos de entrega do Event Webhook para saber se o servidor de destino aceitou a mensagem e mantenha a chegada à caixa de entrada como um resultado separado, que a resposta da API não comprova.

Que permissão uma chave de envio do SendGrid deve ter?

Use uma chave Custom Access limitada à capacidade Mail Send exigida pelo worker. Evite Full Access para envios rotineiros e use chaves separadas, gerenciadas como segredos, para desenvolvimento, staging, produção, administração e qualquer outra carga de trabalho com autoridade significativamente diferente.

Como verificar a assinatura do Event Webhook do SendGrid?

Retenha o corpo HTTP bruto exato, leia os cabeçalhos de assinatura e de timestamp da Twilio e verifique-os antes do parsing do JSON ou de uma nova serialização. Aplique proteção contra replay, rejeite verificações que falharem e então armazene de forma durável ou coloque na fila o lote de eventos antes de confirmar o recebimento.

Um produto deve tentar novamente toda requisição Mail Send que falhar?

Não. Corrija erros de payload, autenticação, autorização, tamanho e destinatário permanente, em vez de tentar novamente. Aguarde até o reset documentado antes de repetir requisições que recebam 429, tente novamente falhas transitórias de rede e 5xx com backoff limitado e reconcilie timeouts ambíguos antes de reenviar.

As supressões do SendGrid podem ser ignoradas para e-mail transacional?

O SendGrid expõe controles de desvio, mas um produto não deve usá-los rotineiramente. Separe as classes de mensagem, respeite o descadastro ou a supressão aplicável e exija autorização documentada e histórico de auditoria para qualquer reativação excepcional ou decisão de envio baseada em política específica.

O que uma equipe deve avaliar antes de comparar o SendGrid e o SendHQ?

Compare os payloads, eventos, controles de identidade, supressões, requisitos regionais e identificadores de provedor armazenados antes de planejar uma migração.

Fontes

Continue aprendendo

Guia de implementação de API de e-mail para equipes de produtoProjete uma integração segura com uma API de e-mail usando domínios verificados, envios em fila, identificadores estáveis, novas tentativas controladas, eventos de entrega, supressão e isolamento de tenants.