Como uma equipe de produto deve implementar a API de e-mail do Resend com segurança?

Defina a operação do produto antes da requisição ao provedor

Comece com uma operação de aplicação bem delimitada, como verificação de conta, um recibo, um alerta de segurança ou uma notificação que o destinatário solicitou. O endpoint público do produto deve autorizar quem chama, o tenant, a classe da mensagem, a identidade do remetente, os destinatários e o template antes que exista qualquer payload para o Resend. Não permita que um navegador envie `from`, `to`, HTML ou opções do provedor arbitrários usando uma credencial reutilizável. Crie um registro interno de saída durável contendo uma chave de evento da aplicação, o tenant, a revisão do template, o remetente aprovado, o conjunto de destinatários e o estado atual. Um worker pode traduzir esse registro na requisição ao provedor. Essa fronteira mantém as chaves de API e o conteúdo de mensagens não confiável longe dos clientes, torna a prevenção de duplicatas testável e permite que o produto troque de provedor sem reescrever cada fluxo de negócio. Separe no modelo interno as mensagens transacionais das que dependem de consentimento, para que preferências, supressões e decisões em incidentes continuem explícitas.

Verifique o domínio exato usado no endereço From

Adicione no Resend um domínio que você controla e publique os registros DNS exibidos para esse domínio. Verifique o domínio organizacional ou subdomínio realmente usado no endereço From visível, em vez de presumir que uma identidade pai não relacionada o cobre. Revise a política de SPF e DMARC existente antes de alterar o DNS e nunca crie um segundo registro SPF para o mesmo hostname. Use um subdomínio de envio com finalidade específica quando requisitos de isolamento, propriedade ou migração o justificarem. Depois que o painel indicar a verificação, inspecione uma mensagem de teste recebida para confirmar o endereço From visível, a identidade de assinatura DKIM, o return path, os resultados de autenticação e o comportamento das respostas. A verificação pelo provedor prova que uma identidade configurada passou na checagem de configuração do provedor. Ela não prova consentimento do destinatário, aceitação pelo servidor de destino, chegada à caixa de entrada nem boa reputação. Mantenha a propriedade do DNS e o histórico de alterações fora do painel do provedor, para que a rotação e o rollback continuem possíveis.

Crie uma chave de API com privilégio mínimo para cada carga de trabalho

O Resend documenta chaves de API com níveis de acesso e restrição opcional por domínio. Um worker de envio deve usar uma chave limitada ao acesso de envio e, quando a arquitetura permitir, ao único domínio que essa carga de trabalho controla. Mantenha a administração de gerenciamento, domínios, webhooks e conta sob uma autoridade separada. Crie chaves separadas para desenvolvimento, staging e produção, para que um ambiente inferior não possa enviar com a identidade de produção nem consumir os limites dela. Armazene cada segredo diretamente em um gerenciador de segredos, exponha-o apenas ao processo de servidor que precisa dele e passe-o como autorização Bearer via HTTPS. Não copie a chave para o controle de versão, artefatos de build, logs, templates, analytics, tickets ou prompts. A rotação deve ser ensaiada: crie uma substituta com o mesmo escopo, atualize o worker, verifique o tráfego controlado e a correlação de eventos e, então, revogue a chave antiga. Crie alertas para falhas inesperadas de autenticação e autorização, porque elas podem indicar expiração, revogação, desvio de escopo ou exposição do segredo.

Crie um job durável e uma tentativa de envio idempotente

Reserve o job interno de saída antes de chamar o Resend. Obtenha um valor de idempotência de um fato estável do produto, como o tenant, o tipo de operação e o ID imutável do evento da aplicação, e não de uma tentativa aleatória. Envie esse valor no cabeçalho `Idempotency-Key`. Atualmente, o Resend documenta que essas chaves evitam requisições de e-mail duplicadas, expiram após 24 horas e podem ter no máximo 256 caracteres. Essa janela do provedor ajuda, mas não é uma garantia completa contra duplicatas no nível do produto. Mantenha uma restrição de unicidade na chave interna do evento para fluxos de negócio mais longos, execute de forma serial os workers que podem assumir o mesmo job e armazene o ID do e-mail retornado por uma requisição bem-sucedida. Se um timeout de rede tornar a aceitação ambígua, mantenha o job em um estado desconhecido e faça a conciliação com os logs ou eventos do provedor antes de reenviar. Reutilizar uma chave estável para a mesma operação lógica é mais seguro do que gerar uma chave nova a cada nova tentativa de transporte.

Monte e valide a requisição de e-mail de forma deliberada

O endpoint de envio de e-mail do Resend aceita um endereço From, destinatários, assunto e conteúdo da mensagem, com opções documentadas como texto, HTML, conteúdo renderizado com React, templates, Cc, Bcc, reply-to, cabeçalhos, anexos, tags e entrega agendada. Exponha apenas o subconjunto de que o produto precisa. Valide a sintaxe dos endereços e a propriedade pelo tenant, limite a quantidade de destinatários e anexos abaixo dos limites do provedor, rejeite injeção de quebras de linha nos cabeçalhos e monte o conteúdo relacionado ao MIME com bibliotecas mantidas ou com campos confiáveis do provedor. Não coloque credenciais, dados pessoais sensíveis ou entradas irrestritas de clientes em tags ou cabeçalhos. Armazene a revisão do template e as variáveis sanitizadas, em vez de registrar o conteúdo completo. Um adaptador interno deve retornar um resultado enxuto, como o ID de aceitação do provedor ou uma falha classificada, sem vazar detalhes da resposta do provedor para o código de negócio. Isso permite atualizar nomes de campos específicos do provedor, versões de SDK ou limites de requisição sem mudar o contrato de eventos do produto.

Classifique as respostas da API e os limites de uso antes de tentar novamente

Trate a resposta HTTP como uma observação dentro do fluxo. Uma resposta de envio bem-sucedida retorna um identificador de e-mail que deve ser armazenado com o job interno, mas ela não garante a aceitação pelo destino nem a chegada à caixa de entrada. Corrija erros de validação, autenticação, domínio, permissão e payload, em vez de tentar novamente às cegas. O Resend documenta limites de requisições à API e retorna cabeçalhos de limite de taxa e de cota, incluindo campos que descrevem a capacidade restante, o momento do reset e o intervalo para nova tentativa; uma resposta 429 deve aguardar o intervalo documentado, com jitter adicional. Tente novamente falhas de transporte e erros de servidor elegíveis com backoff exponencial, um número finito de tentativas e a mesma chave de idempotência lógica enquanto a janela documentada dela valer. Falhas ambíguas exigem conciliação, porque o provedor pode ter aceitado o e-mail mesmo quando o cliente não recebeu a resposta. Crie alertas quando falhas repetidas se concentrarem por domínio, template, chave ou tenant, mas mantenha credenciais, conteúdo completo e dados desnecessários de destinatários fora dos logs operacionais.

Autentique as requisições de webhook antes de processar os eventos

Configure um endpoint HTTPS dedicado para webhooks e guarde o corpo bruto exato da requisição. O Resend documenta a assinatura de webhooks por meio de cabeçalhos compatíveis com o Svix e de segredos de assinatura. Verifique o ID do webhook, o timestamp e a assinatura sobre o payload não modificado antes do parsing ou da reserialização do JSON, e use o fluxo oficial de verificação ou uma biblioteca compatível mantida. Rejeite requisições inválidas ou antigas, limite o tamanho da requisição e mantenha o segredo de assinatura separado da chave de envio. Depois da autenticação, armazene ou enfileire o evento de forma durável antes de confirmar o recebimento, para que a queda de um processo não descarte silenciosamente evidências de entrega. Os sistemas de entrega podem reenviar e duplicar webhooks, então use o identificador do evento como chave de deduplicação e torne as transições de estado monotônicas. Um evento posterior ou duplicado não deve sobrescrever um resultado final mais informativo só porque chegou por último. Registre as falhas de verificação e o atraso dos eventos como sinais operacionais, sem persistir o conteúdo bruto das mensagens além do período de retenção necessário.

Modele os eventos do provedor sem exagerar a entrega

O Resend publica tipos de evento de e-mail nomeados, incluindo sent, delivered, delivery delayed, bounced, complained, failed, opened e clicked. Mapeie esses nomes do provedor para um modelo de estado interno com o tipo de evento original, o ID do e-mail no provedor, o ID do evento, o timestamp, o escopo do destinatário e os dados de diagnóstico disponíveis. Um evento sent descreve o progresso no provedor. Um evento delivered informa a entrega segundo a semântica de eventos documentada pelo Resend, mas o sucesso SMTP em um sistema de destino ainda não revela a pasta final do destinatário. Aberturas e cliques são observações de engajamento, e não prova de entrega, e tecnologias de privacidade podem afetá-los. Bounces, reclamações e falhas permanentes devem atualizar o estado de segurança do destinatário antes da próxima decisão de envio. Mantenha o histórico de eventos do provedor somente com acréscimos e derive o status exibido ao usuário por meio de regras explícitas. Isso preserva as evidências para o suporte e evita novas tentativas inseguras depois que a responsabilidade foi transferida ou que um destinatário deu um sinal negativo.

Teste os caminhos de falha e de recuperação com destinatários controlados

Use uma chave que não seja de produção, um subdomínio verificado e controlado e caixas postais pertencentes à equipe. Teste conteúdo em texto e HTML, o comportamento do reply-to, os limites de anexos, as chaves de idempotência estáveis e os identificadores do provedor armazenados. Envie o mesmo job lógico duas vezes e confirme que os controles da aplicação e do provedor não criam uma duplicata indesejada. Exercite payload inválido, domínio errado, chave revogada, permissão insuficiente, limite de taxa, timeout de transporte, bounce, reclamação, atraso na entrega, webhook duplicado, corpo de assinatura modificado, timestamp de webhook antigo e rotação do segredo de assinatura. Confirme que a entrada dos eventos é durável antes da confirmação e que a segurança do destinatário bloqueia um job posterior. Teste a rotação de DNS e a remoção do provedor sem excluir registros não relacionados. Os painéis devem cobrir falhas de envio, latência, falhas de verificação de webhooks, atraso de eventos, bounces, reclamações e filas de conciliação. Revise a documentação atual do Resend e as configurações da conta no lançamento, porque cotas, limites, campos de eventos e permissões disponíveis podem mudar independentemente do código da aplicação implantado.

Compare os recursos de API publicados antes de migrar

O SendHQ publica um contrato OpenAPI 3.1 para sua API de e-mail com escopo por workspace, incluindo envio com domínio verificado, e-mail de entrada, templates hospedados, eventos de entrega e supressões. Antes de migrar uma integração, compare corpos de requisição, autenticação, idempotência, identificadores retornados, formatos de erro, webhooks, regras de domínio e comportamento de supressão; depois, valide-os com testes no nível de campo. Não presuma compatibilidade por nomes de endpoint semelhantes.

Perguntas frequentes

Fontes

• Resend Send Email API — Resend (em inglês)
• Resend API Keys — Resend (em inglês)
• Resend Domains — Resend (em inglês)
• Resend Idempotency Keys — Resend (em inglês)
• Resend Usage Limits — Resend (em inglês)
• Resend Webhooks — Resend (em inglês)
• Verify Resend Webhook Requests — Resend (em inglês)
• Resend Webhook Event Types — Resend (em inglês)
• RFC 5321: Simple Mail Transfer Protocol — RFC Editor (em inglês)
• Contrato OpenAPI do SendHQ — SendHQ