Custom Domains

Custom domains let you replace Unipile domains with domains that match your product or company. You can configure them for:

Hosted Auth: display the account authentication flow on a domain such as auth.example.com
Email tracking: use a domain such as tracking.example.com for tracked links and open-tracking pixels

A custom domain is verified once for the organization, then enabled separately for each application that needs to use it.

💡
A hostname can be verified for either Hosted Auth or email tracking, but not both. Use separate subdomains, such as auth.example.com and tracking.example.com, if you need both features.

Configure a Custom Domain

1. Choose the domain type

In the Unipile Dashboard, select your application, open Custom domains, then choose Hosted Auth domains or Email tracking domains.

2. Create the CNAME record

Create the corresponding CNAME record with your DNS provider:

Use case	Example hostname	CNAME target
Hosted Auth	`auth.example.com`	`auth.unipile.com`
Email tracking	`tracking.example.com`	`track.lnk-fllw.com`

Enter only the hostname in the DNS record and Dashboard, without https:// or a URL path. The exact fields vary by DNS provider, but the Name or Host is your chosen subdomain and the Target or Value is the Unipile hostname shown above.

3. Verify the domain

Click Verify a domain, enter your complete hostname, and start verification. Organization Admins and Owners can verify domains.

DNS changes can take up to 24 hours to propagate. If verification fails immediately after creating the record, wait for propagation and try again.

4. Enable it for an application

After verification, activate the domain for the selected application. A verified domain is available to the organization, but it cannot be used by an application until it is enabled in that application's Custom domains settings.

Repeat this activation in every application that should use the domain.

Use a Hosted Auth Domain

Once the domain is verified and enabled for the application, pass its hostname in the domain field when you Create an Auth Link:

{
  "expires_on": "2030-12-31T23:59:59.999Z",
  "redirect_uri": "https://example.com/callback",
  "providers": "*",
  "domain": "auth.example.com"
}

The generated Hosted Auth link will use your custom hostname instead of auth.unipile.com.

See Authenticate with Hosted Auth for the complete authentication flow.

Use an Email Tracking Domain

Once the domain is verified and enabled for the application, pass its hostname in tracking_options.custom_domain when you Send an Email or Create a Draft:

{
  "to": [
    {
      "display_name": "John Doe",
      "email": "[email protected]"
    }
  ],
  "subject": "Hello",
  "html": "<a href=\"https://example.com\">Visit our website</a>",
  "tracking_options": {
    "opens": true,
    "clicks": true,
    "custom_domain": "tracking.example.com"
  }
}

The custom domain is used for tracked link redirects and open-tracking pixels. It does not enable tracking by itself: set clicks and/or opens to true, and configure the corresponding tracking webhooks.

See Track clicks & opens for the complete tracking setup.