Autenticação

Toda requisição à API do Emailit precisa levar uma credencial no cabeçalho Authorization. Esta página explica os dois tipos de credencial (chaves de API e tokens de acesso OAuth), o que cada escopo permite fazer e todos os erros de autenticação que você pode receber.

Chaves de API

Uma chave de API pertence a um workspace, e toda requisição feita com ela atua nesse workspace. As chaves têm esta aparência:

secret_Xq7pL2mN9vB4kR8tW1yZ6cH3jF5dS0aG

Ou seja, secret_ seguido de 32 letras e dígitos. Chaves criadas antes do formato secret_ não têm prefixo e continuam funcionando.

Crie chaves no painel em Email API›API Keys ou com Criar uma chave de API. O segredo é exibido uma única vez, quando você cria ou regenera a chave, então guarde-o imediatamente. Consulte Chaves de API para gerenciá-las.

As mesmas chaves funcionam como senha SMTP no SMTP relay.

Enviar a chave em cada requisição

Use o esquema Bearer no cabeçalho Authorization. A API não aceita chaves em parâmetros de consulta nem no corpo da requisição.

curl https://api.emailit.com/v2/domains \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

const response = await fetch('https://api.emailit.com/v2/domains', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const domains = await response.json();

import os
import requests

response = requests.get(
    "https://api.emailit.com/v2/domains",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
domains = response.json()

Quando você passa a chave para o cliente, os SDKs definem esse cabeçalho por você.

Escopos

Cada chave tem um de dois escopos. Você o escolhe ao criar a chave e não pode alterá-lo depois.

Uma chave sending pode chamar estes endpoints e nenhum outro:

Ler e-mails (listar, obter, MIME bruto, corpo, metadados, anexos e status) exige uma chave full. Quando uma chave sending chama qualquer outro endpoint, a API retorna 403 com Permission denied: full (ou Permission denied: read nos endpoints de leitura de e-mails).

A página Todos os endpoints mostra o escopo de cada endpoint.

Restringir uma chave a um domínio

Uma chave sending também pode ficar presa a um único domínio de envio. Passe o ID do domínio em sending_domain_id ao criar a chave. Uma chave restrita só pode enviar de endereços desse domínio. Qualquer outro domínio em from retorna 403:

{
  "error": "Domain not authorized",
  "message": "API key is not authorized to send from this domain"
}

As restrições de domínio se aplicam apenas a chaves sending. Uma chave full sempre tem acesso a todos os domínios do workspace.

Tokens de acesso OAuth

Apps que agem em nome de um usuário do Emailit, como clientes MCP e integrações de terceiros, não pedem uma chave de API. Em vez disso, eles usam OAuth 2.1: o usuário entra no Emailit, escolhe os workspaces que o app pode usar (todos ou apenas os selecionados) e aprova o escopo sending ou full, e o app recebe um token de acesso. O usuário pode alterar ou revogar esse acesso em Connected apps.

Envie os tokens de acesso no mesmo cabeçalho das chaves de API:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…

Um token de acesso vale por 15 minutos e atua no workspace padrão da autorização, com o escopo concedido e o papel do usuário nesse workspace. Os apps o renovam com o token de atualização. Consulte Apps OAuth para criar um.

Erros de autenticação

A autenticação é executada antes de qualquer outra coisa, então esses erros podem vir de qualquer endpoint.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Permission denied: full"
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Workspace is suspended"
}

{
  "code": "unverified_workspace_recipient",
  "error": "Workspace not verified",
  "message": "Unverified workspaces can only send to workspace members' account emails. Blocked recipient: ada@example.com.",
  "blocked_recipients": ["ada@example.com"]
}

Workspaces não verificados

Workspaces novos começam não verificados. Até o Emailit aprovar o acesso de produção, a API só envia para os endereços de e-mail das contas dos membros do workspace. Enviar, tentar de novo ou encaminhar para qualquer outra pessoa retorna 403 com o código unverified_workspace_recipient e a lista blocked_recipients, e as campanhas não podem ser enviadas de forma alguma. As suas chaves de API funcionam normalmente para todo o resto.

Manter as chaves em segredo

Uma chave de API dá acesso ao seu workspace, então trate-a como uma senha.

• Chame a API apenas do seu servidor. Nunca coloque uma chave em JavaScript de navegador, em um app para celular nem em qualquer outro código que rode no dispositivo de outra pessoa.
• Mantenha as chaves fora do controle de versão. Carregue-as de variáveis de ambiente ou de um gerenciador de segredos.
• Crie uma chave por aplicação e por ambiente, com um nome que indique onde ela é usada, para poder revogar uma sem quebrar as outras.
• Dê a cada chave apenas o acesso de que ela precisa: uma chave sending restrita a um domínio é suficiente para a maioria das aplicações.
• Confira last_used_at em Listar chaves de API e exclua as chaves que você não usa mais.
• Se uma chave vazar, regenere ou exclua a chave imediatamente. O segredo antigo para de funcionar na hora.

Veja também