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

# Setup and authenticate your email domain

> Set up domain authentication so Userpilot can send emails from your own domain with high deliverability.

## Overview

Authenticating your domain is required to allow Userpilot to send emails on your behalf and provides the following benefits:

* Protects against email spoofing.
* Meets email clients' sender requirements.
* Enables reliable open / click tracking.

***

## Prerequisites

* A valid registered domain that you own. Email messages will be sent using this domain.
* Access to your domain's **DNS** provider (GoDaddy, Cloudflare, Route 53, etc.).

***

## Authenticate DKIM + MAIL FROM (required)

<Steps>
  <Step title="Add your domain in Userpilot">
    1. Open **Settings → Email → Domains** in the Userpilot dashboard.
    2. Click **Add domain**, enter **`yourdomain.com`**, then click **Create**.

    <Frame caption="Domain just added – pending authentication">
      <img src="https://mintcdn.com/userpilot/6mq0DeMvNIpVRWN5/images/email-domain-not-authenticated.png?fit=max&auto=format&n=6mq0DeMvNIpVRWN5&q=85&s=1920a2357c4956764106a57385b76e6d" alt="Pending domain authentication status" width="3086" height="1054" data-path="images/email-domain-not-authenticated.png" />
    </Frame>
  </Step>

  <Step title="Create the DNS records">
    Add the generated DNS records in your DNS provider.

    <Note>
      #### Record Description

      * **DKIM:** DKIM adds a tamper-proof signature to every email your app sends. Receiving mail providers check that signature against public keys in your DNS to confirm the message really came from you and wasn’t altered in transit.
      * **SPF:** SPF is an allow-list that Internet Service Providers use to check email authorization.
        * **TXT Record** → Authorizes our mail server to send emails on your behalf.
        * **MX Record** → A return-path which mail clients use to route bounces. Ensures block spoofing and keeps your main email (e.g., Gmail/Office 365) untouched.
      * **DMARC:** DMARC helps protect your domain from email spoofing by working alongside SPF and DKIM. It lets you define how email providers should handle messages that fail authentication checks and provides reports so you can monitor and improve your domain’s email security.

      > **Note:** You don't need to add or adjust your DMARC TXT record if you already have one. Simply review it to ensure it meets your needs.
    </Note>

    <Warning>
      If you use Cloudflare, set all records to **DNS Only**. Proxying breaks verification.
    </Warning>
  </Step>

  <Step title="Verify">
    DNS may take a few minutes (rarely up to 48h).

    <Note>
      Verified domains will automatically cover all their subdomains.\
      For example, if you’ve verified [**example.pxl.studio**](http://example.pxl.studio), you can now send emails from addresses like [**noreply@eng.example.pxl.studio**](mailto:noreply@eng.example.pxl.studio)
    </Note>

    <Check>
      Status switches to **Authenticated** when DKIM and SPF records are valid. You are now ready to send emails.
    </Check>

    <Frame caption="Authenticated status">
      <img src="https://mintcdn.com/userpilot/6mq0DeMvNIpVRWN5/images/email-domain-authenticated.png?fit=max&auto=format&n=6mq0DeMvNIpVRWN5&q=85&s=8b1d5d0c1c79073cbafb7639d2004fa1" alt="Domain authenticated status" style={{ width:"100%" }} width="3074" height="1036" data-path="images/email-domain-authenticated.png" />
    </Frame>
  </Step>
</Steps>

<Warning>
  If DNS records are not found after **72 hours**, the status changes to **Failed**. Click **Retry Verification** to restart the lookup process.

  <img src="https://mintcdn.com/userpilot/XL7YmTTWVDAuL5SC/images/email-domain-failed-authentication.png?fit=max&auto=format&n=XL7YmTTWVDAuL5SC&q=85&s=990acf229f0704365a25bc7a96a857ce" alt="Domain failed authentication status" width="3048" height="1216" data-path="images/email-domain-failed-authentication.png" />
</Warning>

***

## Custom Link-Tracking Domain (Optional - Strongly Recommended)

Spam filters and recipient servers assess the root domain of email links to decide whether to trust an email, so using a domain you control significantly improves deliverability and reduces “suspicious link” flags.

By default, Userpilot serves your email links with its own domain to track opens and clicks. With custom tracking domain enabled, those assets are served from your custom tracking subdomain instead (e.g., `tracking.yourdomain.com`). This keeps link URLs brand aligned and leverages your domain's reputation for better inbox placement.

### Option A – Userpilot-Managed *(Easiest)*

<Steps>
  <Step title="Request a tracking subdomain">
    Email [**support@userpilot.com**](mailto:support@userpilot.com) with the tracking subdomain you want to use (e.g. `tracking.yourdomain.com`). Make sure the subdomain is not used for other purposes.

    Userpilot will then provision the following resources for you:

    * SSL certificate.
    * CDN Distribution.
  </Step>

  <Step title="Verify the CNAME records">
    We will reach out to you once the resources are provisioned and ready to use. We will provide you with a set of CNAME records for both resources to add in your DNS provider.
  </Step>

  <Step title="Confirm the setup">
    Confirm to the support team that you have added the CNAME records. We will then configure the custom tracking domain for your emails.
  </Step>
</Steps>

### Option B – Bring your Own CDN *(Advanced)*

<Tabs>
  <Tab title="US region">
    Origin: **`r.us-west-2.awstrack.me`**
  </Tab>

  <Tab title="EU region">
    Origin: **`r.eu-west-3.awstrack.me`**
  </Tab>
</Tabs>

If your security policy requires using your own CDN/certificate, you can manage the tracking subdomain yourself.

1. Create a CDN/edge distribution (e.g. CloudFront) for the tracking subdomain (e.g. `tracking.yourdomain.com`) pointing to the origin value above.

<Info>
  Make sure your CDN is configured to:

  * Force **HTTPS** protocol.
  * Forward original Host headers to the origin.
  * Disable caching.
</Info>

2. Attach an SSL certificate for the subdomain to your CDN distribution.
3. Add a **CNAME** record for your subdomain to point to your CDN distribution.

   ```txt theme={null}
   <tracking.yourdomain.com> CNAME  <your-cdn-domain.example.net>
   ```
4. Reach out to [**support@userpilot.com**](mailto:support@userpilot.com) when you have verified the setup. We will then configure the custom tracking domain for your emails and confirm it with you.

<Note>
  You can find your Userpilot hosting region in the [Environment page](https://run.userpilot.io/environment). If your HTTP endpoint is `https://analytex-eu.userpilot.io/`, you're in the EU region.
</Note>

***

## Verify Link-Tracking Domain

```bash theme={null}
curl -I https://tracking.yourdomain.com/favicon.ico
```

A 200 response with headers like below confirms the setup:

```txt theme={null}
x-amz-ses-region: us-west-2 # or eu-west-3
x-amz-ses-request-protocol: https
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Records still pending after 24 h">
    * Check for typos in records.
    * Disable CDN/proxy if using Cloudflare.
  </Accordion>

  <Accordion title="Emails land in spam after authenticating or marked as suspicious">
    * Add **DMARC** and a **tracking subdomain**.
    * Make sure your emails contain valid links.
  </Accordion>
</AccordionGroup>