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

# Receiving emails

> Receive email on your verified domain, configure MX, email.received webhooks, and the dashboard inbox.

<Tip>
  Inbound email is the **return path**: someone replies to `support@yourdomain.com` and Notifique delivers the content to your webhook and/or the dashboard **Received** tab.
</Tip>

## What’s new

Besides **sending** from a verified domain, you can **receive** messages sent to `@yourdomain.com` (or a registered subdomain). The flow uses MX in your DNS zone, inbound processing on the platform, and the **`email.received`** webhook event.

## Prerequisites

1. **Domain registered and VERIFIED** for sending (provedor de e-mail da plataforma per platform setup).
2. **MX record** on the domain (or subdomain) pointing to Notifique’s inbound host — see `inboundDnsRecords` in the API or dashboard when adding the domain.
3. **Email channel** enabled under **Settings → Received messages**.
4. **Webhook** subscribed to **`email.received`** (for backend automation).

<Note>
  By default, when you enable inbound email, the platform **sends webhooks** and **does not persist** messages in the dashboard (avoids inbound storage charges). Turn on **Persist** in channel settings to see emails under **Emails → Received**.
</Note>

## Query via API

When **Persist** is on, list received emails with scope `email:inbound:read`:

```bash theme={null}
curl "https://api.notifique.dev/v1/email/inbound?page=1&limit=20" \
  -H "Authorization: Bearer sk_live_..."

curl "https://api.notifique.dev/v1/email/inbound/INBOUND_ID" \
  -H "Authorization: Bearer sk_live_..."
```

Filters: `q`, `domainId`, `dateFrom`, `dateTo`. See **Received emails** in the Email tab.

With **`domainIds`** on the key, listing only includes emails from allowed domains. Invalid `domainId` → **400**; domain not on key → **403**; detail for forbidden domain → **404**.

## DNS for inbound

On **create**, **list**, **get**, or **verify** domain responses, `data` includes:

| Field                 | Description                                                |
| --------------------- | ---------------------------------------------------------- |
| `dnsRecords`          | Provider records (DKIM, bounce, tracking, etc.)            |
| `suggestedDnsRecords` | Recommended SPF and DMARC                                  |
| `inboundDnsRecords`   | MX to **receive** mail (e.g. `10 inbound.notifique.dev`)   |
| `dkim`                | Shortcut `{ name, value }` for primary DKIM when available |
| `verification`        | Per-provider and per-record DNS status                     |

Inbound MX example:

```json theme={null}
{
  "type": "MX",
  "name": "yourdomain.com",
  "value": "10 inbound.notifique.dev"
}
```

The MX host must resolve to a valid **A** record (do not use CNAME on the MX target — providers such as Gmail reject it).

After publishing MX, call **`POST /v1/email/domains/:id/verify`** until `verification.records` shows the MX as `verified` when applicable.

## Dashboard setup

1. **Settings → Channels → Email** (or **Received messages**): enable **Email**.
2. Default actions:
   * **Send webhook** — fires `email.received` (default when enabling).
   * **Persist** — stores in the dashboard (**Received** tab); may charge inbound storage per plan.
3. **Developer → Webhooks**: add or edit a webhook and select **`email.received`** under **Email**.
4. Optional: restrict by **email domain** on the webhook.

## `email.received` event

Fires when an inbound email is accepted and processed per workspace actions (webhook, persist, or both).

```json theme={null}
{
  "event": "email.received",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2026-08-12T11:30:00.000Z",
  "data": {
    "inboundEmailId": "clinbound1...",
    "persisted": true,
    "from": "customer@example.com",
    "to": "support@yourdomain.com",
    "subject": "Question about order #123",
    "matchedRuleIds": [],
    "persistDeniedReason": null
  }
}
```

| `data` field          | Description                                                   |
| --------------------- | ------------------------------------------------------------- |
| `inboundEmailId`      | Dashboard inbound id; **`null`** if webhook-only (no persist) |
| `persisted`           | `true` if the message was stored                              |
| `from` / `to`         | Sender and recipient on your domain                           |
| `subject`             | Subject or `null`                                             |
| `matchedRuleIds`      | Inbound rules that matched (if any)                           |
| `persistDeniedReason` | Persist failure reason (e.g. balance), when applicable        |

Full payloads and outbound events: [Webhook events](/en/emails-api/como-funciona/eventos-do-webhooks).

## Dashboard inbox

With **Persist** enabled:

* **Emails → Received** lists inbound messages.
* Detail view shows HTML/text preview, metadata, MIME **Message-ID**, threading (`In-Reply-To`, `References`), and timeline.
* **Reply** opens the composer with recipient, `Re:` subject, and thread headers.

Public API: `GET /v1/email/inbound` and `GET /v1/email/inbound/:id` with scope **`email:inbound:read`**. The dashboard uses the session API (`/app/email/inbound`) with the same behavior.

## Reply with threading

On send (`POST /v1/email/messages`), use **`headers`** with allowed MIME headers:

* `In-Reply-To`, `References`, `Message-ID`, `X-Entity-Ref-ID`

```json theme={null}
{
  "from": "support@yourdomain.com",
  "to": ["customer@example.com"],
  "type": "email",
  "payload": {
    "subject": "Re: Question about order #123",
    "html": "<p>Thanks for reaching out. Your order has shipped.</p>"
  },
  "headers": {
    "In-Reply-To": "<abc@mail.example.com>",
    "References": "<abc@mail.example.com>"
  }
}
```

## Domain verification (send + inbound)

**`POST /v1/email/domains/:id/verify`** returns `verified`, `code`, plus:

* **`verificationSummary`** — human-readable per-provider status.
* **`data.verification`** — structured `providers`, `records`, and per-record status.

Codes `EMAIL_DOMAIN_DNS_PENDING`, `EMAIL_DOMAIN_VERIFIED`, and `EMAIL_DOMAIN_VERIFY_FAILED` still use HTTP **200**. See [Error responses](/en/guides/conceitos/resposta-de-erros#email-verify-domain-post-v1emaildomainsidverify).

## Next steps

* [Quick Start](/en/emails-api/como-funciona/quick-start)
* [Webhook events](/en/emails-api/como-funciona/eventos-do-webhooks)
* [API Key scopes](/en/emails-api/como-funciona/escopos-da-api-key)
* [Webhooks guide](/en/guides/webhooks/index)