Como integrar o serviço de email Resend com Edge Functions

Este guia demonstra como integrar o serviço de email Resend com Azion Edge Functions para enviar emails transacionais diretamente da edge. Esta integração fornece entrega de email rápida e confiável com performance otimizada e alcance global.

Requisitos

Antes de começar, certifique-se de ter:

Uma conta na Azion
Uma conta no Resend com acesso à API
Azion CLI instalada e configurada
Node.js versão 18 ou superior
Gerenciador de pacotes pnpm instalado
Conhecimento básico de JavaScript e Edge Functions
Chave de API do Resend do seu dashboard

Primeiros passos

Passo 1: Configure seu ambiente de desenvolvimento

Clone o repositório de exemplo do Resend:

git clone https://github.com/egermano/edge-functions-examples.git
cd edge-functions-examples/packages/resend

Instale as dependências do projeto:

pnpm install

Revise a estrutura do projeto para entender a implementação:

ls -la

Você deve ver os arquivos principais incluindo a implementação da Edge Function, arquivos de configuração e templates de email.

Passo 2: Configure as variáveis de ambiente

Crie um arquivo .env baseado no exemplo:

cp .env.example .env

Edite o arquivo .env para incluir sua chave de API do Resend:

# Configuração da API Resend
RESEND_API_KEY=sua_chave_de_api_resend_aqui

Obtenha sua chave de API do Resend no seu dashboard do Resend.

Passo 3: Configure a integração Resend

Configure seu domínio de envio no Resend (se ainda não foi feito):
- Adicione seu domínio no dashboard do Resend
- Configure registros DNS para verificação do domínio
- Verifique a propriedade do domínio
Revise templates de email em seu projeto para personalizá-los conforme suas necessidades.

Passo 4: Compile o projeto

Compile sua Edge Function para deployment:

pnpm build

Este comando compila sua Edge Function e a prepara para deployment na rede edge da Azion.

Passo 5: Teste localmente

Antes de fazer o deploy, teste sua função de email localmente:

pnpm dev

Isso inicia um servidor de desenvolvimento local onde você pode testar a funcionalidade de envio de email.

Deploy na Azion

Passo 1: Autentique-se na Azion

Faça login na sua conta Azion via CLI:

azion login

Siga os prompts de autenticação para conectar sua CLI com sua conta Azion.

Passo 2: Crie secrets para chaves de API

Para segurança, armazene sua chave de API do Resend como um secret:

azion create secret RESEND_API_KEY

Quando solicitado, digite sua chave de API do Resend. Isso garante que seus dados sensíveis sejam criptografados e seguros.

Passo 3: Faça o deploy da Edge Function

Faça o deploy de sua aplicação de email na rede edge da Azion:

azion deploy

O processo de deploy irá:

Fazer upload do código da sua Edge Function
Configurar a edge application
Configurar as regras de roteamento necessárias
Configurar variáveis de ambiente e secrets
Fornecer um domínio único

Passo 4: Acesse sua aplicação

Após o deploy, você receberá um domínio como https://xxxxxxx.map.azionedge.net. Sua aplicação de email estará disponível nesta URL em alguns minutos após a propagação do DNS.

Entendendo a implementação

Processo de envio de email

A Edge Function do Resend tipicamente manipula:

Validação de requisição: Verificação de parâmetros de email e autenticação
Composição de email: Construção de conteúdo de email com templates
Integração com API: Comunicação com a API do Resend
Manipulação de resposta: Processamento de respostas da API e erros
Logging: Registro de atividades de envio de email

Exemplo de integração com API

Veja como funciona a integração com a API do Resend:

// Exemplo de Edge Function para envio de emails
async function sendEmail(request) {
    const { to, subject, html, text } = await request.json();

    const response = await fetch('https://api.resend.com/emails', {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${RESEND_API_KEY}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            from: 'seu-email@seudominio.com',
            to: to,
            subject: subject,
            html: html,
            text: text
        })
    });

    return response.json();
}

Principais benefícios

Performance: Processamento de email na edge reduz latência
Confiabilidade: Infraestrutura robusta do Resend garante entrega
Escalabilidade: Escala automaticamente com a demanda
Alcance global: Localizações edge fornecem cobertura mundial
Eficiência de custo: Custos otimizados de entrega de email

Testando sua aplicação de email

Passo 1: Teste a funcionalidade de envio de email

Navegue até sua aplicação deployada
Use o formulário de email para enviar emails de teste
Verifique se os emails são entregues aos destinatários
Verifique formatação e conteúdo do email

Passo 2: Teste tratamento de erros

Endereços de email inválidos: Teste com endereços de email malformados
Rate limiting: Teste com requisições sucessivas rápidas
Falhas de autenticação: Teste com chaves de API inválidas
Problemas de rede: Teste tratamento de erros para falhas da API

Passo 3: Testes de performance

Tempo de resposta: Meça tempos de resposta de envio de email
Requisições simultâneas: Teste múltiplos envios de email simultâneos
Taxas de erro: Monitore taxas de sucesso e falha

Casos de uso comuns

Emails de boas-vindas: Enviar emails de onboarding para novos usuários
Redefinição de senhas: Lidar com notificações de email de redefinição de senha
Confirmações de pedidos: Enviar emails transacionais para compras
Emails de notificação: Enviar alertas e atualizações aos usuários
Formulários de contato: Lidar com submissões de formulários com notificações por email

Templates de email e personalização

Usando templates HTML

Crie templates de email dinâmicos com placeholders:

<!DOCTYPE html>
<html>
<head>
    <title>Bem-vindo ao Nosso Serviço</title>
</head>
<body>
    <h1>Bem-vindo, {{nome}}!</h1>
    <p>Obrigado por se juntar à {{empresa}}. Estamos empolgados em tê-lo conosco.</p>
    <p>Sua conta agora está ativa e pronta para uso.</p>
</body>
</html>

Variáveis de template

Substitua placeholders com conteúdo dinâmico:

const emailTemplate = html.replace('{{nome}}', userData.name)
                         .replace('{{empresa}}', 'Sua Empresa');

Solução de problemas

Problemas comuns e soluções

Falhas de entrega de email: Verifique validade da chave de API e configuração do domínio
Rate limiting: Implemente throttling de requisições adequado
Renderização de template: Verifique sintaxe do template e substituição de variáveis
Erros de autenticação: Certifique-se de que a chave de API esteja configurada corretamente como secret

Melhores práticas de tratamento de erros

Logging detalhado: Registre todas as tentativas de envio de email e resultados
Mecanismos de retry: Implemente lógica de retry para falhas temporárias
Degradação graciosa: Lide com downtime da API adequadamente
Feedback do usuário: Forneça mensagens de status claras aos usuários

Considerações de segurança

Gerenciamento de chaves de API

Use secrets: Sempre armazene chaves de API como secrets da Azion
Rotacione regularmente: Rotacione periodicamente suas chaves de API
Monitore uso: Rastreie uso de chaves de API e padrões de acesso
Limite permissões: Use chaves de API com permissões mínimas necessárias

Validação de entrada

Validação de email: Valide endereços de email antes do envio
Sanitização de conteúdo: Limpe e valide conteúdo de email
Rate limiting: Implemente rate limiting para prevenir abuso
Autenticação: Adicione autenticação adequada aos seus endpoints de email

Recursos avançados

Envio de email em lote

Implemente funcionalidade de email em lote para campanhas de newsletter e marketing:

async function sendBatchEmails(recipients, template) {
    const batchSize = 100;
    for (let i = 0; i < recipients.length; i += batchSize) {
        const batch = recipients.slice(i, i + batchSize);
        await processBatch(batch, template);
    }
}

Rastreamento de email

Adicione capacidades de rastreamento para monitorar engajamento de email:

Rastreamento de abertura: Rastreie quando emails são abertos
Rastreamento de cliques: Monitore cliques em links nos emails
Tratamento de bounce: Lide com emails bounceados adequadamente
Gerenciamento de unsubscribe: Processe solicitações de unsubscribe

Próximos passos

Explore técnicas avançadas de templateização de email
Implemente analytics e rastreamento de email
Adicione agendamento de email e envio atrasado
Integre com outros produtos Azion como Edge Storage
Monitore performance de entrega de email e otimize adequadamente