> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Primeiro envio de e-mail: verificar domínio, enviar, consultar e cancelar agendamento.

<Tip>
  Do **zero ao primeiro e-mail na fila** em poucos passos. O indispensável é o **domínio verificado** no DNS, sem isso o envio não sai.
</Tip>

## Em poucas palavras

* **Verifique um domínio** no DNS, prova que você controla o remetente (`noreply@seudominio.com`).
* **Envie** com assunto e corpo (texto e/ou HTML) para até **100** destinatários por chamada.
* **Consulte, agende ou cancele** e receba status por [webhooks](/emails-api/como-funciona/eventos-do-webhooks).

Contexto: [Introdução](/emails-api/como-funciona/introducao). Escopos: [Escopos da API Key](/emails-api/como-funciona/escopos-da-api-key).

## Antes de começar

* Chave com **`email:domains:create`**, **`email:domains:list`** e **`email:send`** (ou escopo admin em teste)
* O domínio do **`from`** precisa estar **VERIFIED** antes do envio
* Autenticação: `Authorization: Bearer sk_live_...` ou `x-api-key`
* Base URL: `https://api.notifique.dev`, use `sk_test_...` no [Sandbox](/guides/sandbox/index) se estiver começando

***

## 1. Verificar domínio

Dois caminhos, escolha o que combina com sua integração:

#### 1A, Pelo painel

1. Settings → E-mail → **Adicionar domínio**
2. Copie os registros **DNS** (TXT/CNAME) para o provedor do domínio
3. Clique em **Verificar** até o status ficar **VERIFIED**

#### 1B, Pela API

**Registrar domínio**

```http theme={null}
POST /v1/email/domains
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "domain": "seudominio.com"
}
```

Resposta esperada: **200** com status **PENDING** e registros DNS:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "clxx123...",
    "domain": "seudominio.com",
    "status": "PENDING",
    "dnsRecords": [
      {
        "type": "TXT",
        "name": "notifique._domainkey.seudominio.com",
        "value": "p=MIGf..."
      }
    ],
    "createdAt": "2025-02-15T10:00:00.000Z"
  },
  "message": "Add the DNS record(s) above to your domain, then call the verify endpoint or use the Verify button in the dashboard."
}
```

Guarde o **`id`** do domínio para o passo de verificação.

**Verificar** (repita após propagar o DNS):

```http theme={null}
POST /v1/email/domains/:id/verify
Authorization: Bearer sk_live_xxxxx
```

DNS ainda pendente, **200**, não é erro HTTP:

```json theme={null}
{
  "success": true,
  "verified": false,
  "code": "EMAIL_DOMAIN_DNS_PENDING",
  "message": "Os registros DNS ainda não foram verificados. Confira no seu provedor DNS e tente novamente em alguns minutos.",
  "data": { "id": "clxx...", "domain": "seudominio.com", "status": "PENDING" }
}
```

Verificado, **200**:

```json theme={null}
{
  "success": true,
  "verified": true,
  "code": "EMAIL_DOMAIN_VERIFIED",
  "message": "Domínio verificado com sucesso.",
  "data": { "id": "clxx...", "domain": "seudominio.com", "status": "VERIFIED" }
}
```

Códigos e erros HTTP: [Respostas de erro](/guides/conceitos/resposta-de-erros#verificar-domínio-de-e-mail-post-v1emaildomainsidverify).

***

## 2. Enviar e-mail

Com domínio **VERIFIED**, envie para um ou vários destinatários. `to` é sempre um **array** (até **100**).

```http theme={null}
POST /v1/email/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "from": "noreply@seudominio.com",
  "fromName": "Suporte",
  "to": ["cliente@example.com"],
  "type": "email",
  "payload": {
    "subject": "Confirmação de pedido",
    "html": "<p>Olá, seu pedido foi confirmado.</p>",
    "text": "Olá, seu pedido foi confirmado."
  }
}
```

Obrigatório em `payload`: **subject** e pelo menos **text** ou **html**.

### Enviar com template

Se você já tem um [template do workspace](/template-api/como-funciona/variaveis-disponiveis-e-crud) com canal e-mail habilitado:

```json theme={null}
{
  "from": "noreply@seudominio.com",
  "to": ["cliente@example.com"],
  "type": "template",
  "payload": {
    "templateId": "ID_DO_TEMPLATE",
    "variables": { "name": "Maria", "orderId": "12345" }
  }
}
```

Resposta esperada: **202**

```json theme={null}
{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 1,
    "messageIds": ["clemail1..."],
    "emailIds": ["clemail1..."]
  }
}
```

`messageIds` é o campo canônico; `emailIds` é alias de compatibilidade.

<Note>
  Domínio do **from** não verificado → **400** com `DOMAIN_NOT_VERIFIED`.
</Note>

**Opções em `options`:** `priority` (`high`, `normal`, `low`), `webhook` (URL e segredo só deste lote), `metadata` (texto livre). Detalhes na referência da API.

**RFC 8058 (one-click unsubscribe):** por padrão, se o destinatário for contato do workspace, a Notifique injeta `List-Unsubscribe`. Em e-mails transacionais use `"listUnsubscribe": false`. Tópico inválido → **400** `INVALID_LIST_UNSUBSCRIBE_TOPIC`. Guia: [One-click unsubscribe](/emails-api/como-funciona/one-click-unsubscribe-rfc-8058).

***

## 3. Consultar, agendar e cancelar

**Listar enviados**

```http theme={null}
GET /v1/email/messages?page=1&limit=20
Authorization: Bearer sk_live_xxxxx
```

Filtros opcionais: `fromDate`, `toDate`, `status`, `emailDomainId`. Requer **`email:read`**.

**Ver um envio**

```http theme={null}
GET /v1/email/messages/:id
Authorization: Bearer sk_live_xxxxx
```

**Agendar**, inclua no body do envio:

```json theme={null}
{
  "from": "noreply@seudominio.com",
  "to": ["cliente@example.com"],
  "type": "email",
  "payload": {
    "subject": "Lembrete",
    "html": "<p>Conteúdo.</p>"
  },
  "schedule": {
    "sendAt": "2025-12-31T14:00:00.000Z"
  }
}
```

**Cancelar agendamento** (só com status **SCHEDULED**):

```http theme={null}
POST /v1/email/messages/:id/cancel
Authorization: Bearer sk_live_xxxxx
```

Escopo: **`email:cancel`**. Créditos do agendamento voltam para o workspace.

***

## 4. Evitar duplicata

Header **`Idempotency-Key`** no `POST`. Repetições em até 24 h não criam dois envios iguais. Veja [Segurança e Confiabilidade](/guides/conceitos/seguranca-e-confiabilidade).

***

## 5. Webhooks (opcional)

Configure `email.sent`, `email.delivered`, `email.opened`, `email.clicked`, `email.failed`, `email.complained` e `email.cancelled` para acompanhar sem polling.

Guia: [Eventos dos webhooks](/emails-api/como-funciona/eventos-do-webhooks).

***

## Todos os tipos de envio

Na referência da API (aba E-mail), abra **Enviar e-mail** (`POST /v1/...`) e escolha o exemplo no playground: HTML+texto, Só texto, Template, Agendado, List-Unsubscribe.

## Próximos passos

* [Introdução](/emails-api/como-funciona/introducao): quando usar e ciclo de status
* [Escopos](/emails-api/como-funciona/escopos-da-api-key): permissões da chave
* [Eventos dos webhooks](/emails-api/como-funciona/eventos-do-webhooks): status em tempo real
* [Respostas de erro](/guides/conceitos/resposta-de-erros): códigos HTTP e `code`