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

# Add a mail domain

> Register a domain for hosted mailboxes, publish the DNS records Brudcast generates, verify them, and see what each record does.

export const DemoVideo = ({id, title, embedUrl, src, poster, duration}) => {
  if (embedUrl) {
    return <figure className="brd-media" data-media-id={id}>
        <iframe className="brd-media-frame w-full aspect-video" src={embedUrl} title={title} allow="accelerometer; autoplay; clipboard-write; encrypted-media; picture-in-picture" allowFullScreen />
      </figure>;
  }
  if (src) {
    return <figure className="brd-media" data-media-id={id}>
        <video className="brd-media-frame w-full aspect-video" src={src} poster={poster} controls playsInline preload="metadata" />
      </figure>;
  }
  const label = duration ? `Video walkthrough coming soon · ${duration}` : "Video walkthrough coming soon";
  return <Placeholder id={id} kind="video" label={label} description={title} ratio="16 / 9" icon={<PlayIcon />} />;
};

export const Loop = ({id, src, alt, caption}) => {
  if (!src) {
    return <Placeholder id={id} kind="loop" label="Animation coming soon" description={alt} icon={<PlayIcon />} />;
  }
  return <figure className="brd-media" data-media-id={id}>
      <video className="brd-media-frame" src={src} autoPlay muted loop playsInline aria-label={alt} />
      {caption && <figcaption className="brd-media-caption">{caption}</figcaption>}
    </figure>;
};

export const Screenshot = ({id, src, srcDark, alt, caption}) => {
  if (!src) {
    return <Placeholder id={id} kind="screenshot" label="Screenshot coming soon" description={alt} icon={<ImageIcon />} />;
  }
  return <figure className="brd-media" data-media-id={id}>
      <img className="brd-media-frame block dark:hidden" src={src} alt={alt} />
      <img className="brd-media-frame hidden dark:block" src={srcDark || src} alt={alt} />
      {caption && <figcaption className="brd-media-caption">{caption}</figcaption>}
    </figure>;
};

Get a domain ready to host mailboxes. At the end, its DNS status reads **DNS verified** and you
can start adding addresses.

<Screenshot id="ss-mailbox-add-a-mail-domain-hero-verified" alt="A mail domain's page showing the DNS verified badge with the Routing, DKIM, SPF and DMARC checks all green" />

<Info>
  **Before you start:**

  * You need access to your domain's DNS settings at your DNS provider.
  * Your organization needs a Mailbox plan. New organizations start on the free plan, which
    includes one mail domain.
  * Any member of the organization can add mail domains and mailboxes.
</Info>

<Accordion title="Watch the walkthrough" icon="circle-play">
  <DemoVideo id="V16" title="Set up mailboxes on your domain" duration="3 min" />
</Accordion>

<Steps>
  <Step title="Open the Add Mail Domain panel">
    In the sidebar, select **Mailboxes**, then select **Add Mail Domain**.

    <Screenshot id="ss-mailbox-add-a-mail-domain-01-add-panel" alt="The Add Mail Domain panel with example.com typed in the Domain field" />
  </Step>

  <Step title="Enter your domain">
    In **Domain**, enter the domain people's addresses will be on. For `jane@example.com`, enter
    `example.com`. Select **Add Mail Domain**.

    The domain appears in **Your Mail Domains** with the DNS status **Setup pending**.

    If the same domain is already one of your sending domains, Brudcast links the two
    automatically and the **Sends campaigns** column shows **Yes**. That changes the SPF record
    you publish in the next step.
  </Step>

  <Step title="Copy the DNS records">
    Select the domain name to open it. On the **Complete your mail domain setup** banner, select
    **View DNS Records**, or open the **DNS Records** tab.

    The records are grouped:

    * **Receiving records**: the MX record that routes inbound mail to Brudcast.
    * **Authentication records**: SPF, DKIM and DMARC.
    * **Autodiscovery records**: optional records that help some mail clients set themselves up.
    * **Shared records**: shown only when the domain is also a sending domain. These serve both.

    Each row has copy buttons for **Host (name)** and **Value (points to)**. The DKIM record is
    added once Brudcast has generated your domain's signing key. If it isn't listed yet, check the
    tab again later.

    <Screenshot id="ss-mailbox-add-a-mail-domain-02-dns-tab" alt="The DNS Records tab showing Receiving records, Authentication records and Autodiscovery records, each row marked Unconfigured" />
  </Step>

  <Step title="Publish the records with your DNS provider">
    Create each record at your DNS provider, copying the host and value exactly. Every record is
    explained in [The record set](#the-record-set) below.

    <Warning>
      A domain can have only one SPF record and one DMARC record. If it already has either, don't
      add a second. Read [The SPF record](#the-spf-record) and
      [The DMARC record](#the-dmarc-record) first.
    </Warning>

    <Snippet file="dns-propagation.mdx" />
  </Step>

  <Step title="Verify">
    Back on the domain's page, select **Verify DNS**. Brudcast checks every record and updates the
    **Status** column on the **DNS Records** tab. The strip at the top shows **Routing**, **DKIM**,
    **SPF** and **DMARC**.

    The domain becomes **DNS verified** when the MX record and the DKIM record match. SPF, DMARC
    and the autodiscovery records are checked and shown too, but they don't decide the status.

    <Loop id="lp-mailbox-add-a-mail-domain-verify" alt="Selecting Verify DNS, then the Routing and DKIM checks turning green and the badge changing to DNS verified" />
  </Step>
</Steps>

## The record set

Every record is published with a TTL of 300 seconds. In the table, `example.com` stands for your
domain. Copy the exact values from the **DNS Records** tab rather than from this page: the DKIM
value is unique to your domain.

| Group          | Type        | Host (name)                         | Value (points to)                                                                                | Priority | Required for DNS verified |
| -------------- | ----------- | ----------------------------------- | ------------------------------------------------------------------------------------------------ | -------- | ------------------------- |
| Receiving      | MX          | `example.com`                       | `mail.prod.brudcast.org.`                                                                        | 10       | Yes                       |
| Authentication | TXT (SPF)   | `example.com`                       | `v=spf1 include:_spf.prod.brudcast.org -all`, or the shared value below                          |          | No                        |
| Authentication | TXT (DKIM)  | `<selector>._domainkey.example.com` | `v=DKIM1; …` with your domain's public key                                                       |          | Yes                       |
| Authentication | TXT (DMARC) | `_dmarc.example.com`                | `v=DMARC1; p=none; rua=mailto:dmarc@prod.brudcast.org; ruf=mailto:dmarc@prod.brudcast.org; fo=1` |          | No                        |
| Autodiscovery  | CNAME       | `autoconfig.example.com`            | `autoconfig.prod.brudcast.org.`                                                                  |          | No                        |
| Autodiscovery  | CNAME       | `autodiscover.example.com`          | `autodiscover.prod.brudcast.org.`                                                                |          | No                        |
| Autodiscovery  | SRV         | `_imaps._tcp.example.com`           | `10 5 993 imap.prod.brudcast.org.`                                                               | 10       | No                        |
| Autodiscovery  | SRV         | `_submission._tcp.example.com`      | `10 5 587 smtp.prod.brudcast.org.`                                                               | 10       | No                        |

The MX record is what tells other mail servers to deliver your domain's mail to Brudcast. If the
domain already receives mail elsewhere, remove the old MX records once you're ready to switch, so
all mail goes to one place.

<Warning>
  **The autodiscovery records don't point at a live server yet.** The four `autoconfig`,
  `autodiscover` and SRV records advertise hostnames on `prod.brudcast.org` that aren't serving IMAP
  or SMTP today. They're optional and marked "No" for verification, so you can publish them or leave
  them out — but a mail client that picks them up will fail to connect. Set your client up with the
  manual settings (`mail.brudcast.io`, IMAP `993`, SMTP `465`) instead. See
  [Connect a mail client](/mailbox/connect-a-mail-client#server-settings).
</Warning>

### The SPF record

A domain can publish only one SPF record, and the mail domain's record sits at the domain itself, so
it has to describe every service that sends as your domain.

| The domain is                      | Generated value                                                          |
| ---------------------------------- | ------------------------------------------------------------------------ |
| A mail domain only                 | `v=spf1 include:_spf.prod.brudcast.org -all`                             |
| A mail domain and a sending domain | `v=spf1 include:brd.spf.example.com include:_spf.prod.brudcast.org ~all` |

A mail-domain-only record covers everything Brudcast sends for the domain, so `-all` tells receivers
to reject anything else. When the domain also sends campaigns, `~all` is used instead, so legitimate
mail from another sender of yours isn't bounced.

<Warning>
  If the domain already has an SPF record, for example for your office email provider, don't publish
  a second one. Two SPF records make SPF fail for every message. Add Brudcast's `include:` terms to
  the existing record instead, and keep a single `all` at the end.
</Warning>

### The DMARC record

The generated policy is `p=none`, which is monitoring only: receivers report on failing mail but
don't reject it. A domain can have only one DMARC record. The value is identical to the one
generated for a sending domain, so one record serves both.

### The autodiscovery records

These are optional. They let a mail client find its server settings from an email address alone:
`autoconfig` is used by Thunderbird, `autodiscover` by Outlook, and the two SRV records advertise
where clients read mail (`_imaps`) and send it (`_submission`). Whether or not you publish them,
check the settings a client fills in against [Connect a mail client](/mailbox/connect-a-mail-client).

### Sharing records with a sending domain

When a mail domain and one of your [sending domains](/channels/email/dns-records) have the same name,
Brudcast links them, whichever you added first.

* **SPF and DMARC move to Shared records** on both the mail domain's and the sending domain's DNS
  tab, so each is published once rather than on both.
* **The SPF value includes both paths**: the sending domain's `brd.spf` delegation and the mailbox
  servers, ending in `~all`. Without both, one of the two kinds of mail would fail SPF.
* **Everything else stays separate.** The sending domain's SPF delegation CNAME, its two DKIM CNAMEs
  at `brd1._domainkey` and `brd2._domainkey`, and its tracking CNAME have their own names, as do the
  mail domain's MX, DKIM and autodiscovery records. None of them collide, because a domain can hold
  as many DKIM records as it has selectors.

<Warning>
  If you add the sending domain after the mail domain is already set up, the generated SPF value
  changes from `-all` to `~all` and gains the `brd.spf` include. Update the SPF record at your DNS
  provider to match, or campaign mail will fail SPF.
</Warning>

## What happens next

* Brudcast re-checks every mail domain's records once a day. If a required record disappears, the
  status changes to **Not routing**.
* The routing panel on the **Mailboxes** tab says whether inbound mail is being delivered. See
  [How mail reaches a mailbox](/mailbox/overview#how-mail-reaches-a-mailbox).
* You can create mailboxes now. You don't have to wait for verification. Mailboxes can sign in and
  send before the records are published, but they won't receive mail until the MX record is in
  place.

## Troubleshooting

<AccordionGroup>
  <Accordion title="“… is a Brudcast-owned domain and cannot be added”" icon="circle-alert">
    **Why:** domains that belong to Brudcast, such as `brudcast.com` and `brudcastmail.com`, can't
    host your mailboxes.

    **Fix:** add a domain you own.
  </Accordion>

  <Accordion title="“This domain is already hosting mailboxes”" icon="circle-alert">
    **Why:** your organization has already added this domain.

    **Fix:** open it from the **Your Mail Domains** table instead of adding it again.
  </Accordion>

  <Accordion title="“Plan limit reached” when you add a domain" icon="circle-alert">
    **Why:** your Mailbox plan's mail domain allowance is used up. The free and Starter plans
    include one mail domain.

    **Fix:** remove a mail domain you no longer use, or move to a larger plan. See
    [Plans and subscriptions](/billing/plans-and-subscriptions).
  </Accordion>

  <Accordion title="The status stays Not routing" icon="circle-alert">
    **Why:** the MX or DKIM record is missing, or its value differs from what Brudcast generated.
    Values are compared exactly, ignoring only letter case and a trailing dot.

    **Fix:** compare each record at your provider with the **DNS Records** tab. A common slip is a
    provider that appends your domain to the host automatically, which turns `example.com` into
    `example.com.example.com`. Enter only the part your provider asks for, wait a few minutes,
    then select **Verify DNS** again.
  </Accordion>

  <Accordion title="SPF or DMARC shows Unconfigured, but the domain is DNS verified" icon="circle-alert">
    **Why:** SPF and DMARC are marked verified only when the published value matches the generated
    value exactly. If you merged Brudcast's SPF into an existing record, or kept your own DMARC
    policy, the check won't match. That doesn't change the domain's status.

    **Fix:** if you merged on purpose, no action is needed. Otherwise publish the value shown on
    the **DNS Records** tab.
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Create a mailbox" icon="inbox" href="/mailbox/manage-mailboxes#create-a-mailbox">
    Add the first addresses on your domain.
  </Card>

  <Card title="Connect a mail client" icon="mail" href="/mailbox/connect-a-mail-client">
    Sign in from Apple Mail, Outlook, Thunderbird or Gmail.
  </Card>

  <Card title="Sending domain DNS records" icon="list" href="/channels/email/dns-records">
    The records for campaign and API mail.
  </Card>
</Columns>