Chaves de API

As chaves de API autenticam as suas requisições à API REST, as suas conexões SMTP e as sessões com chave de API no servidor MCP. Esta página explica os dois escopos de chave, como criar e gerenciar chaves e como guardá-las e fazer a rotação delas com segurança.

Como as chaves de API funcionam

• Cada chave pertence a um workspace. Tudo o que você faz com ela acontece nesse workspace.
• As chaves novas começam com secret_ seguido de 32 letras e dígitos, por exemplo, secret_••••••••. As chaves criadas antes da introdução do prefixo continuam funcionando.
• O Emailit mostra a chave completa uma única vez, quando você a cria ou regenera. Copie-a nesse momento; não é possível vê-la de novo.
• Envie a chave como bearer token: Authorization: Bearer secret_…. No SMTP, a chave é a senha.

Escopos

Toda chave tem um de dois escopos. Você escolhe o escopo ao criar a chave.

Uma chave Sending Only que chama qualquer outro endpoint recebe 403 com uma mensagem como Permission denied: read. Use chaves Full Access para tarefas internas que gerenciam recursos e chaves Sending Only para tudo o que só precisa enviar.

Restringir uma chave a um domínio

Ao criar uma chave Sending Only, você pode escolher um domínio de envio verificado. A chave passa a enviar apenas de endereços desse domínio:

• Pela API, enviar de outro domínio retorna 403 com "error": "Domain not authorized".
• Pelo SMTP, a mensagem é rejeitada depois de DATA com 530 API key is restricted to sending domain: ….

As chaves restritas são uma boa escolha para credenciais por aplicação ou por cliente, e para chaves que você precisa entregar a software de terceiros, como um plugin de CMS.

Antes de começar

• É preciso ter o papel Admin no workspace para criar, editar, regenerar ou excluir chaves. Membros com o papel Member podem ver a lista de chaves, mas não alterá-la. Consulte Membros e papéis.
• Para enviar com uma chave, você precisa de pelo menos um domínio de envio verificado.

Criar uma chave de API

curl https://api.emailit.com/v2/api-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-web",
    "scope": "sending",
    "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6"
  }'

{
  "object": "api_key",
  "id": "key_4F2kN8sQwE1rT6yU3iO9pA7sD5f",
  "name": "production-web",
  "scope": "sending",
  "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6",
  "last_used_at": null,
  "created_at": "2026-10-01T09:30:00.000Z",
  "updated_at": "2026-10-01T09:30:00.000Z",
  "key": "secret_••••••••••••••••••••••••••••••••"
}

Usar a chave

Passe a chave no cabeçalho Authorization de cada requisição à API:

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Your order has shipped",
    "text": "Your order #1042 is on its way."
  }'

Para enviar por SMTP, use a chave como senha:

Consulte Configurações de SMTP para ver todas as opções.

Gerenciar chaves

Abra uma chave em Email API›API Keys para ver o escopo, o domínio, a data em Created, o horário em Last used e as configurações de SMTP a usar com ela.

Last used é atualizado sempre que a chave autentica uma requisição à API ou um login SMTP. Uma chave que nunca foi usada mostra Never. Na API, os endpoints que recebem o ID de uma chave também aceitam o nome dela.

Guardar as chaves com segurança

• Mantenha as chaves no servidor. Nunca coloque uma chave em JavaScript do navegador, em um app mobile, em um repositório público ou em um chamado de suporte. Qualquer pessoa com a chave pode enviar e-mails em seu nome e gastar os seus créditos.
• Use variáveis de ambiente ou um gerenciador de segredos. Carregue a chave em tempo de execução, por exemplo, de EMAILIT_API_KEY. Adicione os arquivos .env ao .gitignore.
• Dê a cada aplicação e ambiente a sua própria chave. Chaves separadas para produção, homologação e cada ferramenta de terceiros facilitam ver quem enviou o quê e revogar uma sem mexer nas outras.
• Use o escopo mais restrito. Se uma aplicação só envia e-mails, dê a ela uma chave Sending Only, restrita ao domínio dela sempre que possível.
• Acompanhe o uso. Email API›Logs lista as requisições à API e ao SMTP por chave, e você pode filtrar Email API›Emails por chave de API. Consulte Logs de requisições.
• Aja rápido em caso de vazamento. Se uma chave for exposta, regenere-a ou exclua-a na hora e depois verifique nos logs se houve envios inesperados.

Fazer a rotação de uma chave sem interrupção

Regenerar uma chave invalida o segredo antigo na hora, então faça isso só quando uma chave estiver comprometida. Para uma rotação planejada, use a chave antiga e a nova lado a lado:

1. Crie uma chave nova. Adicione uma chave com o mesmo escopo e a mesma restrição de domínio da chave que você vai substituir. Dê a ela um nome que indique a data, como production-web-2026-10.

2. Faça o deploy da chave nova. Atualize o segredo no seu gerenciador de segredos ou no ambiente e distribua-o para todos os servidores, workers e jobs agendados que usam a chave antiga.

3. Confirme a troca. Abra a chave nova e confira se Last used é recente. Em Email API›Logs, filtre pela chave antiga e confira se as requisições pararam.

4. Exclua a chave antiga. Quando o horário em Last used da chave antiga parar de mudar, exclua-a.

Solução de problemas

Veja também