Skip to main content
Você pode enviar a chave de duas formas (escolha a que seu framework preferir): Opção A (Padrão Recomendado): 
Authorization: Bearer sk_live_sua_chave_aqui
Opção B (Header Customizado): 
x-api-key: sk_live_sua_chave_aqui
A API Key está sempre vinculada a um único Workspace. Todas as operações de e-mail (enviar, consultar status, cancelar, gerenciar domínios) ocorrem dentro desse contexto. Você não consegue acessar dados de outro workspace com a mesma chave.

​
Tabela de Escopos (Permissões)

Ao criar uma API Key, você define o que ela pode fazer. Se você deixar a lista de escopos vazia, a chave terá acesso ADMIN (todas as operações permitidas). Para segurança, recomendamos restringir.

​
Escopos por envio e consulta

  • email:send Enviar e-mail(s). O domínio do remetente (from) deve estar verificado.
  • email:read Listar e-mails (GET /v1/email/messages) e consultar por ID (GET /v1/email/messages/{id}). Com domainIds na chave, a listagem fica limitada a esses domínios.
  • email:cancel Cancelar um e-mail agendado (status SCHEDULED). Os créditos são devolvidos ao workspace.

​
Escopos por domínios

  • email:domains:list Listar domínios do workspace, obter domínio por ID e verificar status DNS.
  • email:domains:create Registrar novo domínio para verificação DNS.

​
Restrição por domínio

Além dos escopos (O QUE fazer), você pode limitar de quais domínios a chave pode enviar e-mail. Se a sua API Key tiver o campo domainIds preenchido, ela só poderá enviar e-mail usando remetentes (from) cujo domínio esteja nessa lista. Domínios devem estar verificados no workspace.
  • Tentar enviar com um domínio não listado = 403 Forbidden com code: DOMAIN_NOT_ALLOWED.
  • Lista vazia ou não definida = a chave pode usar qualquer domínio verificado do workspace.

​
Respostas de Erro de Autenticação

Se algo der errado com sua chave, a API retorna códigos HTTP claros para facilitar o debug:
Verifique se o header está correto e se a chave não foi apagada no painel.
Verifique se a chave tem o Escopo necessário para a rota. Se a chave tiver domainIds definidos, o domínio do remetente (from) deve estar na lista (code: DOMAIN_NOT_ALLOWED). Para envio, verifique também se não excedeu créditos ou limite do plano (code: PLAN_LIMIT_CREDITS). Agendamento pode não estar permitido no plano (PLAN_LIMIT_SCHEDULING).