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

# Email Messaging with Zexa: Domain Setup and Delivery

> Send transactional and marketing emails through Zexa. Configure your sender domain, compose messages, and monitor open and delivery rates.

Zexa handles email delivery so you can focus on crafting the right message. Send transactional notifications — such as order confirmations and password resets — or marketing campaigns to your contact list, and track every send, open, bounce, and spam report from a single dashboard.

## Before you start

Good email deliverability depends on proper domain configuration. Complete these steps before sending your first email:

<Steps>
  <Step title="Verify your sender domain">
    In the Zexa dashboard, go to **Channels > Email** and add the domain you'll be sending from (e.g., `yourdomain.com`). Zexa will generate the DNS records you need to add.
  </Step>

  <Step title="Add DNS records to your domain">
    Add the following DNS records at your domain registrar or DNS provider to authenticate your emails:

    * **SPF** — authorises Zexa's mail servers to send on behalf of your domain.
    * **DKIM** — adds a cryptographic signature to outbound messages, proving they haven't been tampered with.

    Once the records are saved, click **Verify** in the Zexa dashboard. Propagation can take up to 48 hours, though it usually completes within a few minutes.
  </Step>
</Steps>

<Tip>
  Adding both SPF and DKIM records significantly improves inbox placement rates and reduces the chance of your emails being flagged as spam.
</Tip>

## Send an email via API

Send a `POST` request to `/messages` with `"channel": "email"` to dispatch an email message.

<CodeGroup>
  ```bash curl theme={null}
  curl --request POST \
    --url https://api.zexa.ao/v1/messages \
    --header 'Authorization: Bearer <api_key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "channel": "email",
      "to": "customer@example.com",
      "from": "noreply@yourdomain.com",
      "subject": "Order Confirmation #1234",
      "body": "Thank you for your order!",
      "html": "<p>Thank you for your order!</p>"
    }'
  ```

  ```python python theme={null}
  import requests

  url = "https://api.zexa.ao/v1/messages"

  payload = {
      "channel": "email",
      "to": "customer@example.com",
      "from": "noreply@yourdomain.com",
      "subject": "Order Confirmation #1234",
      "body": "Thank you for your order!",
      "html": "<p>Thank you for your order!</p>"
  }

  headers = {
      "Authorization": "Bearer <api_key>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```
</CodeGroup>

A successful request returns a `201` response with the message object:

```json theme={null}
{
  "id": "msg_em2291",
  "status": "queued",
  "channel": "email",
  "to": "customer@example.com",
  "created_at": "2026-06-24T10:15:00Z"
}
```

## HTML vs plain text

The email request body accepts two content fields — always provide both:

* **`body`** — the plain text version of your email. This is displayed by email clients that cannot render HTML, and is also used by spam filters when evaluating your message.
* **`html`** — the full HTML version of your email. Most modern email clients render this version.

Sending both fields ensures every recipient receives a readable message regardless of their email client. If you only send HTML and a client strips it, recipients will see an empty message.

## Delivery tracking

Zexa records engagement and deliverability events for every email you send. View these stats per message or aggregated across a campaign in the **Reports** section of your dashboard.

| Status      | Description                                                            |
| ----------- | ---------------------------------------------------------------------- |
| `queued`    | The email has been accepted and is waiting to be dispatched.           |
| `sent`      | The email has been handed off to the receiving mail server.            |
| `delivered` | The receiving mail server confirmed successful delivery to the inbox.  |
| `opened`    | The recipient opened the email (requires tracking pixel support).      |
| `bounced`   | The email could not be delivered — the address may be invalid or full. |
| `spam`      | The recipient marked the email as spam or junk.                        |

<Warning>
  Sending emails to addresses without explicit consent may result in high spam rates and account suspension. Always obtain permission before adding contacts to your list.
</Warning>

<Tip>
  Include a clear and functional unsubscribe link in all marketing emails. This is required by anti-spam laws in many jurisdictions and by Zexa's Terms of Use.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Email Campaigns" icon="envelope-open-text" href="/messaging/campaigns">
    Send bulk marketing emails to segmented contact lists with scheduling and reporting.
  </Card>

  <Card title="Contact Lists" icon="address-book" href="/messaging/contacts">
    Manage your subscriber lists and segment contacts for targeted email campaigns.
  </Card>
</CardGroup>