Visão geral para desenvolvedores

Esta página reúne as convenções que você precisa conhecer antes de escrever código para o Emailit: onde a API fica, como as requisições são autenticadas, como os objetos são identificados e como funcionam os erros, a paginação e os limites de requisições. Cada seção tem um link para a referência detalhada.

Formas de integração

Não sabe se deve usar a API ou o SMTP? Leia API ou SMTP.

URL base e versionamento

Todos os endpoints REST ficam sob uma única URL base:

https://api.emailit.com/v2

v2 é a versão atual e a única documentada. A API legada v1 está descontinuada; consulte Versionamento.

Autenticação

Envie uma chave de API como bearer token no cabeçalho Authorization de cada requisição:

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

• As chaves de API começam com secret_. As chaves mais antigas, sem o prefixo, continuam funcionando.
• Cada chave pertence a um workspace e tem um escopo: Full Access (full) pode chamar todos os endpoints, e Sending Only (sending) só pode enviar e gerenciar envios. Consulte Chaves de API.
• Os tokens de acesso OAuth emitidos para apps OAuth são aceitos no mesmo cabeçalho.
• Uma chave ausente retorna 401 com API key required, uma chave desconhecida retorna 401 com Invalid API key, e um workspace suspenso retorna 403 com Workspace is suspended.

Nunca chame a API a partir de um navegador ou de um app mobile com a sua chave. Mantenha-a no seu servidor. Detalhes: Autenticação.

IDs e prefixos

Todo objeto tem um ID em string com um prefixo de tipo, para você saber de imediato a que um ID se refere.

Os domínios criados antes da mudança para IDs dom_ ainda podem ter IDs sd_ ou sed_.

Alguns endpoints também aceitam um identificador legível no lugar do ID: um nome para chaves de API, domínios, webhooks, campanhas e listas de contatos, e um endereço de e-mail para contatos e supressões. E-mails, templates e eventos são buscados apenas pelo ID.

Requisições e respostas

• JSON na entrada, JSON na saída. Envie os corpos das requisições em JSON com Content-Type: application/json. Um JSON malformado retorna 400 com Invalid JSON in request body. O corpo de uma requisição pode ter até 50 MB; a mensagem MIME final de um e-mail pode ter até 40 MB.
• Erros. A maioria dos erros retorna {"statusCode", "error", "message"}. Os erros de validação adicionam um array details, e os erros de envio retornam validation_errors. Recursos restritos por plano retornam 403 com "error": "plan_required". Consulte Erros.
• Paginação. Os endpoints de listagem recebem page e limit (de 1 a 100) e retornam data, next_page_url e previous_page_url. Templates e automações usam page e per_page. Consulte Paginação.
• Filtragem e ordenação. Filtre com field.condition=value, combine filtros com match=all ou match=or e ordene com order e direction. Por exemplo, GET /v2/emails?status.exact=bounced&order=created_at&direction=desc. Consulte Filtragem.
• Idempotência. Envie um cabeçalho Idempotency-Key em POST /emails e POST /emails/:id/forward para tornar as novas tentativas seguras. O Emailit repete a primeira resposta por 24 horas. Consulte Idempotência.
• Limites de requisições. O envio é limitado por workspace, por padrão a 2 e-mails por segundo e 5.000 e-mails por dia, compartilhados entre a API e o SMTP. As respostas incluem cabeçalhos ratelimit-*, e um 429 inclui retry-after. Consulte Limites de requisições e Limites.

SDKs

As bibliotecas oficiais encapsulam a API REST para Node.js, PHP, Laravel, Python, Ruby, Go, Java, .NET e Rust. Todas estão no GitHub. Consulte SDKs e bibliotecas para os comandos de instalação e os guias de frameworks para exemplos completos, começando por Node.js.

Webhooks

Os webhooks enviam eventos para o seu endpoint à medida que acontecem: entregas, bounces, aberturas, cliques, e-mails recebidos e alterações em domínios, contatos e outros recursos. Cada requisição leva um array JSON de até 100 eventos e é assinada com HMAC-SHA256 no cabeçalho X-Emailit-Signature. As requisições com falha recebem até 11 tentativas. Comece por Configurar um webhook e Assinatura das requisições.

Servidor MCP e ferramentas de IA

O servidor MCP hospedado em https://api.emailit.com/mcp dá aos assistentes de IA 109 ferramentas que cobrem toda a API v2, do envio de e-mails a campanhas e automações. Os assistentes fazem login com OAuth ou com uma chave de API, e os plugins do Emailit adicionam skills para ChatGPT, Codex, Claude Code, Cursor e Grok.

A documentação também é publicada para IA: cada página tem uma versão em Markdown, e o /docs/llms.txt indexa todas elas.

Próximos passos