# Visão geral para desenvolvedores

> URL base, autenticação, IDs de objeto, erros, paginação, limites de requisições, SDKs, webhooks e MCP. As convenções que toda integração com o Emailit compartilha.

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

| Interface | Endpoint | Para que usar |
| --- | --- | --- |
| API REST | `https://api.emailit.com/v2` | Enviar e-mails e gerenciar todos os recursos pelo código. |
| SMTP relay | `smtp.emailit.com` | Aplicações, frameworks e CMSs que já falam SMTP. Consulte [Configurações de SMTP](/pt/docs/smtp/settings/). |
| Webhooks | O seu endpoint HTTPS | Eventos de entrega, de engajamento e de recursos em tempo real. |
| Servidor MCP | `https://api.emailit.com/mcp` | Permitir que assistentes de IA como Claude, ChatGPT e Cursor trabalhem com o seu workspace. |
| OAuth 2.1 | `https://api.emailit.com/oauth/*` | Integrações que agem em nome de usuários do Emailit sem lidar com as chaves de API deles. |

Não sabe se deve usar a API ou o SMTP? Leia [API ou SMTP](/pt/docs/get-started/api-or-smtp/).

## URL base e versionamento

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

```text
https://api.emailit.com/v2
```

`v2` é a versão atual e a única documentada. A API legada `v1` está descontinuada; consulte [Versionamento](/pt/docs/api-reference/versioning/).

## Autenticação

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

```bash
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](/pt/docs/developers/api-keys/).
- Os tokens de acesso OAuth emitidos para [apps OAuth](/pt/docs/developers/oauth-apps/) 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](/pt/docs/api-reference/authentication/).

## 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.

| Objeto | Prefixo | Exemplo |
| --- | --- | --- |
| E-mail | `em_` | `em_4K6oASS7KP9ztzWmSN9ndEu13HW` |
| Domínio de envio | `dom_` | `dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6` |
| Chave de API | `key_` | `key_4F2kN8sQwE1rT6yU3iO9pA7sD5f` |
| Lista de contatos | `aud_` | `aud_3zR8tY2uI6oP4aS1dF9gH7jK5lM` |
| Inscrito | `sub_` | `sub_4K6oASS7KP9ztzWnqS4svxApJzO` |
| Contato | `con_` | `con_4A9sD2fG6hJ1kL8zX3cV7bN5mQw` |
| Template | `tem_` | `tem_3wE8rT1yU5iO9pA2sD6fG4hJ7kL` |
| Supressão | `sup_` | `sup_4K6oASS7KP9ztzWol5ElicOeKFE` |
| Webhook | `wh_` | `wh_3mN7bV2cX6zL9kJ4hG1fD8sA5pO` |
| Requisição de webhook | `whr_` | `whr_4K6oASS7KP9ztzWpVUIec9Jneax` |
| Evento | `evt_` | `evt_4K6oASS7KP9ztzWpqId2iIptac5` |
| Campanha | `cmp_` | `cmp_4B1nM5qW9eR3tY7uI2oP6aS8dF4` |
| Formulário | `frm_` | `frm_4C3vB7nM1qW5eR9tY2uI6oP8aS4` |
| Resposta de formulário | `fsub_` | `fsub_4K6oASS7KP9ztzWqvxLV3IsFRs8` |
| Automação | `aut_` | `aut_4D5fG9hJ3kL7zX1cV6bN2mQ8wE4` |
| Execução de automação | `aur_` | `aur_4K6oASS7KP9ztzWrWOjGgqompRo` |
| Verificação de e-mail | `ev_` | `ev_4E7gH1jK5lZ9xC3vB8nM2qW6eR4` |
| Lista de verificação | `evl_` | `evl_4F9hJ3kL7zX1cV5bN9mQ2wE6rT8` |
| Relatório DMARC | `dmr_` | `dmr_4K6oASS7KP9ztzWsW7e5qkOYHO6` |

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](/pt/docs/api-reference/errors/).
- **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](/pt/docs/api-reference/pagination/).
- **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](/pt/docs/api-reference/filtering/).
- **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](/pt/docs/api-reference/idempotency/).
- **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](/pt/docs/api-reference/rate-limits/) e [Limites](/pt/docs/limits/).

## 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](https://github.com/emailit). Consulte [SDKs e bibliotecas](/pt/docs/sdks/) para os comandos de instalação e os guias de frameworks para exemplos completos, começando por [Node.js](/pt/docs/frameworks/nodejs/).

## 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](/pt/docs/webhooks/set-up/) e [Assinatura das requisições](/pt/docs/webhooks/request-signature/).

## Servidor MCP e ferramentas de IA

O [servidor MCP](/pt/docs/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](/pt/docs/mcp/plugins-and-skills/) 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](/pt/docs/developers/llms-txt/) indexa todas elas.

## Próximos passos

  - [Criar uma chave de API](/pt/docs/developers/api-keys/): Escolha um escopo, restrinja a chave a um domínio e guarde-a com segurança.
  - [Enviar o primeiro e-mail](/pt/docs/quickstart/api/): Faça a sua primeira chamada à API em poucos minutos.
  - [SDKs e bibliotecas](/pt/docs/sdks/): Bibliotecas oficiais para nove linguagens e frameworks.
  - [Referência da API](/pt/docs/api-reference/): Todos os endpoints, parâmetros e respostas.

---
Fonte: https://emailit.com/pt/docs/developers/