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

# Custom Domains

> Send emails from your customers' own domains

## Overview

Custom domains let your customers send emails from their own domain (e.g.
`promotions@joes-pizza.com`) instead of a shared Pocketflows domain. There are
two ways to set them up:

* **Embed-first** — Your customer configures their domain directly through the
  Pocketflows embed UI. No API work required.
* **API-first** — You manage domain setup programmatically through the API.

***

## Embed-first

If you're using [Pocketflows embeds](/embeds/overview), custom domain setup is
already built into the UI. Your customers can add and verify their domain
directly from the embedded experience—no additional integration work needed on
your end.

***

## API-first

Use this approach if you want to manage custom domains programmatically—for
example, to automate domain setup during onboarding or build your own domain
configuration UI.

### Step 1: Create a custom domain

Register the domain you want to send emails from.

```shell theme={null}
POST /businesses/{business_id}/custom_domains

{
  "domain": "joes-pizza.com"
}

# Response
{
  "id": "cd_XXXXXXXXXXXXX",
  "domain": "joes-pizza.com",
  "dns_records": [...],
  "validated": false
}
```

Save the `id` for the following steps.

***

### Step 2: Retrieve DNS records

Poll the custom domain until the required DNS records are available.

```shell theme={null}
GET /custom_domains/{custom_domain_id}

# Response
{
  "id": "cd_XXXXXXXXXXXXX",
  "domain": "joes-pizza.com",
  "dns_records": [
    {
      "type": "CNAME",
      "name": "...",
      "value": "..."
    }
  ],
  "validated": false
}
```

The `dns_records` array contains the records that need to be added to the
domain's DNS provider. Share these with your customer or configure them
programmatically if you manage their DNS.

<Note>
  DNS records may take a moment to be generated after creating the custom
  domain. Poll this endpoint until `dns_records` is populated in the response.
</Note>

***

### Step 3: Validate the domain

Once the DNS records have been installed, call validate to verify everything is
configured correctly.

```shell theme={null}
POST /custom_domains/{custom_domain_id}/validate

# Response
{
  "id": "cd_XXXXXXXXXXXXX",
  "domain": "joes-pizza.com",
  "validated": true
}
```

Pocketflows will check that the required DNS records are in place. Once
validation succeeds, the domain is ready to use for sending emails.

<Note>
  DNS changes can take up to 48 hours to propagate. If validation fails, wait
  and try again later.
</Note>

***

### Step 4: Create email addresses

With the domain validated, create email addresses on it for the business.

```shell theme={null}
POST /businesses/{business_id}/email_addresses

{
  "username": "order",
  "display_name": "Joe's Pizza",
  "custom_domain": "cd_XXXXXXXXXXXXX"
}

# Response
{
  "id": "ea_XXXXXXXXXXXXX",
  "email_address": "order@joes-pizza.com",
  "display_name": "Joe's Pizza",
  "custom_domain": "cd_XXXXXXXXXXXXX"
}
```

<Warning>
  You can create email addresses on a custom domain before it's validated, but
  they **cannot be used in triggers or campaigns** until the domain passes
  validation.
</Warning>