# Custom email domains for notifications (/docs/guides/tutorials/add-a-custom-email-domain-to-your-brand)




Your envelope creators and recipients should recognize who sent the email the moment it lands in their inbox. By default, Verdocs sends notifications from `notifications@verdocs.com`. With **custom email domains**, you can send from an address on your own domain, e.g. 'Acme Documents \<[notifications@notify.acme.com](mailto:notifications@notify.acme.com)>' so every notification reflects your brand.

Custom email domains are configured via Brands. When an envelope is sent, Verdocs resolves the brand from the envelope assignment, your organization's default brand, or (in parent/child org hierarchies) a parent organization's default brand. You may configure custom domains either via the Verdocs Web App (**Settings → Brands → \{brand} → Sender Email**) or via our REST API / SDKs.

> Note: The custom **From** address is used only when that brand's domain is fully verified; until then, notifications continue to send from the platform default.

## Prerequisites [#prerequisites]

Before you begin, make sure you have:

* **Admin or Owner** access in your organization, or an API token for same.
* At least one Brand defined. Navigate to **Settings → Brands**, or call [Create Brand](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/brands/createBrand).
* The ability to add custom DNS records for the domain or subdomain you want to send from.
* A sending domain that is **not** a subdomain of `verdocs.com` or `verdocs.io` (these are reserved).

We strongly recommend using a **dedicated subdomain** such as `notify.acme.com` rather than your primary corporate domain (`acme.com`). A dedicated subdomain isolates your notification sending reputation from everyday business email - if deliverability issues arise on the notification channel, they won't affect mail sent from your main domain.

***

## How it works [#how-it-works]

At a high level, you tell us which subdomain and sender address to use, then add DNS records that we provide in response (to prove that you control the domain). We will periodically check for these records to be created, then complete the verification process. Once all checks pass, notifications for communications related to the selected Brand will automatically use your custom address.

<img alt="Custom email domain workflow" src="__img0" />

### Step 1 - Configure the sender identity [#step-1---configure-the-sender-identity]

You must provide four pieces of information when adding an email domain:

| Input               | API field      | Required | Example            |
| ------------------- | -------------- | -------- | ------------------ |
| Sending domain      | `subdomain`    | Yes      | `notify.acme.com`  |
| From local part     | `local_part`   | Yes      | `notifications`    |
| Sender display name | `display_name` | No       | `Acme Documents`   |
| Reply-to address    | `reply_to`     | No       | `support@acme.com` |

This can be done via the [Verdocs web application](https://app.verdocs.com) or the [Verdocs API](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/brands/addBrandEmailDomain).

After you submit, Verdocs registers the domain with our email infrastructure and returns your brand record with `email_domain_status` set to `pending`. The response also includes `email_dkim_tokens` - three unique tokens you will use to create DKIM CNAME records.

The resulting `From address` recipients, once verified, will see:

'\{display\_name or brand/org name} \<\{local\_part}@\{subdomain}>'

For example: 'Acme Documents \<[notifications@notify.acme.com](mailto:notifications@notify.acme.com)>'.

### Step 2 - Add DNS records [#step-2---add-dns-records]

Add the following records in your DNS provider. All three record types are **required** before the domain becomes active.

#### SPF (TXT) [#spf-txt]

Authorizes Verdocs' mail servers to send on behalf of your domain.

|           |                                         |
| --------- | --------------------------------------- |
| **Type**  | TXT                                     |
| **Host**  | `notify.acme.com` (your `email_domain`) |
| **Value** | `v=spf1 include:amazonses.com ~all`     |

If your domain already has an SPF TXT record on that host, **do not create a second one**. Instead, add `include:amazonses.com` to your existing SPF record.

#### DKIM (3× CNAME) [#dkim-3-cname]

Adds a cryptographic signature to outgoing mail. Verdocs provides three tokens in `email_dkim_tokens` after you add the domain. Create one CNAME per token:

|           |                                       |
| --------- | ------------------------------------- |
| **Type**  | CNAME                                 |
| **Host**  | `{token\}._domainkey.notify.acme.com` |
| **Value** | `{token\}.dkim.amazonses.com`         |

Repeat for all three tokens.

#### DMARC (TXT) [#dmarc-txt]

Tells receiving mail servers how to handle messages that fail SPF or DKIM checks.

|           |                          |
| --------- | ------------------------ |
| **Type**  | TXT                      |
| **Host**  | `_dmarc.notify.acme.com` |
| **Value** | `v=DMARC1; p=reject;`    |

Verification requires both `v=DMARC1` and `p=reject` in the record value. You can optionally append an aggregate reporting address, for example:

`v=DMARC1; p=reject; rua=mailto:dmarc-reports@acme.com`

Because the sending subdomain is dedicated to Verdocs notifications, `p=reject` is appropriate: if DMARC fails, something is misconfigured and the message should not be delivered.

### Step 3 - Verify DNS [#step-3---verify-dns]

Once your DNS records are in place, trigger a verification check. Verdocs evaluates three independent checks:

| Check | Field updated          | What passes                                                                     |
| ----- | ---------------------- | ------------------------------------------------------------------------------- |
| SPF   | `email_spf_verified`   | TXT record on your sending domain contains `v=spf1` and `include:amazonses.com` |
| DKIM  | `email_dkim_verified`  | DKIM identity reports a successful status                                       |
| DMARC | `email_dmarc_verified` | TXT record at `_dmarc.\{email_domain\}` contains `v=DMARC1` and `p=reject`      |

When **all three** are `true`, `email_domain_status` becomes `verified` and `email_domain_verified_at` is set to the current timestamp.

You can verify on demand at any time. Verdocs also re-checks automatically:

* **Pending domains** - checked approximately every 15 minutes until verified.
* **Verified domains** - re-checked daily. If a previously passing record is removed, status moves to `suspended` and sending reverts to the platform default until DNS is fixed and verification passes again.

DNS changes typically propagate within 15 - 60 minutes, though some providers can take up to 48 hours.

### Step 4 - Send notifications from your domain [#step-4---send-notifications-from-your-domain]

Once verified, envelope notifications tied to that brand use your custom **From** address. The display name comes from `email_display_name` if set; otherwise Verdocs uses the envelope sender name, organization name, or profile name depending on context.

If verification is incomplete (`pending`) or a re-check fails (`suspended`), Verdocs continues sending from `notifications@verdocs.com` - your recipients are not left without mail, but they will see the platform sender until DNS is healthy again.

***

## Status lifecycle [#status-lifecycle]

| Status      | Meaning                                                   | Sending behavior                                        |
| ----------- | --------------------------------------------------------- | ------------------------------------------------------- |
| `pending`   | Domain configured; DNS verification incomplete            | Platform default sender                                 |
| `verified`  | SPF, DKIM, and DMARC all pass                             | Custom From address active                              |
| `suspended` | Was verified, but a re-check found missing or invalid DNS | Reverts to platform default until fixed and re-verified |

**Removing a domain** clears all email fields (`email_domain`, `email_local_part`, `email_display_name`, `email_reply_to`, verification flags, DKIM tokens, and timestamps) and deletes the registered domain identity. This is immediate - there is no grace period.

**Constraints to be aware of:**

* One email domain per brand. Remove the existing domain before adding a different one.
* Each `email_domain` value can only be registered to one brand across the entire Verdocs platform.
* Subdomains of `verdocs.com` and `verdocs.io` cannot be used.
* The sending domain must be a valid multi-label domain (e.g. `notify.acme.com`, not a single label like `acme`).

***

## How notifications choose a brand [#how-notifications-choose-a-brand]

Not every notification is tied to the same brand. Verdocs resolves the brand in this order:

1. The **brand assigned to the envelope** (if set when the envelope was created).
2. Your **organization's default brand** (if configured).
3. In parent/child organization hierarchies, the **parent organization's default brand**.

The custom email domain on the resolved brand is used for that notification's **From** address - but only when that brand's domain is fully verified as described above. Brand visual settings (logo, colors) follow the same resolution path independently of email domain status.

For more on how notifications behave generally - including when Verdocs sends email versus when you handle delivery yourself - see [Controlling workflow behaviors](https://developers.verdocs.com/docs/guides/tutorials/controlling-workflow-behaviors-notifications-names-and-more).