# Enviar um e-mail

> Envie e-mails com POST /emails, com as regras do remetente, os destinatários, o conteúdo, os templates, o rastreamento, a resposta, os eventos de webhook e todos os códigos de erro.

Este guia explica cada parte de uma requisição `POST /emails` e o que o Emailit faz com ela, do endereço From aos erros que você pode receber. Para a referência completa dos parâmetros, consulte [Enviar um e-mail](/pt/docs/api-reference/emails/send/) na referência da API.

## Antes de começar

- Um domínio de envio verificado no seu workspace. Consulte [Adicionar um domínio](/pt/docs/domains/add-a-domain/).
- Uma chave de API com escopo **Full Access** ou **Sending Only**. Consulte [Chaves de API](/pt/docs/developers/api-keys/).
- Acesso de produção, se você enviar para alguém que não seja membro do workspace. Consulte [Acesso de produção](/pt/docs/workspaces/production-access/).
- Créditos suficientes para todos os destinatários (1 crédito cada).

## Enviar um e-mail básico

**cURL**

```bash
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready."
  }'
```

**Node.js**

```javascript
import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);

const email = await emailit.emails.send({
  from: 'Acme Billing <billing@acme.com>',
  to: ['ada@example.com', 'Grace Hopper <grace@example.com>'],
  cc: 'accounts@example.com',
  reply_to: 'support@acme.com',
  subject: 'Your invoice for October',
  html: '<p>Your invoice is ready.</p>',
  text: 'Your invoice is ready.',
});
```

**Python**

```python
import os
from emailit import EmailitClient

client = EmailitClient(os.environ["EMAILIT_API_KEY"])

email = client.emails.send({
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready.",
})
```

**PHP**

```php
$emailit = Emailit::client(getenv('EMAILIT_API_KEY'));

$email = $emailit->emails()->send([
    'from' => 'Acme Billing <billing@acme.com>',
    'to' => ['ada@example.com', 'Grace Hopper <grace@example.com>'],
    'cc' => 'accounts@example.com',
    'reply_to' => 'support@acme.com',
    'subject' => 'Your invoice for October',
    'html' => '<p>Your invoice is ready.</p>',
    'text' => 'Your invoice is ready.',
]);
```

## Definir o endereço From

`from` é obrigatório e aceita um endereço em qualquer uma destas formas:

- `billing@acme.com`
- `Acme Billing <billing@acme.com>` ou, com aspas, `"Acme, Inc." <billing@acme.com>`

O domínio depois do `@` deve ser um domínio de envio verificado no mesmo workspace:

- **A correspondência é exata.** Os domínios são comparados sem diferenciar maiúsculas de minúsculas, mas `mail.acme.com` e `acme.com` são domínios diferentes. Adicione e verifique cada subdomínio de onde você envia.
- **Qualquer parte local funciona.** Você não precisa de uma caixa de e-mail para `billing@` ou `no-reply@`.
- **Domínios pendentes não podem enviar.** Um domínio que ainda aguarda análise (**Pending verification**) é tratado como não verificado.
- **Chaves restritas só usam o domínio delas.** Uma chave **Sending Only** restrita a um domínio só pode enviar desse domínio.
- **Domínios pausados são bloqueados.** Se a [saúde de envio](/pt/docs/deliverability/sending-health/) pausou o domínio, os envios a partir dele são rejeitados até a pausa ser retirada.

## Adicionar destinatários

`to` é obrigatório. `cc` e `bcc` são opcionais. Cada campo aceita uma string ou um array de strings, com ou sem nomes de exibição, e comporta até 50 endereços. Uma string pode conter vários endereços separados por vírgula; use um array quando o próprio nome de exibição tiver uma vírgula.

O Emailit remove os endereços duplicados entre `to`, `cc` e `bcc` (sem diferenciar maiúsculas de minúsculas) e depois cria **um e-mail por destinatário único**, cada um com o seu próprio ID `em_`. Todas as cópias levam os mesmos cabeçalhos `To` e `Cc`, então os destinatários veem a conversa normalmente, e os destinatários em `Bcc` nunca aparecem nos cabeçalhos de nenhuma cópia.

Quando uma requisição tem mais de um destinatário, a resposta inclui um mapa `ids` de destinatário para ID de e-mail. `id` é o e-mail do primeiro destinatário.

```json
{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "ids": {
    "ada@example.com": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
    "grace@example.com": "em_33VtK8nB5rTq0YxW3mJk9PdLsUe",
    "accounts@example.com": "em_33VtK8nQ2wErT6yU8iOp4AsDf7g"
  }
}
```

Cada destinatário custa 1 crédito e conta para os seus [limites de requisições](/pt/docs/api-reference/rate-limits/). Um destinatário com uma [supressão](/pt/docs/suppressions/) do tipo `recipient` é aceito e depois marcado como `suppressed`, em vez de ser entregue.

## Escrever o conteúdo

| Campo | Regras |
| --- | --- |
| `subject` | Obrigatório, a menos que um template o forneça. Caracteres não ASCII são codificados automaticamente. |
| `html` | O corpo HTML. Você precisa de `html`, de `text` ou dos dois, a menos que um template os forneça. |
| `text` | O corpo em texto simples. Envie-o junto com `html`: alguns clientes de e-mail e filtros de spam preferem mensagens com os dois. |
| `reply_to` | Uma string ou um array de endereços para onde as respostas devem ir. |

Se `reply_to` tiver o mesmo endereço que `from`, o Emailit remove o cabeçalho `Reply-To`, porque ele não acrescenta nada e alguns filtros de spam o penalizam.

## Enviar com um template

Defina `template` como o alias de um template ou um ID `tem_` e passe em `variables` os valores para as variáveis do [Temple](/pt/docs/templates/temple/) que ele contém.

- **Um alias** envia a versão publicada no momento para esse alias. Se nenhuma versão estiver publicada, a requisição falha com `404`.
- **Um ID `tem_`** envia exatamente essa versão, publicada ou não. Use-o para testar uma versão em rascunho antes de publicá-la.

Os campos da requisição têm precedência sobre o template: um `subject`, `html` ou `text` que você enviar substitui o valor do template. Se você não enviar `reply_to`, o Reply-To do template é usado. `from` é sempre obrigatório na requisição. Consulte [Versões de templates](/pt/docs/templates/versions/) para saber como a publicação funciona.

**cURL**

```bash
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",
    "template": "welcome-email",
    "variables": {
      "first_name": "Ada",
      "plan": "Pro",
      "activation_url": "https://acme.com/activate?token=8f3k2"
    }
  }'
```

**Node.js**

```javascript
const email = await emailit.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'ada@example.com',
  template: 'welcome-email',
  variables: {
    first_name: 'Ada',
    plan: 'Pro',
    activation_url: 'https://acme.com/activate?token=8f3k2',
  },
});
```

**Python**

```python
email = client.emails.send({
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "template": "welcome-email",
    "variables": {
        "first_name": "Ada",
        "plan": "Pro",
        "activation_url": "https://acme.com/activate?token=8f3k2",
    },
})
```

**PHP**

```php
$email = $emailit->emails()->send([
    'from' => 'Acme <hello@acme.com>',
    'to' => 'ada@example.com',
    'template' => 'welcome-email',
    'variables' => [
        'first_name' => 'Ada',
        'plan' => 'Pro',
        'activation_url' => 'https://acme.com/activate?token=8f3k2',
    ],
]);
```

`variables` também funciona sem template: o Emailit renderiza as variáveis do Temple no `subject`, no `html` e no `text` que você envia diretamente na requisição.

## Controlar o rastreamento

Por padrão, cada e-mail segue as configurações **Track loads** e **Track clicks** do seu domínio de envio. Para substituí-las em um e-mail, use `tracking`:

- `"tracking": true` ou `false` ativa ou desativa o rastreamento de carregamentos (aberturas) e de cliques.
- `"tracking": { "loads": true, "clicks": false }` define cada um separadamente.

O rastreamento só funciona quando o CNAME de rastreamento do domínio está verificado. Sem ele, o e-mail é enviado sem rastreamento e a requisição é bem-sucedida mesmo assim. O objeto `tracking` da resposta mostra as configurações que foram de fato aplicadas. Consulte [Rastreamento de aberturas e cliques](/pt/docs/tracking/).

## Adicionar cabeçalhos e metadados

Use `headers` para cabeçalhos de e-mail personalizados, como `List-Unsubscribe`, e `meta` para os seus próprios pares chave-valor de strings. O Emailit armazena `meta` com o e-mail e o inclui nos eventos de webhook. Consulte [Cabeçalhos e metadados](/pt/docs/email-api/headers-and-metadata/).

Para anexar arquivos, agendar o envio ou tornar as novas tentativas seguras, consulte [Anexos](/pt/docs/email-api/attachments/), [Agendamento](/pt/docs/email-api/scheduling/) e [Idempotência](/pt/docs/email-api/idempotency/).

## Ler a resposta

Uma requisição bem-sucedida retorna `200`:

| Campo | Descrição |
| --- | --- |
| `object` | Sempre `email`. |
| `id` | O ID `em_` do e-mail do primeiro destinatário. |
| `ids` | Mapa de endereço do destinatário para ID de e-mail. Presente apenas quando há mais de um destinatário. |
| `token` | Token interno do primeiro e-mail, também usado no Message-ID dele. |
| `message_id` | O cabeçalho `Message-ID` do primeiro e-mail, no formato `<token@your-domain>`. |
| `from` | O endereço From como você o enviou. |
| `to` | Os endereços de `to`, sem os nomes de exibição. |
| `cc`, `bcc` | Os endereços de `cc` e `bcc`. Presentes apenas quando você os enviou. |
| `subject` | O assunto final, depois da renderização do template. |
| `status` | `accepted`, ou `scheduled` quando o e-mail tem um horário de envio no futuro. |
| `scheduled_at` | O horário de envio em ISO 8601, ou `null`. |
| `created_at` | Quando o e-mail foi criado. |
| `tracking` | As configurações `loads` e `clicks` aplicadas. |

Guarde o `id` (ou o mapa `ids`) para associar os eventos de webhook que chegarem depois e consultar o e-mail com [Obter um e-mail](/pt/docs/api-reference/emails/get/).

## Eventos

O e-mail de cada destinatário emite os próprios eventos:

1. [`email.accepted`](/pt/docs/webhooks/events/email/accepted/) logo após a requisição, ou [`email.scheduled`](/pt/docs/webhooks/events/email/scheduled/) se ele tiver um horário de envio no futuro.
2. Eventos de entrega à medida que o e-mail avança no processamento: [`email.delivered`](/pt/docs/webhooks/events/email/delivered/), [`email.attempted`](/pt/docs/webhooks/events/email/attempted/) (falha temporária, haverá nova tentativa), [`email.bounced`](/pt/docs/webhooks/events/email/bounced/), [`email.failed`](/pt/docs/webhooks/events/email/failed/), [`email.rejected`](/pt/docs/webhooks/events/email/rejected/) ou [`email.suppressed`](/pt/docs/webhooks/events/email/suppressed/). Um e-mail retido para análise emite `email.held`.
3. Eventos de engajamento, se o rastreamento estiver ativado: [`email.loaded`](/pt/docs/webhooks/events/email/loaded/) e [`email.clicked`](/pt/docs/webhooks/events/email/clicked/). As denúncias de spam emitem [`email.complained`](/pt/docs/webhooks/events/email/complained/).

Consulte [Status de e-mail](/pt/docs/logs/email-statuses/) para saber o que cada status significa.

## Erros

Os erros de validação retornam uma lista com todos os problemas encontrados:

```json
{
  "error": "Validation failed",
  "validation_errors": [
    "Missing required field: subject",
    "Invalid to email address at index 1: grace@"
  ]
}
```

| Status | `error` | Causa | Solução |
| --- | --- | --- | --- |
| `400` | `Validation failed` | Falta um campo obrigatório, um endereço está malformado, um campo tem mais de 50 destinatários ou um anexo é inválido. | Corrija cada item de `validation_errors`. |
| `400` | `Invalid Idempotency-Key` | O cabeçalho `Idempotency-Key` tem um formato inválido. | Use de 1 a 256 letras, dígitos, `-` ou `_`. Consulte [Idempotência](/pt/docs/email-api/idempotency/). |
| `401` | `Unauthorized` | A chave de API está ausente ou é inválida. | Envie `Authorization: Bearer` com uma chave válida. |
| `402` | `Insufficient credits` | O workspace não consegue pagar por todos os destinatários. | [Compre créditos](/pt/docs/billing/credits/) ou ative a [recarga automática](/pt/docs/billing/auto-refill/). |
| `403` | `Workspace not verified` | O workspace está no modo sandbox e um destinatário não é membro do workspace. `code` é `unverified_workspace_recipient` e `blocked_recipients` lista os endereços. | [Solicite acesso de produção](/pt/docs/workspaces/production-access/) ou teste com os endereços dos membros. |
| `403` | `Domain not authorized` | A chave de API está restrita a outro domínio de envio. | Envie a partir do domínio da chave ou use uma chave sem restrição de domínio. |
| `403` | `Domain paused` | A saúde de envio pausou o domínio do From. | Consulte [Saúde de envio](/pt/docs/deliverability/sending-health/). |
| `404` | `Template not found` | O alias não tem versão publicada, ou o ID `tem_` não existe neste workspace. | Publique uma versão ou confira o ID. |
| `409` | `Idempotency key in progress` | Outra requisição com a mesma chave ainda está em andamento. | Espere e tente de novo com a mesma chave. |
| `413` | `Message too large` | A mensagem codificada tem mais de 40 MB. | Envie menos anexos ou anexos menores, ou use links para os arquivos grandes. |
| `422` | `Domain not verified` | O domínio do From não é um domínio de envio verificado neste workspace. | Verifique o domínio ou confira se é um subdomínio ou se há um erro de digitação. |
| `422` | `Attachment error` | Não foi possível baixar a URL de um anexo, ou o arquivo tem mais de 25 MB. | Consulte [Anexos](/pt/docs/email-api/attachments/). |
| `429` | `Rate limit exceeded` ou `Daily limit exceeded` | Você ultrapassou o limite de envio por segundo ou o diário. | Espere `retry-after` segundos ou solicite um limite maior. |
| `503` | `Idempotency unavailable` | Não foi possível acessar o armazenamento de idempotência. | Tente de novo com a mesma chave. |

Um workspace suspenso recebe `403` com `Workspace is suspended` em todos os envios. Para o formato geral dos erros, consulte [Erros](/pt/docs/api-reference/errors/).

## Veja também

- [Enviar um e-mail](/pt/docs/api-reference/emails/send/) na referência da API
- [Templates](/pt/docs/templates/)
- [Status de e-mail](/pt/docs/logs/email-statuses/)
- [Tipos de eventos de webhook](/pt/docs/webhooks/event-types/)
- [Por que o meu e-mail não chegou?](/pt/docs/kb/email-not-delivered-checklist/)

---
Fonte: https://emailit.com/pt/docs/email-api/send-email/