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

# DNS Setup

> Configure DNS records to verify your domain with MailBreeze

Learn how to configure your DNS records to verify your domain with MailBreeze. These instructions work for any DNS provider (Cloudflare, GoDaddy, Namecheap, Route 53, etc.).

## Add Domain to MailBreeze

Log into your MailBreeze account and navigate to [Domains](https://console.mailbreeze.com/domains) to add a new domain. After entering your domain, you'll see the DNS Setup screen with all required records.

<Frame>
  <img src="https://mintcdn.com/mailbreeze/ak2nLyPy3wQUho9Y/images/dns/mailbreeze-domain-setup-modal.png?fit=max&auto=format&n=ak2nLyPy3wQUho9Y&q=85&s=e7d1e5e44ae56d3b12fb073b14814b61" alt="MailBreeze domain setup modal showing DNS records" width="700" height="966" data-path="images/dns/mailbreeze-domain-setup-modal.png" />
</Frame>

<Note>
  **Use a subdomain** (e.g., `mail.example.com`) instead of your root domain (`example.com`). This keeps your transactional email reputation separate from your corporate email. If your sending domain ever gets blacklisted, your main business email (Google Workspace, Microsoft 365, etc.) remains unaffected.
</Note>

You can click **I'll do this later** to access the dashboard, but you won't be able to send emails until the domain setup is complete.

## Domain Setup Page

After adding your domain, you can access the setup page anytime from **Domains** in your dashboard. Here you can:

* Click **Check** to verify your DNS records
* Click **Send to IT** to email the DNS details to your IT team
* Click **Zone** to download the zone file for import

<Frame>
  <img src="https://mintcdn.com/mailbreeze/ak2nLyPy3wQUho9Y/images/dns/pending-domain-setup-page.png?fit=max&auto=format&n=ak2nLyPy3wQUho9Y&q=85&s=1302b94ffc75fc3560babf106c4189d9" alt="MailBreeze domain setup page with pending DNS records" width="1042" height="792" data-path="images/dns/pending-domain-setup-page.png" />
</Frame>

## Import DNS Zone File

The easiest way to configure your DNS records is to import the zone file directly. Most DNS providers support zone file imports.

<Steps>
  <Step title="Download Zone File">
    On the domain setup page, click **Zone** to download the DNS zone file.
  </Step>

  <Step title="Import to Your DNS Provider">
    In your DNS provider's dashboard, look for an **Import** or **Import Zone File** option and upload the file you downloaded from MailBreeze.

    <Frame>
      <img src="https://mintcdn.com/mailbreeze/ak2nLyPy3wQUho9Y/images/dns/cloudflare-upload-dns-zone.png?fit=max&auto=format&n=ak2nLyPy3wQUho9Y&q=85&s=ee9bc084ab26267845daea90648be7a1" alt="Example: Cloudflare Import and Export button" width="1319" height="480" data-path="images/dns/cloudflare-upload-dns-zone.png" />
    </Frame>

    <Note>
      The screenshot above shows Cloudflare, but most DNS providers have a similar import option in their DNS settings.
    </Note>
  </Step>

  <Step title="Verify Your Records">
    Before clicking Check in MailBreeze, verify your records are live using [MXToolbox DNS Lookup](https://mxtoolbox.com/DNSLookup.aspx). This helps catch any issues before verification fails.
  </Step>

  <Step title="Complete Verification">
    Return to your MailBreeze dashboard and click **Check** to verify your DNS records.
  </Step>
</Steps>

## Manual Setup

If you prefer to add records manually or your DNS provider doesn't support zone file imports, follow these steps. You'll need to add 4 records:

| Record       | Type  | Purpose                                |
| ------------ | ----- | -------------------------------------- |
| Verification | TXT   | Proves you own this domain             |
| SPF          | TXT   | Authorizes our servers to send email   |
| DKIM         | CNAME | Signs emails to prevent tampering      |
| DMARC        | TXT   | Tells receivers how to handle failures |

### Provider-Specific Notes

<AccordionGroup>
  <Accordion title="Cloudflare">
    All DNS records must have proxy status set to **DNS only** (gray cloud icon). Orange cloud (proxied) will cause verification to fail.
  </Accordion>

  <Accordion title="GoDaddy">
    GoDaddy automatically appends your domain to the Name field. If MailBreeze shows `_mailbreeze.mail.example.com`, enter only `_mailbreeze.mail` in GoDaddy.
  </Accordion>

  <Accordion title="AWS Route 53">
    TXT record values must be wrapped in quotes. For example: `"v=spf1 include:_spf.mailbreeze.com -all"`
  </Accordion>

  <Accordion title="Namecheap">
    Use `@` for root domain records. Namecheap automatically appends your domain, so enter only the subdomain portion in the Host field.
  </Accordion>
</AccordionGroup>

<Tip>
  **TTL Tip:** During initial setup, use a low TTL (300 seconds) so changes propagate quickly if you need to fix mistakes. After verification, you can increase it to 3600 or higher.
</Tip>

### Add Your Records

<Steps>
  <Step title="Open Your DNS Provider">
    Log in to your DNS provider and navigate to the DNS management page for your domain.
  </Step>

  <Step title="Add Verification Record">
    Add a TXT record to verify domain ownership.

    | Field           | Value                                           |
    | --------------- | ----------------------------------------------- |
    | Type            | TXT                                             |
    | Name / Host     | Copy from MailBreeze (e.g., `_mailbreeze.mail`) |
    | Value / Content | Copy verification value from MailBreeze         |
    | TTL             | 300 (or Auto)                                   |

    The verification value will look like:

    ```
    mailbreeze-verification=99235a0f3794e445be3340cf5f56e9725fe7ac53c05174fd86683123f5f4aed5
    ```
  </Step>

  <Step title="Add SPF Record">
    Add a TXT record for SPF authentication. This authorizes MailBreeze servers to send email on your behalf.

    | Field           | Value                          |
    | --------------- | ------------------------------ |
    | Type            | TXT                            |
    | Name / Host     | Your subdomain (e.g., `mail`)  |
    | Value / Content | Copy SPF value from MailBreeze |
    | TTL             | 300 (or Auto)                  |

    The SPF value will look like:

    ```
    v=spf1 include:_spf.mailbreeze.com -all
    ```

    <Warning>
      **A domain can only have one SPF record.** Having multiple SPF records will cause email delivery failures.

      If you already have an SPF record from another provider (e.g., Google Workspace, Microsoft 365), MailBreeze will automatically combine them into a single record for you.

      If MailBreeze detects multiple SPF records for the same domain, it will alert you on the domain setup page, tell you which record to delete, and provide an updated combined SPF record to add.
    </Warning>
  </Step>

  <Step title="Add DKIM Record">
    Add a CNAME record for DKIM authentication. DKIM cryptographically signs your emails to prove they haven't been tampered with.

    | Field          | Value                                                               |
    | -------------- | ------------------------------------------------------------------- |
    | Type           | CNAME                                                               |
    | Name / Host    | Copy DKIM name from MailBreeze (e.g., `mailbreeze._domainkey.mail`) |
    | Value / Target | Copy DKIM target from MailBreeze                                    |
    | TTL            | 300 (or Auto)                                                       |

    The DKIM target will look like:

    ```
    mailbreeze._domainkey.mailbreeze.com
    ```
  </Step>

  <Step title="Add DMARC Record">
    Add a TXT record for DMARC (Domain-based Message Authentication, Reporting, and Conformance). This tells receiving mail servers what to do when emails fail SPF or DKIM checks.

    | Field           | Value                                      |
    | --------------- | ------------------------------------------ |
    | Type            | TXT                                        |
    | Name / Host     | Copy from MailBreeze (e.g., `_dmarc.mail`) |
    | Value / Content | Copy DMARC value from MailBreeze           |
    | TTL             | 300 (or Auto)                              |

    The DMARC value will look like:

    ```
    v=DMARC1; p=quarantine; rua=mailto:your-domain@dmarc-reports.mailbreeze.com; ruf=mailto:your-domain@dmarc-reports.mailbreeze.com; pct=100; adkim=r; aspf=r
    ```

    <Info>
      **Understanding DMARC policy:** MailBreeze sets `p=quarantine` by default, which tells receiving servers to send suspicious emails to spam rather than rejecting them outright. This protects your deliverability while you're building sender reputation. The `rua` and `ruf` parameters send DMARC reports to MailBreeze so we can monitor your domain's authentication health.
    </Info>
  </Step>

  <Step title="Verify Your Records">
    Before clicking Check in MailBreeze, verify your records are live using [MXToolbox DNS Lookup](https://mxtoolbox.com/DNSLookup.aspx). Enter your full record name (e.g., `_mailbreeze.mail.example.com`) and confirm the values match what MailBreeze expects.
  </Step>

  <Step title="Complete Verification">
    Return to your MailBreeze dashboard and click **Check** to verify your DNS records. DNS propagation typically completes within a few minutes, but can take up to 72 hours in some cases.
  </Step>
</Steps>

## After Verification

Once all 4 records show as verified, your domain is ready to send. You can:

* [Send your first email](/api-reference/emails/send) using the API
* [Set up an SDK](/sdks/overview) in your preferred language
* Configure sender addresses in your dashboard

## Troubleshooting

<AccordionGroup>
  <Accordion title="Verification Failed">
    Double-check the following:

    * Record values were copied exactly from MailBreeze (no extra spaces or missing characters)
    * You entered only the subdomain portion if your provider auto-appends the domain
    * TXT values are wrapped in quotes if your provider requires it (e.g., Route 53)
    * You're adding records to the correct domain/subdomain
  </Accordion>

  <Accordion title="Records Not Propagating">
    DNS propagation usually takes 5-15 minutes but can take up to 72 hours. To check propagation status:

    1. Use [MXToolbox](https://mxtoolbox.com/DNSLookup.aspx) or [WhatsMyDNS](https://www.whatsmydns.net/) to verify records are visible globally
    2. If records appear in these tools but MailBreeze still shows pending, wait a few minutes and click **Check** again
  </Accordion>

  <Accordion title="Cloudflare: Error Code 1004">
    This error indicates DNS records are being proxied. In Cloudflare, click the orange cloud icon next to each record to change it to gray (DNS only).
  </Accordion>

  <Accordion title="Still Pending After 72 Hours">
    If verification is still pending after 72 hours:

    1. Use [MXToolbox](https://mxtoolbox.com/) to verify records are visible
    2. Compare the visible records against what MailBreeze expects
    3. Contact [support@mailbreeze.com](mailto:support@mailbreeze.com) with your domain name and we'll investigate
  </Accordion>
</AccordionGroup>

## Need Help?

Contact us at [support@mailbreeze.com](mailto:support@mailbreeze.com) for assistance with domain verification.