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

> ## Agent Instructions
> AhaSend stores all message data in the EU. See /facts.
> The API base URL is https://api.ahasend.com. Send the API key in the Authorization: Bearer header. See /api-reference/authentication.
> Use send.ahasend.com for SMTP. Ports 25, 587 and 2525 use STARTTLS. Port 465 is not supported. See /smtp.
> For send-only integrations, create an API Key v2 under Credentials → Add and scope it to messages:send:{your-domain}. See /send-api/credentials and /api-reference/scopes.

# Domain Setup: SPF, DKIM and DMARC Records

> Add and verify your sending domain in AhaSend: publish the SPF, DKIM (CNAME), DMARC, return-path and tracking DNS records, then run the DNS check.

To send email with AhaSend, add your domain, publish its SPF, DKIM and DMARC records, then run the DNS check; this guide walks through each step.

Free includes 3 sending domains; Pro and Max include unlimited domains. Automatic DKIM rotation is available on all three plans. Custom DKIM selectors and bring-your-own DKIM come with [DNS whitelabel](https://ahasend.com/docs/scale/dns-whitelabel.md) on Max. See [plans and features](https://ahasend.com/docs/facts.md#plans-and-features).

> [!WARNING]
>
> **Domain verification is required** before you can send any emails through AhaSend. Unverified domains cannot send emails and will result in API errors.

## Which DNS records do I need?

Publish the records shown for your domain in the dashboard. New managed-DNS domains use these record types:

| Record | Type | Purpose | Required for sending? |
| - | - | - | - |
| SPF | TXT | Authorizes AhaSend through `include:spf.ahasend.com` | Yes |
| DKIM | Two CNAMEs | Active and standby signing keys | Yes; publish both for rotation |
| DMARC | TXT | Sets your domain's authentication policy | Yes |
| Return-path | CNAME | Handles bounces and supports SPF alignment | Recommended |
| Tracking | CNAME | Uses your domain for tracking links | When tracking is used |
| MX | Dashboard values | Receives inbound email for routing | When inbound routing is used |

Copy the exact hostnames and values from your domain page; manual DNS and whitelabel setups can differ.

## Why does AhaSend need DNS records?

Email receivers use multiple authentication methods to verify that emails are legitimate. When you properly configure your domain with AhaSend, you're telling receiving servers that:

1. **You own the domain** and have the rights to send emails from it
2. **You've authorized AhaSend** to send emails on behalf of your domain
3. **Your emails are authentic** and not spoofed or malicious

Without proper domain setup, your emails will either be **rejected outright** or **land in spam folders**, significantly impacting your delivery rates.

> [!TIP]
>
> **Subdomain recommendation:** Use a subdomain like `email.yourcompany.com` instead of your main domain for transactional emails. This separates configuration and monitoring; mailbox providers can still consider the parent domain’s reputation. See [sending subdomains](https://ahasend.com/docs/deliverability.md#should-transactional-mail-use-a-separate-subdomain).

## Sending Type

Each domain has a sending type: **transactional** or **marketing**. A new domain is transactional. Set it in the domain's settings in the dashboard, or with `sending_type` in [Create Domain](https://ahasend.com/docs/api-reference/domains/create-domain.md) or [Update Domain](https://ahasend.com/docs/api-reference/domains/update-domain.md), to match the mail you send from the domain through the API or SMTP:

| You send from the domain | Sending type | What AhaSend does |
| - | - | - |
| Password resets, receipts, notifications: mail a recipient expects from their own actions | Transactional | Sends over the transactional infrastructure with the hourly sending limit |
| Newsletters, promotions, announcements through the API or SMTP | Marketing | Sends over the marketing infrastructure with the [daily marketing limit](https://ahasend.com/docs/campaigns/marketing-limit.md), and adds one-click [unsubscribe headers](https://ahasend.com/docs/campaigns/unsubscribe.md) to every message |

Campaigns made with [Campaign Builder](https://ahasend.com/docs/campaigns.md) do not depend on this setting. They always go out over the marketing infrastructure, from any verified domain, whatever its sending type. The sending type matters for marketing mail that you send yourself, from your own tool, through the API or SMTP: that mail must come from a marketing domain.

For that mail, the visible unsubscribe link and the handling of opt-outs are your responsibility: put `{{unsubscribe_url}}` in the content for a signed AhaSend link that adds a suppression when it is used, or use your own unsubscribe endpoint with the one-click headers, and keep the opt-out in your own data. See [unsubscribe links and one-click headers](https://ahasend.com/docs/campaigns/unsubscribe.md).

> [!WARNING]
>
> Marketing mail from a transactional domain, a newsletter sent through the API or SMTP for example, can get your account paused. Give marketing mail its own subdomain, such as `news.yourcompany.com`, set that subdomain to marketing, and keep your transactional mail on its own domain. See [why the two should stay apart](https://ahasend.com/docs/deliverability.md#which-sending-type-should-my-domain-use).

A change of the sending type applies to new messages within five minutes. It does not lift a [pause](#why-is-sending-paused-on-my-domain).

## Prerequisites

Before setting up your domain, make sure you have:

* **Access to your DNS provider** (usually your hosting provider or domain registrar)
* **An AhaSend account** with verified email address
* **The domain or subdomain** you want to use for sending emails

> [!NOTE]
>
> **Managed DNS vs manual DNS:** New domains in AhaSend use managed DNS (DNS v3) by default. Managed DNS shows two DKIM CNAME records so AhaSend can rotate DKIM keys safely over time. Some older or explicitly manual domains may still use the legacy single-DKIM-TXT setup instead. Your domain details page is always the source of truth for the exact records you need to publish.

**1. Add your domain**

Start by adding your domain to your AhaSend account:

1. **Log in to your [AhaSend Dashboard](https://dash.ahasend.com)**
2. **Navigate to Domains** in the sidebar
3. **Click "Add Domain"**
4. **Enter your domain name** (e.g., `email.yourcompany.com`)
5. **Click "Create Domain"**

You'll be redirected to the domain details page where you can see all required DNS records.

> [!NOTE]
>
> **API Alternative:** You can also add domains programmatically using our [Domains API](https://ahasend.com/docs/api-reference/domains/create-domain.md).

**2. Configure DNS records**

Add the DNS records shown on your domain details page. The exact hostnames and values can vary by account, domain mode, and reseller configuration.

> [!NOTE]
>
> **Required for sending:** SPF, DKIM, and DMARC must be valid before the domain can send mail.
>
> **Optional or feature-specific:** Return-path, tracking, subscription management, media, and MX records improve deliverability or enable product features, but they are not all required for basic sending.

> [!TIP]
>
> **Custom subdomains:** AhaSend can use custom subdomains for return-path, tracking, subscription management, and media. Always copy the exact hostnames from your domain page instead of assuming the defaults.

> [accordion] SPF record (Required)
>
> **Sender Policy Framework (SPF)** authorizes AhaSend to send emails on your domain's behalf.
>
> **Record Type:** `TXT`
> **Purpose:** Prevents email spoofing by specifying authorized sending servers
>
> ```text theme={null}
> Name: @ (or your subdomain)
> Type: TXT
> Value: v=spf1 include:spf.ahasend.com ~all
> ```
>
> > [!WARNING]
> >
> > If you already have an SPF record, **do not create a duplicate**. Instead, add `include:spf.ahasend.com` to your existing SPF record before the final mechanism (`~all` or `-all`).
>
> > [!NOTE]
> >
> > AhaSend can validate SPF through the return-path setup in some cases, but you should still publish the SPF record shown in your dashboard. It is the most portable and least surprising setup.

> [accordion] DKIM records (Required)
>
> **DomainKeys Identified Mail (DKIM)** cryptographically signs your emails to verify authenticity.
>
> **Record Type:** Usually `CNAME` for managed DNS, sometimes `TXT` for manual DNS
> **Purpose:** Prevents email tampering, confirms sender identity, and enables safe DKIM rotation on managed domains
>
> **Managed DNS (DNS v3):**
>
> ```text theme={null}
> Name: managed._domainkey.(your domain or subdomain)
> Type: CNAME
> Value: [AhaSend alias shown in dashboard]
>
> Name: managed2._domainkey.(your domain or subdomain)
> Type: CNAME
> Value: [AhaSend alias shown in dashboard]
> ```
>
> > [!NOTE]
> >
> > Managed DNS domains show two DKIM selectors: one active selector used for signing now, and one standby selector used for future rotation. Your domain can verify with the active selector alone, but publishing **both** DKIM CNAMEs up front is recommended so future DKIM rotation does not require another DNS change.
>
> **Manual DNS:**
>
> ```text theme={null}
> Name: [selector]._domainkey.(your domain or subdomain)
> Type: TXT
> Value: [unique DKIM public key]
> ```
>
> > [!NOTE]
> >
> > If you are working with a legacy or explicitly manual domain, your dashboard will show a single DKIM TXT record instead of the managed CNAME-based setup.

> [accordion] DMARC record (Required)
>
> **Domain-based Message Authentication, Reporting and Conformance (DMARC)** provides policy guidance for email authentication failures.
>
> **Record Type:** `TXT`
> **Purpose:** Protects your domain from email spoofing and phishing attacks
>
> ```text theme={null}
> Name: _dmarc
> Type: TXT
> Value: v=DMARC1; p=quarantine; sp=none; adkim=r; aspf=r;
> ```
>
> > [!NOTE]
> >
> > This DMARC policy asks receiving servers to quarantine messages that fail DMARC. It has no `rua` tag and sends no aggregate reports. You can add your own `rua=mailto:reports@yourdomain.com` address to receive reports. If the domain already has a DMARC record, update that record instead of adding another. Check all services that send from the domain before enforcing a quarantine policy.
>
> > [!NOTE]
> >
> > **Subdomains inherit the root record.** If you add `mail.example.com`, the DNS check first looks for `_dmarc.mail.example.com`. If there is none, it looks for `_dmarc.example.com` and accepts that. You only need a DMARC record on the subdomain itself when you want a different policy or reporting address for it.

> [accordion] Return-Path record (Highly recommended)
>
> **Return-Path** specifies where bounce messages and delivery notifications should be sent.
>
> **Record Type:** `CNAME`
> **Purpose:** Improves deliverability by providing a communication channel for bounce handling and SPF alignment
>
> ```text theme={null}
> Name: [return-path subdomain].(your domain or subdomain)
> Type: CNAME
> Value: [value shown in dashboard]
> ```
>
> > [!TIP]
> >
> > While not strictly required for every setup, the return-path record is strongly recommended. It improves bounce handling and is part of the managed DNS flow for many domains.

> [accordion] Email tracking record (Optional)
>
> **Tracking Domain** ensures tracking URLs in your emails come from your domain instead of AhaSend's.
>
> **Record Type:** `CNAME`
> **Purpose:** Improves deliverability and maintains brand consistency for tracked links
>
> ```text theme={null}
> Name: [tracking subdomain].(your domain or subdomain)
> Type: CNAME
> Value: [value shown in dashboard]
> ```
>
> > [!NOTE]
> >
> > Email tracking is **disabled by default** and must be explicitly enabled in your account settings, even if you configure the tracking domain.

> [accordion] Subscription management record (Optional)
>
> **Subscription management domain** hosts unsubscribe and subscription management links on your own domain.
>
> **Record Type:** `CNAME`
> **Purpose:** Keeps subscription management links branded on your domain
>
> ```text theme={null}
> Name: [subscription subdomain].(your domain or subdomain)
> Type: CNAME
> Value: [value shown in dashboard]
> ```
>
> > [!NOTE]
> >
> > This record is optional, but recommended if you want subscription management URLs to use your own domain instead of an AhaSend hostname.

> [accordion] Media record (Optional)
>
> **Media domain** serves hosted media assets from your own domain.
>
> **Record Type:** `CNAME`
> **Purpose:** Keeps hosted assets and media URLs branded on your domain
>
> ```text theme={null}
> Name: [media subdomain].(your domain or subdomain)
> Type: CNAME
> Value: [value shown in dashboard]
> ```
>
> > [!NOTE]
> >
> > This record is optional and mainly useful if you use AhaSend-hosted assets or want a consistent branded media hostname.

> [accordion] MX record (Recommended)
>
> **Mail Exchanger (MX)** specifies the mail server responsible for receiving emails for your domain.
>
> **Record Type:** `MX`
> **Purpose:** Required for receiving emails, recommended for better sending reputation
>
> ```text theme={null}
> Name: @ (or your subdomain)
> Type: MX
> Priority: 10
> Value: [value shown in dashboard]
> ```
>
> > [!NOTE]
> >
> > While not required for sending emails, some receiving servers penalize domains without MX records. Adding this record improves overall deliverability.

**3. Wait for DNS propagation**

DNS changes can take time to propagate across the internet:

* **Typical time:** 5-30 minutes
* **Maximum time:** Up to 48 hours
* **Check status:** Use online DNS checkers to verify your records are live

> [!TIP]
>
> **Pro tip:** Use tools like [DNS Checker](https://dnschecker.org/) or [What's My DNS](https://www.whatsmydns.net/) to verify your records have propagated globally.

**4. Verify your domain**

Once your DNS records are live, verify your domain in AhaSend:

1. **Return to your domain details page** in the dashboard
2. **Click "Check DNS"** to run verification
3. **Wait for confirmation** - this usually takes just a few seconds
4. **Look for the green checkmarks** next to each record type

> [!TIP]
>
> **Success!** When SPF, DKIM, and DMARC show as valid, your domain is ready to send emails.

> [!NOTE]
>
> On managed DNS domains, you may see a second DKIM selector that is marked as standby or not currently required. That is expected. Publishing it anyway is recommended so DKIM rotation can happen without a future DNS update.

> [!WARNING]
>
> If verification fails, double-check that:
>
> * All DNS records are added exactly as shown
> * DNS changes have had time to propagate
> * You don't have conflicting DNS records
> * You didn't create a second SPF TXT record
> * You published the DKIM record type shown by AhaSend (`CNAME` for managed DNS, `TXT` for manual DNS)

## DNS provider guides

Choose your authoritative DNS provider for record names and setup steps.

> [card] [Cloudflare](https://ahasend.com/docs/dns/cloudflare.md)

> [card] [GoDaddy](https://ahasend.com/docs/dns/godaddy.md)

> [card] [Namecheap](https://ahasend.com/docs/dns/namecheap.md)

> [card] [Route 53](https://ahasend.com/docs/dns/route-53.md)

> [card] [Hetzner](https://ahasend.com/docs/dns/hetzner.md)

> [card] [IONOS](https://ahasend.com/docs/dns/ionos.md)

> [card] [STRATO](https://ahasend.com/docs/dns/strato.md)

> [card] [TransIP](https://ahasend.com/docs/dns/transip.md)

> [card] [OVHcloud](https://ahasend.com/docs/dns/ovh.md)

> [card] [Squarespace](https://ahasend.com/docs/dns/squarespace.md)

> [card] [Vercel](https://ahasend.com/docs/dns/vercel.md)

## How do I manage domains through the API?

For programmatic domain management, use our comprehensive Domains API:

> [card] [Create domain](https://ahasend.com/docs/api-reference/domains/create-domain.md)
>
> Add new domains programmatically

> [card] [List domains](https://ahasend.com/docs/api-reference/domains/get-domains.md)
>
> Retrieve all your configured domains

> [card] [Get domain details](https://ahasend.com/docs/api-reference/domains/get-domain.md)
>
> Check domain verification status

> [card] [Delete domain](https://ahasend.com/docs/api-reference/domains/delete-domain.md)
>
> Remove domains from your account

> [!NOTE]
>
> API v2 also supports updating domain DNS settings such as tracking, return-path, subscription, media, and DKIM rotation interval, as well as requesting a DNS check for an existing domain.

## Why is my domain not verified?

Most records verify within minutes. DNS changes can take up to 48 hours to propagate. After a domain is added or verified, allow up to 2 minutes for the SMTP configuration to refresh if you see `556 Invalid account or domain`.

> [accordion] DNS records not verifying
>
> **Common causes and solutions:**
>
> * **Wait longer:** DNS propagation can take up to 48 hours
> * **Check record values:** Ensure exact copy-paste from dashboard (no extra spaces)
> * **Verify record type:** SPF and DMARC use TXT; DKIM can be `CNAME` or `TXT` depending on your domain mode
> * **Remove duplicates:** Don't create multiple SPF records
> * **Check with DNS tools:** Use online DNS checkers to verify records are live

> [accordion] Existing SPF record conflicts
>
> **If you already have an SPF record:**
>
> 1. **Don't create a duplicate** - domains can only have one SPF record
> 2. **Modify your existing record** by adding `include:spf.ahasend.com`
> 3. **Place it before the final mechanism** (`~all` or `-all`)
>
> Example:
>
> ```text theme={null}
> OLD: v=spf1 include:_spf.google.com ~all
> NEW: v=spf1 include:_spf.google.com include:spf.ahasend.com ~all
> ```

> [accordion] Why do I see two DKIM records?
>
> **Managed DNS domains use two DKIM selectors.**
>
> * **Active selector:** Used for signing mail right now and required for verification
> * **Standby selector:** Reserved for the next DKIM rotation
>
> Publishing both DKIM CNAMEs from the start is recommended. It lets AhaSend rotate keys later without requiring another DNS change on your side.

> [accordion] Subdomain vs root domain
>
> **Understanding the difference:**
>
> * **Root domain:** `yourcompany.com` (affects all subdomains)
> * **Subdomain:** `email.yourcompany.com` (isolated setup)
>
> **For subdomains:** Add the SPF, DKIM, return-path and tracking records at the subdomain itself. DMARC is the exception: a record at the root domain also counts, because the DNS check falls back to `_dmarc.<root domain>` when the subdomain has none.
>
> Records like return-path, tracking, subscription management, and media are usually additional subdomains under the domain you add to AhaSend.

> [accordion] Still having issues?
>
> **We're here to help:**
>
> * **Check our [status page](https://status.ahasend.com)** for any ongoing DNS issues
> * **Contact support** at [support@ahasend.com](mailto:support@ahasend.com)
> * **Include your domain name** and specific error messages
> * **Attach screenshots** of your DNS configuration if helpful
>
> Our engineering team typically responds within a few hours!

## Why is sending paused on my domain?

AhaSend pauses sending from a marketing domain when too many recent emails from it bounced. The pause applies only to that domain:

* AhaSend refuses new email from the domain, through the API and through SMTP.
* Your other domains continue to send.
* AhaSend still delivers the email that it accepted before the pause.
* A campaign that sends from the domain is paused. After the pause is lifted, write to [support@ahasend.com](mailto:support@ahasend.com) to resume it.
* [Sandbox](https://ahasend.com/docs/send-api/sandbox.md) messages from the domain are still accepted.
* You cannot delete or rename the domain, and you cannot add its name to another account.

### How do I see that a domain is paused?

* **Dashboard:** the domain page shows the reason and what to do next. The domain list shows a **Paused** badge.
* **Email:** AhaSend sends an email to the owners and admins of the account. For a [sub-account](https://ahasend.com/docs/scale/sub-accounts.md#paused-domains), the owners and admins of the parent account also get the email.
* **API:** the [Domain object](https://ahasend.com/docs/api-reference/domains/get-domain.md) has the fields `paused`, `paused_at` and `pause_reason`. The reason `bounce_rate` means that too many recent emails from the domain bounced.
* **Send errors:** the [API](https://ahasend.com/docs/api-reference/errors.md#403-forbidden) returns HTTP 403, and [SMTP](https://ahasend.com/docs/smtp/errors.md) refuses the message with code `550 5.7.1`. Both give this text:

```text theme={null}
Sending from domain 'example.com' is paused. Check your dashboard for the reason.
```

### How do I get a pause lifted?

1. Fix the cause. For a high bounce rate, remove addresses that are not valid or old. Send only to people who asked for your email.
2. Reply to the pause email, or write to [support@ahasend.com](mailto:support@ahasend.com). AhaSend support lifts the pause.

For a sub-account, the parent account can also lift the pause. See [paused domains of sub-accounts](https://ahasend.com/docs/scale/sub-accounts.md#paused-domains).

A change of the [sending type](#sending-type) does not lift a pause. After the pause is lifted, AhaSend can refuse email from the domain for a few more minutes.

## What's next?

Once your domain is verified, you're ready to start sending emails:

> [card] [Send your first email](https://ahasend.com/docs/quickstart.md)
>
> Follow our quickstart guide to send emails via API or SMTP

> [card] [Create SMTP credentials](https://ahasend.com/docs/smtp/credentials.md)
>
> Generate credentials for your applications

> [card] [Create API keys](https://ahasend.com/docs/send-api/credentials.md)
>
> Track email delivery and engagement events

> [card] [Enable tracking](https://ahasend.com/docs/tracking/open-tracking.md)
>
> Monitor opens and clicks on your emails

> [!NOTE]
>
> **Domain setup complete?** Your domain is now ready to send emails through AhaSend. Test it out with our [quickstart guide](https://ahasend.com/docs/quickstart.md) to send your first email!

## Common domain questions

### Can I keep my existing SPF record?

Yes. Add `include:spf.ahasend.com` to the existing SPF record before its final `~all` or `-all` mechanism. Do not publish a second SPF record.

### Why are there two DKIM records?

Managed DNS uses one active key and one standby key so AhaSend can rotate signing keys. Publish both CNAMEs shown in your dashboard.

### How long does verification take?

Most records verify within minutes. DNS changes can take up to 48 hours to propagate. Check the DNS host, type and value if verification still fails.

### Should I use a subdomain?

Use a dedicated subdomain when you want to separate transactional sending from other mail on your main domain. Add and verify that subdomain in AhaSend.

## Domain, Delivery and Migration Guides

* [DNS provider guides](https://ahasend.com/docs/dns.md): record names and setup steps for Cloudflare, GoDaddy, Namecheap, Route 53, Hetzner, IONOS, STRATO, TransIP, OVHcloud, Squarespace and Vercel.
* [SPF, DKIM and DMARC](https://ahasend.com/docs/email-authentication.md): what each check proves and how domain alignment works.
* [Bounces and suppressions](https://ahasend.com/docs/bounces.md) and [SMTP error codes](https://ahasend.com/docs/smtp/errors.md): understand a failed send and choose the next step.
* [Deliverability best practices](https://ahasend.com/docs/deliverability.md): sender reputation, warm-up, sending subdomains, Gmail and Yahoo requirements, and one-click unsubscribe.
* Migrate from [SendGrid](https://ahasend.com/docs/migrations/sendgrid.md), [Mailgun](https://ahasend.com/docs/migrations/mailgun.md), [Postmark](https://ahasend.com/docs/migrations/postmark.md), [Resend](https://ahasend.com/docs/migrations/resend.md) or [Amazon SES](https://ahasend.com/docs/migrations/amazon-ses.md), including suppression imports.
* [Troubleshooting and FAQ](https://ahasend.com/docs/troubleshooting.md): domain checks, missing messages, port 465, permission errors and blocked recipients.
* [Email glossary](https://ahasend.com/docs/glossary.md) and [credential security](https://ahasend.com/docs/security.md): definitions and practical steps to protect your account.

## Related guides

* [Account quickstart](https://ahasend.com/docs/quickstart.md), [Domain API](https://ahasend.com/docs/api-reference/domains/create-domain.md), [Domain CLI](https://ahasend.com/docs/cli/commands/domains.md).
* [DNS whitelabel](https://ahasend.com/docs/scale/dns-whitelabel.md), [Send-only API keys](https://ahasend.com/docs/send-api/credentials.md), [Inbound MX setup](https://ahasend.com/docs/integrations/routing.md).
* [Plans and limits](https://ahasend.com/docs/facts.md), [Tracking setup](https://ahasend.com/docs/tracking/open-tracking.md).


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