Skip to main content

​
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, 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. 
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. 
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.
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.

​
Step 3: Validate the domain

Once the DNS records have been installed, call validate to verify everything is configured correctly. 
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.
DNS changes can take up to 48 hours to propagate. If validation fails, wait and try again later.

​
Step 4: Create email addresses

With the domain validated, create email addresses on it for the business. 
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"
}
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.