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

# Custom domains

> Connect your own domain or subdomain so workspace mailboxes send and receive on it.

Custom domains let your workspace mailboxes use an address on a domain your organization controls, such as `support@mail.example.com`. Mermail provisions the domain through the [Email module](https://docs.mermail.app/concepts/email.md), generates the DNS records you need to publish, and checks them for you.

When the domain is fully connected, every mailbox in the workspace moves to it. A mailbox keeps its username, so `support@mermail.app` becomes `support@mail.example.com`. Existing mail stays in place. Review all workspace mailbox addresses before connecting the domain; this change is not limited to your support mailbox.

## Before you begin

You need:

* A workspace on a paid plan, such as Developer. Each workspace supports one custom domain.
* Workspace admin access. Other members can view the setup but cannot add, check, or remove a domain.
* Permission to edit DNS records for the domain.

> [!TIP]
>
> Use a dedicated subdomain, such as `mail.example.com`. Mermail does not accept a domain that already receives email, so a subdomain keeps your existing company email untouched.

## Open Custom Domains

On the Mermail home page, find the **Custom Domains** card and click **Open Custom Domains**. The page belongs to the workspace you have selected and walks you through three steps.

On the Free plan, the page shows **Upgrade to Developer** instead of the domain form. Your workspace keeps using its Mermail address until you upgrade.

## Connect your domain

**1. Choose your domain**

Under **1. Choose your domain**, enter the domain or subdomain that should appear after `@` and click **Check domain**.

Mermail checks that the domain:

* Is a valid domain, such as `example.com` or `mail.example.com`.
* Is not already used by this or another workspace.
* Does not already have email (MX) records.

If the domain is available, click **Add domain**. If it already receives email, Mermail shows the existing MX records and suggests a subdomain. Click **Use mail.example.com** (or the suggested name) to check it instead.

**2. Add DNS records**

Under **2. Add DNS records**, Mermail lists every record to publish. Open the DNS dashboard for your domain and create each record exactly as shown. Use the copy button next to each name and value.

| Mermail field | DNS provider field | What to enter |
| - | - | - |
| Type | Type | The record type shown, such as `TXT`, `MX`, or `CNAME` |
| Name | Name, host, or hostname | The record name shown (`@` means the domain itself) |
| Value | Value, content, target, or mail server | The record value shown |
| Priority | Priority | For an MX record, the priority shown |

DNS providers format names differently. Some expect the full name, such as `selector._domainkey.mail.example.com`. Others expect only the part before your zone. Follow your provider's convention and check that it does not add the domain twice.

> [!WARNING]
>
> Set every `CNAME` record to **DNS only**. If your DNS provider offers a proxy (for example, the orange cloud in Cloudflare), turn it off for these records. A proxied CNAME returns IP addresses instead of the target and never verifies.

Keep existing DNS records that the list does not replace. Do not add guessed SPF, DKIM, or MX values.

**3. Verify the connection**

DNS changes can take a few minutes, or longer depending on your provider and record TTL. Under **3. Verify connection**, click **Check connection**.

Mermail re-checks every record and updates the **Status** column in step 2. For each record that is not verified yet, it looks up your public DNS and explains what it found, for example:

* **No CNAME record found at this name.** The record is missing or has a different name.
* **Returns IP addresses instead of a CNAME.** The record is proxied. Set it to DNS only.
* **Points to another target instead of the expected one.** Correct the record value.
* **Found at `name.example.com.example.com` instead.** Your provider added the domain twice. Enter the name without the domain suffix.
* **A TXT record exists but does not match the expected value.** Replace the value with the one shown.
* **MX priority is 20; expected 10.** Correct the MX priority.

Fix the records, wait for DNS to update, and click **Check connection** again.

> [!TIP]
>
> The domain is ready when both **Sending ready** and **Receiving ready** appear and the step shows **Ready**. Mermail then moves workspace mailboxes to the domain.

## Understand the connection status

The domain card shows two capabilities:

| Capability | Meaning |
| - | - |
| **Sending** | The records used to sign and send mail are verified |
| **Receiving** | The MX record used to receive mail is verified |

If only sending is ready, the domain is **partially verified**. Add the pending MX record, then check the connection again to receive email.

Each DNS record also has its own status:

| Record status | Meaning |
| - | - |
| **Verified** | The record is published correctly |
| **Pending** | The record has not been confirmed yet. Wait for DNS to update and check again |
| **Retrying** | A temporary check error occurred. Mermail will check again |
| **Failed** | Mermail stopped checking this record. Fix it in step 2, then click **Check connection** to restart verification |

## What happens to your mailboxes

* **When the domain is ready**, every mailbox in the workspace moves to the custom domain and keeps its username. New mailboxes are also created on the custom domain.
* **If an address is already taken** on the domain, Mermail cannot move the workspace and shows a conflict message. Resolve the duplicate addresses, then check the connection again.
* **If the workspace moves to the Free plan**, the domain is paused. Mailboxes return to a Mermail-hosted address until you upgrade again.

## Test your new address

Once both capabilities are ready:

1. Open the mailbox you plan to use and confirm its custom-domain address.
2. Send one test message to an external inbox you control. Check the sender, signature, and where the message arrives.
3. Reply from that inbox and confirm the reply appears in Mermail.
4. Update website contact links and other places that display the old address.

If either test fails, check the domain's sending and receiving status before
sending customer messages. Do not assume that delivery to one test inbox proves
delivery to every recipient.

## Improve deliverability

Step 2 also shows a deliverability checklist:

* **SPF and DKIM**: Mermail signs every message once the records above are verified.
* **DMARC**: Mermail does not create this record. Add a TXT record at `_dmarc.<your domain>`. Start with a relaxed policy, such as `v=DMARC1; p=none; rua=mailto:dmarc@<your domain>`, then tighten it to `p=quarantine` and later `p=reject`.
* **Build sending history gradually**: start with a small number of relevant messages to recipients who expect them. Increase volume only when delivery remains healthy. Pause and investigate bounces or complaints instead of following a fixed daily growth target.

## Remove a domain

Under **3. Verify connection**, click **Remove**, type the domain name to confirm, and click **Delete domain**.

* Every mailbox on the domain switches back to its `@mermail.app` address. If that exact address is taken, Mermail assigns a numbered variant.
* Stored mail stays intact.
* To use the domain again later, you must add and verify it from scratch.

Only one custom domain is supported per workspace. To use a different domain, remove the current one first.

> [card] [Email module](https://docs.mermail.app/concepts/email.md)
>
> Review send, receive, DNS verification, and attachment limits.

## Troubleshooting

| Problem | What to do |
| - | - |
| **Upgrade to Developer** appears instead of the domain form | Custom domains require a paid plan. Upgrade the workspace |
| You cannot add, check, or remove the domain | Ask a workspace admin |
| **already has email configured** | The domain already receives email. Use the suggested subdomain, such as `mail.example.com` |
| **already in use** | Another workspace uses this domain. Choose a different domain |
| **You already have a custom domain** | Remove the current domain before adding a different one |
| A CNAME returns IP addresses | Turn off the proxy for the record (DNS only) |
| A record name contains the domain twice | Enter the name without the domain suffix |
| A record shows **Failed** | Fix the record, then click **Check connection** to restart verification |
| **Sending ready** but **Receiving pending** | Add the pending MX record and check the connection again |
| **mailbox addresses conflict** | Resolve duplicate addresses in the workspace, then check the connection again |
| **This domain is paused on the Free plan** | Upgrade to Developer to resume sending and receiving |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.