Como Obter uma Chave API Resend e Enviar Seu Primeiro Email

Resend é uma API de e-mail construída para desenvolvedores: uma requisição POST, um corpo JSON, e um e-mail transacional é enviado. Cada requisição precisa de uma chave de API, e a forma como você cria essa chave decide o quão grande pode ser o dano de uma chave vazada. Este guia percorre todo o caminho: inscrever-se, verificar um domínio de envio (ou usar o endereço de teste integrado), criar uma chave com o escopo de permissão correto e enviar seu primeiro e-mail com curl, Node e Python. Você também armazenará a chave no Apidog para poder testar o endpoint sem colar segredos em seu shell.

Se você quiser uma visão mais ampla do que a API faz além do envio, o guia para iniciantes da API Resend cobre o restante. Tudo abaixo é verificado em relação à documentação oficial do Resend, então os números e strings de erro correspondem ao que você verá.

O que você precisa antes de começar

• Uma conta Resend. O plano gratuito é suficiente para este tutorial.
• Um domínio que você controla. Se você não tiver um à mão, o endereço de teste cobre o primeiro envio.
• curl em sua máquina, mais Node.js ou Python se você quiser os exemplos de SDK.
• Apidog instalado se você planeja seguir a seção de testes.

Passo 1: Crie uma conta Resend

Inscreva-se em resend.com e confirme seu e-mail. Anote o endereço com o qual você se inscreveu: até que você verifique um domínio, é a única caixa de entrada para a qual o Resend entregará e-mails de teste, e esquecer isso causa o 403 mais confuso que você verá no primeiro dia.

Passo 2: Verifique um domínio de envio, ou use o endereço de teste

Duas rotas; comece com a mais rápida.

Rota A: o endereço de teste de onboarding. Resend permite que você envie de onboarding@resend.dev sem nenhuma configuração. A ressalva é o destinatário: deve ser o seu próprio e-mail da conta. Envie para qualquer outra pessoa e a API retornará um 403 com a mensagem "Você só pode enviar e-mails de teste para o seu próprio endereço de e-mail".

Rota B: seu próprio domínio. Para qualquer coisa real, adicione um domínio no painel em Domínios. Resend recomenda um subdomínio como notifications.example.com em vez do seu domínio raiz, para que a reputação de envio do seu produto permaneça separada do seu e-mail corporativo. Escolha a região mais próxima dos seus destinatários e, em seguida, copie os registros DNS que o Resend gera para o seu provedor de DNS. A documentação os descreve como "as configurações DKIM e SPF (registros TXT e MX ou CNAME)". O subdomínio Return-Path padrão é send.example.com.

A verificação geralmente é concluída em 15 minutos, embora a propagação do DNS possa levar até 72 horas. Se ela travar, verifique dois culpados clássicos: registros colocados na raiz em vez do subdomínio send, e o proxy do Cloudflare (o ícone da nuvem deve ser cinza, não laranja). Corrija os registros e, em seguida, clique em "Reiniciar verificação". Adicione um registro DMARC depois; não é necessário para enviar, mas os provedores de caixa de entrada o recompensam.

Passo 3: Crie a chave de API com o escopo correto

Abra a página de chaves de API no painel e clique em Criar Chave de API. Três campos importam; a documentação criar uma chave de API cobre cada um:

• Nome. Até 50 caracteres. Nomeie-o para o aplicativo e ambiente, como billing-service-prod, para que as chaves sejam fáceis de distinguir mais tarde.
• Permissão. "Acesso total" pode criar, excluir, obter e atualizar qualquer recurso, incluindo domínios e outras chaves de API. "Acesso de envio" só pode enviar e-mails. Escolha acesso de envio para qualquer coisa implantada. A chave de acesso total pertence ao seu laptop, ou a lugar nenhum.
• Domínio. Com acesso de envio, você pode restringir a chave a um domínio verificado. Uma chave com escopo para notifications.example.com não pode enviar de billing.example.com, o que limita o raio de explosão de um vazamento.

Resend mostra a chave exatamente uma vez. Ela começa com re_, e depois que você fechar a caixa de diálogo, você pode renomear a chave, mas nunca mais poderá vê-la. Copie-a diretamente para uma variável de ambiente:

export RESEND_API_KEY="re_xxxxxxxxx"

A própria orientação do Resend: as chaves nunca expiram, então gire-as a cada 90 dias ou antes; o painel sinaliza qualquer chave não usada por 30 dias; e se uma chave vazar, exclua-a imediatamente em vez de esperar pela próxima rotação. Commitar strings re_ para o git é o caminho de vazamento mais comum, então execute um scanner de segredos em seus repositórios antes do primeiro push.

Você também pode emitir chaves com POST https://api.resend.com/api-keys, passando name, permission (full_access ou sending_access) e um domain_id opcional. Essa chamada precisa de uma chave de acesso total, mais um motivo para manter exatamente uma delas.

Passo 4: Envie seu primeiro e-mail

O endpoint de envio é POST https://api.resend.com/emails. A autenticação é um token Bearer no cabeçalho Authorization, o corpo é JSON, e apenas HTTPS é aceito. Três campos são obrigatórios: from, to e subject. Adicione html, text, ou ambos; se você enviar apenas html, o Resend gera a parte em texto simples. to aceita uma string ou um array de até 50 endereços. A lista completa de parâmetros está na referência de envio de e-mail.

curl

curl -X POST 'https://api.resend.com/emails' \
  -H "Authorization: Bearer $RESEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <onboarding@resend.dev>",
    "to": ["you@yourcompany.com"],
    "subject": "First Resend email",
    "html": "<p>Your Resend key works.</p>"
  }'

Uma chamada bem-sucedida retorna {"id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"}. Uma peculiaridade: cada requisição deve conter um cabeçalho User-Agent, caso contrário, a API responde 403 com o código 1010. curl e os SDKs definem um; um cliente feito à mão em um runtime de borda pode não.

Node.js

npm install resend

import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

const { data, error } = await resend.emails.send({
  from: 'Acme <notifications@example.com>',
  to: ['you@yourcompany.com'],
  subject: 'First Resend email',
  html: '<p>Your Resend key works.</p>',
});

if (error) {
  console.error(error);
} else {
  console.log(data.id);
}

O SDK Node nunca lança erros para erros de API. Ele retorna { data, error }, então verifique error antes de acessar data.id.

Python

import os
import resend
from resend.exceptions import ResendError

resend.api_key = os.environ["RESEND_API_KEY"]

params: resend.Emails.SendParams = {
    "from": "Acme <notifications@example.com>",
    "to": ["you@yourcompany.com"],
    "subject": "First Resend email",
    "html": "<p>Your Resend key works.</p>",
}

try:
    email = resend.Emails.send(params)
    print(email["id"])
except ResendError as err:
    print(err)

O SDK Python faz o oposto: ele lança ResendError em caso de falha, então envolva os envios em try/except.

Passo 5: Armazene e teste a chave no Apidog

Curl prova que a chave funciona uma vez. O Apidog transforma essa única vez em algo que sua equipe pode executar novamente, e mantém a chave fora do histórico do shell e dos logs de bate-papo.

Armazene a chave como uma variável secreta. Crie um ambiente chamado Resend, adicione RESEND_API_KEY como uma variável e marque-a como secreta para que o valor seja mascarado na UI e omitido das exportações. O guia de ambientes e variáveis secretas cobre divisões de dev, staging e prod se você mantiver uma chave de envio diferente por ambiente, o que você deveria fazer.

Envie a requisição. Crie uma requisição POST para https://api.resend.com/emails, defina Auth para Bearer Token com {{RESEND_API_KEY}}, e cole o corpo JSON do exemplo do curl. Clique em Enviar. O id aparece no painel de resposta ao lado dos cabeçalhos de limite de taxa cobertos abaixo.

Salve-o como um teste. Adicione duas asserções: status é igual a 200 e $.id existe. Coloque a requisição em um cenário de teste e você terá um teste de fumaça que é executado sempre que alguém mexe no código de e-mail. Aponte-o para o staging com uma chave de envio restrita ao domínio e é seguro executá-lo a partir do CI.

Simule o endpoint para trabalho de frontend. Seu frontend precisa do formato da resposta, não de um envio real. Simule o endpoint no Apidog para que ele retorne {"id": "mock-email-id"} em cada chamada. A equipe de UI pode construir o estado "e-mail enviado" o dia todo sem usar a cota gratuita de 100 por dia ou enviar spam para uma caixa de entrada real. Baixe o Apidog para configurar isso; o plano gratuito cobre quatro usuários.

Limites do plano gratuito que você atingirá primeiro

A página de preços do Resend lista o plano gratuito com 3.000 e-mails por mês, limitado a 100 por dia, com 3 domínios e retenção de dados de 30 dias. O plano Pro começa em $20 por mês para 50.000 e-mails, 10 domínios e sem limite diário, com excedente a $0.90 por 1.000 e-mails.

E-mails de teste para os endereços resend.dev contam para essas cotas, então um teste de carga direcionado a delivered@resend.dev ainda gasta seus 100 diários. bounced@resend.dev, complained@resend.dev e suppressed@resend.dev simulam um hard bounce, uma reclamação de spam e um destinatário suprimido sem endereços ruins reais.

Separado da cota, o limite de taxa padrão é de 10 requisições por segundo por equipe, compartilhado entre todas as chaves da equipe. Cada resposta contém os cabeçalhos ratelimit-limit, ratelimit-remaining, ratelimit-reset e retry-after, para que um loop de envio possa recuar antes de atingir um 429. Precisa de mais? O Resend pede para você entrar em contato com o suporte em vez de criar equipes extras.

Erros comuns e como corrigi-los

Cada falha retorna como JSON com um statusCode, um name e uma message. Estes são os que você encontrará no primeiro dia, da referência de erros:

Um 401 com uma chave que você tem certeza que está correta geralmente significa uma nova linha no final da variável ou um arquivo .env que nunca carregou. Ambos parecem uma chave ausente do lado da API.

FAQ

Posso ver minha chave de API Resend novamente depois de criá-la?

Não. Resend mostra o valor uma vez no momento da criação. Se você perdê-la, crie uma nova chave com o mesmo nome e permissão, implante-a e depois exclua a antiga.

Devo escolher acesso total ou acesso de envio?

Acesso de envio, restrito a um domínio, para cada chave que sai da sua máquina. Mantenha uma chave de acesso total para trabalhos de estilo de painel, como adicionar domínios ou criar outras chaves, e nunca a inclua em um aplicativo.

Posso testar o envio sem verificar um domínio?

Sim. Use onboarding@resend.dev como o endereço from e o e-mail da sua própria conta como destinatário. Qualquer outro destinatário retornará um 403 até que um domínio seja verificado.

Existe uma maneira de gerenciar o Resend a partir do terminal em vez do painel?

Sim. O passo a passo do CLI do Resend cobre a instalação e a execução dos comandos comuns de domínio e e-mail sem abrir um navegador.

O que acontece quando eu excedo 100 e-mails em um dia no plano gratuito?

A API retorna um 429 com daily_quota_exceeded, e os envios são retomados após o reset diário. Se você precisar regularmente de mais, o Pro remove o limite, e o resumo das APIs de e-mail gratuitas mostra como os planos gratuitos de outros provedores se comparam.

Conclusão

Obter uma chave de API Resend leva dois minutos; fazê-lo corretamente leva cinco. Verifique um subdomínio, crie uma chave de somente envio bloqueada para esse domínio, mantenha-a em uma variável de ambiente e envie um e-mail com curl para confirmar a viagem de ida e volta. Em seguida, mova a requisição para o Apidog, salve as asserções e simule o endpoint para que o restante da sua equipe possa construir sobre ele sem gastar sua cota. Envie a chave menos poderosa que ainda faz o trabalho.