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

> First email send: verify domain, send, query, and cancel scheduled messages.

<Tip>
  From **zero to your first email in the queue** in a few steps. The must-have is a **verified domain** in DNS, without it, send will not work.
</Tip>

## In short

* **Verify a domain** in DNS, proves you control the sender (`noreply@yourdomain.com`).
* **Send** with subject and body (text and/or HTML) to up to **100** recipients per call.
* **Query, schedule, or cancel** and get status via [webhooks](/en/emails-api/como-funciona/eventos-do-webhooks).

Context: [Introduction](/en/emails-api/como-funciona/introducao). Scopes: [API Key scopes](/en/emails-api/como-funciona/escopos-da-api-key).

## Before you start

* Key with **`email:domains:create`**, **`email:domains:list`**, and **`email:send`** (or admin scope in testing)
* The **`from`** domain must be **VERIFIED** before send
* Auth: `Authorization: Bearer sk_live_...` or `x-api-key`
* Base URL: `https://api.notifique.dev`, use `sk_test_...` in [Sandbox](/en/guides/sandbox/index) when getting started

***

## 1. Verify domain

Two paths, pick what fits your integration:

#### 1A, Via dashboard

1. Settings → Email → **Add domain**
2. Copy the **DNS** records (TXT/CNAME) to your domain provider
3. Click **Verify** until status is **VERIFIED**

#### 1B, Via API

**Register domain**

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

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

Expected response: **200** with **PENDING** status and DNS records:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "clxx123...",
    "domain": "yourdomain.com",
    "status": "PENDING",
    "dnsRecords": [
      {
        "type": "TXT",
        "name": "notifique._domainkey.yourdomain.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."
}
```

Save the domain **`id`** for the verify step.

**Verify** (call again after DNS propagates):

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

DNS still pending, **200**, not an HTTP error:

```json theme={null}
{
  "success": true,
  "verified": false,
  "code": "EMAIL_DOMAIN_DNS_PENDING",
  "message": "DNS records are not verified yet. Check your DNS provider and try again in a few minutes.",
  "data": { "id": "clxx...", "domain": "yourdomain.com", "status": "PENDING" }
}
```

Verified, **200**:

```json theme={null}
{
  "success": true,
  "verified": true,
  "code": "EMAIL_DOMAIN_VERIFIED",
  "message": "Domain verified successfully.",
  "data": { "id": "clxx...", "domain": "yourdomain.com", "status": "VERIFIED" }
}
```

Codes and HTTP errors: [Error responses](/en/guides/conceitos/resposta-de-erros#email-verify-domain-post-v1emaildomainsidverify).

***

## 2. Send email

With a **VERIFIED** domain, send to one or many recipients. `to` is always an **array** (up to **100**).

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

```json theme={null}
{
  "from": "noreply@yourdomain.com",
  "fromName": "Support",
  "to": ["customer@example.com"],
  "type": "email",
  "payload": {
    "subject": "Order confirmation",
    "html": "<p>Hello, your order is confirmed.</p>",
    "text": "Hello, your order is confirmed."
  }
}
```

Required in `payload`: **subject** and at least **text** or **html**.

### Send with template

If you already have a [workspace template](/en/template-api/como-funciona/variaveis-disponiveis-e-crud) with email enabled:

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

Expected response: **202**

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

`messageIds` is the canonical field; `emailIds` is a compatibility alias.

<Note>
  Unverified **from** domain → **400** with `DOMAIN_NOT_VERIFIED`.
</Note>

**Options in `options`:** `priority` (`high`, `normal`, `low`), `webhook` (URL and secret for this batch only), `metadata` (free text). Details in the API reference.

**RFC 8058 (one-click unsubscribe):** by default, if the recipient is a workspace contact, Notifique injects `List-Unsubscribe`. For transactional email use `"listUnsubscribe": false`. Invalid topic → **400** `INVALID_LIST_UNSUBSCRIBE_TOPIC`. Guide: [One-click unsubscribe](/en/emails-api/como-funciona/one-click-unsubscribe-rfc-8058).

***

## 3. Query, schedule, and cancel

**List sent**

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

Optional filters: `fromDate`, `toDate`, `status`, `emailDomainId`. Requires **`email:read`**.

**View one send**

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

**Schedule**, include in the send body:

```json theme={null}
{
  "from": "noreply@yourdomain.com",
  "to": ["customer@example.com"],
  "type": "email",
  "payload": {
    "subject": "Reminder",
    "html": "<p>Content.</p>"
  },
  "schedule": {
    "sendAt": "2025-12-31T14:00:00.000Z"
  }
}
```

**Cancel schedule** (only with **SCHEDULED** status):

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

Scope: **`email:cancel`**. Scheduled credits return to the workspace.

***

## 4. Avoid duplicates

**`Idempotency-Key`** header on `POST`. Repeats within 24 h do not create duplicate sends. See [Security and reliability](/en/guides/conceitos/seguranca-e-confiabilidade).

***

## 5. Webhooks (optional)

Configure `email.sent`, `email.delivered`, `email.opened`, `email.clicked`, `email.failed`, `email.complained`, and `email.cancelled` to track without polling.

Guide: [Webhook events](/en/emails-api/como-funciona/eventos-do-webhooks).

***

## All send types

In the API reference (Email tab), open **Send email** and pick an example in the playground: HTML+text, Text only, Template, Scheduled, List-Unsubscribe.

## Next steps

* [Introduction](/en/emails-api/como-funciona/introducao): when to use and status lifecycle
* [Scopes](/en/emails-api/como-funciona/escopos-da-api-key): key permissions
* [Webhook events](/en/emails-api/como-funciona/eventos-do-webhooks): real-time status
* [Error responses](/en/guides/conceitos/resposta-de-erros): HTTP codes and `code`