From 96bbd3cb3b4014665ec9c02ed4ff9592e9ca5251 Mon Sep 17 00:00:00 2001 From: mikesteroonie Date: Mon, 6 Jul 2026 23:15:39 -0700 Subject: [PATCH] fix: cname mentions --- fern/pages/guides/domains/custom-domains.mdx | 36 +++++++++++++++---- .../knowledge-base/custom-domain-setup.mdx | 12 +++++-- fern/pages/knowledge-base/dns-cloudflare.mdx | 27 +++++++------- fern/pages/knowledge-base/dns-godaddy.mdx | 16 +++++---- fern/pages/knowledge-base/dns-namecheap.mdx | 16 +++++---- fern/pages/knowledge-base/dns-route53.mdx | 20 ++++++----- .../knowledge-base/domain-not-verifying.mdx | 17 +++++---- .../knowledge-base/mx-record-conflicts.mdx | 10 +++--- fern/pages/knowledge-base/spf-dkim-dmarc.mdx | 12 ++++--- .../resources/security/email-protocols.mdx | 12 ++++--- 10 files changed, 113 insertions(+), 65 deletions(-) diff --git a/fern/pages/guides/domains/custom-domains.mdx b/fern/pages/guides/domains/custom-domains.mdx index a612358d..ec82a4d7 100644 --- a/fern/pages/guides/domains/custom-domains.mdx +++ b/fern/pages/guides/domains/custom-domains.mdx @@ -245,6 +245,10 @@ A BIND zone file is a text file that contains DNS resource records in a standard Below are detailed instructions for AWS Route53, CloudFlare, and Namecheap. The instructions vary depending on whether you're using the AgentMail Console or the API directly. + + As of July 6, 2026, newly created domains authenticate DKIM with TXT selector records. Older domains may still show DKIM CNAME records. Always publish the exact `type`, `name`, and `value` returned by the AgentMail Console or API. + + If you created your domain through the [AgentMail Console](https://console.agentmail.to), the DNS records are displayed in a simplified format that's ready for copy-paste into your DNS provider. @@ -253,10 +257,15 @@ Below are detailed instructions for AWS Route53, CloudFlare, and Namecheap. The In the dashboard (**DNS > Records**), click **"Add record"**. - - **TXT (DMARC/SPF/DKIM):** + - **TXT (DMARC/SPF/DKIM for new domains):** - **Name:** Copy the **Name** value directly from the console. - **Content:** Copy the **Value** from the console. + - **CNAME (legacy DKIM only):** + - **Name:** Copy the **Name** value directly from the console. + - **Target:** Copy the **Value** from the console. + - **Proxy status:** Set to **DNS only**. + - **MX:** - **Name:** Enter `@` to apply the record to the root domain. - **Mail server:** Copy the **Value** from the console. @@ -267,10 +276,14 @@ Below are detailed instructions for AWS Route53, CloudFlare, and Namecheap. The In your hosted zone, click **"Create record"**. - - **TXT (DMARC/SPF):** - - **Record name:** Copy the **Name** value directly from the console (e.g., `_dmarc` or `mail` or `agentmail._domainkey`). + - **TXT (DMARC/SPF/DKIM for new domains):** + - **Record name:** Copy the **Name** value directly from the console (e.g., `_dmarc` or `mail` or `selector._domainkey`). - **Value:** Copy the **Value** from the console, ensuring it is enclosed in quotes. + - **CNAME (legacy DKIM only):** + - **Record name:** Copy the **Name** value directly from the console. + - **Value:** Copy the **Value** from the console without quotes. + **AWS Route 53 has a 255 character maximum per string.** It will get angry at the DKIM record since it is longer than 255 chars (we use more secure encryption key so we get better deliverability with Gmail!) @@ -306,10 +319,15 @@ Below are detailed instructions for AWS Route53, CloudFlare, and Namecheap. The In the dashboard (**DNS > Records**), click **"Add record"**. - - **TXT (DMARC/SPF/DKIM):** + - **TXT (DMARC/SPF/DKIM for new domains):** - **Name:** Enter the part of the `name` before your root domain (e.g. `_dmarc`). - **Content:** Copy paste the `value` from the API response. + - **CNAME (legacy DKIM only):** + - **Name:** Enter the part of the `name` before your root domain. + - **Target:** Copy paste the `value` from the API response. + - **Proxy status:** Set to **DNS only**. + - **MX:** - **Name:** Enter the part of the name before your root domain - **Mail server:** Enter the `value` from the API. @@ -319,9 +337,13 @@ Below are detailed instructions for AWS Route53, CloudFlare, and Namecheap. The In your hosted zone, click **"Create record"**. - - **TXT (DMARC/SPF/DKIM):** - - **Record name:** Enter the part of the `name` before your root domain (e.g., `_dmarc` for a `name` of `_dmarc.domain.com`, or `mail` for a `name` of `mail.domain.com`, or `agentmail._domainkey` for a `name` of agentmail._domainkey.agents.com). - - **Value:** Can copy paste the`value` from the API, ensuring it is enclosed in quotes. + - **TXT (DMARC/SPF/DKIM for new domains):** + - **Record name:** Enter the part of the `name` before your root domain (e.g., `_dmarc` for a `name` of `_dmarc.domain.com`, or `mail` for a `name` of `mail.domain.com`, or `selector._domainkey` for a `name` of `selector._domainkey.agents.com`). + - **Value:** Copy paste the `value` from the API, ensuring it is enclosed in quotes. + + - **CNAME (legacy DKIM only):** + - **Record name:** Enter the part of the `name` before your root domain. + - **Value:** Copy paste the `value` from the API without quotes. **AWS Route 53 has a 255 character maximum per string.** It will get angry at the DKIM record since it is longer than 255 chars (we use more secure encryption key so we get better deliverability with Gmail!) diff --git a/fern/pages/knowledge-base/custom-domain-setup.mdx b/fern/pages/knowledge-base/custom-domain-setup.mdx index a9efd157..b0e199ce 100644 --- a/fern/pages/knowledge-base/custom-domain-setup.mdx +++ b/fern/pages/knowledge-base/custom-domain-setup.mdx @@ -26,10 +26,10 @@ import { AgentMailClient } from "agentmail"; const client = new AgentMailClient({ apiKey: "am_..." }); -// Add your domain +// add your domain const domain = await client.domains.create("yourcompany.com"); -// View the DNS records you need to add +// view the DNS records you need to add for (const record of domain.records) { console.log(`${record.type} | ${record.name} | ${record.value}`); } @@ -42,9 +42,15 @@ The response includes all the DNS records you need to add at your DNS provider. | Record type | Purpose | | --- | --- | | TXT (SPF) | Authorizes AgentMail to send email on behalf of your domain | -| CNAME (DKIM) | Cryptographic signature proving emails are authentically from you | +| TXT (DKIM) | Publishes the custom DKIM selector key used to sign your email | +| CNAME (DKIM) | Legacy DKIM record type for older domains | +| TXT (DMARC) | Defines how receivers handle authentication failures | | MX | Routes incoming mail for your domain to AgentMail | + +As of July 6, 2026, newly created domains authenticate DKIM with TXT selector records. Older domains may still show DKIM CNAME records. Always add the exact record type, name, and value shown in the AgentMail Console or API response. + + The MX record is only needed if you want to **receive** emails on your custom domain. If you only need to send, you can skip the MX record. diff --git a/fern/pages/knowledge-base/dns-cloudflare.mdx b/fern/pages/knowledge-base/dns-cloudflare.mdx index d02d34d8..ffd82572 100644 --- a/fern/pages/knowledge-base/dns-cloudflare.mdx +++ b/fern/pages/knowledge-base/dns-cloudflare.mdx @@ -24,21 +24,20 @@ slug: knowledge-base/dns-cloudflare If you already have an SPF record for your domain, do **not** create a second one. Instead, add `include:agentmail.to` to your existing SPF record. Having multiple SPF records on the same domain will cause authentication failures. -## Adding a CNAME Record (DKIM) +## Adding a DKIM Record | Field | Value | | --- | --- | -| Type | `CNAME` | -| Name | The DKIM selector from AgentMail (e.g., `agentmail._domainkey`) | -| Target | The DKIM target from AgentMail | -| Proxy status | **DNS only** (grey cloud) | +| Type | `TXT` for new domains; `CNAME` for legacy domains if AgentMail shows CNAME | +| Name | The DKIM selector host from AgentMail (e.g., `selector._domainkey`) | +| Content or Target | The DKIM value from AgentMail | | TTL | `Auto` | - -DKIM CNAME records **must** have Cloudflare proxy disabled (grey cloud icon). If the orange cloud proxy is enabled, Cloudflare replaces the CNAME with its own proxy addresses, which prevents email servers from looking up your DKIM public key. This will cause DKIM verification to fail. If you see Error 1004 when saving, confirm that proxy is set to DNS only. - +Cloudflare automatically strips your domain from the Name field. Enter only the selector host portion (e.g., `selector._domainkey`), not the full `selector._domainkey.yourdomain.com`. -Cloudflare automatically strips your domain from the Name field. Enter only the subdomain portion (e.g., `agentmail._domainkey`), not the full `agentmail._domainkey.yourdomain.com`. + +As of July 6, 2026, newly created domains authenticate DKIM with TXT selector records. Older domains may still show DKIM CNAME records. Add the exact type and value shown in AgentMail. + ## Adding an MX Record (Receiving) @@ -60,12 +59,10 @@ Cloudflare DNS typically propagates within **1 to 5 minutes**, making it one of ## Common Cloudflare Issues -- **Proxy must be off for CNAME records:** The orange cloud (Proxied) means traffic goes through Cloudflare's reverse proxy, which only handles HTTP/HTTPS. Email-related CNAME records like DKIM need direct DNS resolution and must be set to DNS only (grey cloud). If you forget, DKIM verification will silently fail. - -- **CNAME flattening at root:** Cloudflare automatically flattens CNAME records at the zone apex (root domain), returning A/AAAA records instead of the CNAME. This generally does not affect DKIM setup since the selector (e.g., `agentmail._domainkey`) is a subdomain. However, if you encounter unexpected behavior, consider using a subdomain for sending. - - **Existing SPF record:** If you already have a TXT record starting with `v=spf1`, add `include:agentmail.to` before the `~all` or `-all` in that existing record. Do not create a second SPF TXT record. -- **Error 1004 when adding CNAME:** This error typically means the record cannot be proxied. Switch the proxy status to DNS only (grey cloud) and try saving again. +- **Legacy DKIM CNAME proxy:** If AgentMail shows a DKIM CNAME record, set the proxy status to **DNS only** (grey cloud). Proxied CNAME records will break DKIM verification. + +- **Duplicate TXT values:** Cloudflare lets you add TXT records with the same name, but duplicate SPF or stale DKIM selector records can make verification fail. Keep only the current values AgentMail provides for each host. -- **Name field auto-strips domain:** Cloudflare removes the domain portion from the Name field automatically. If your DKIM selector is `agentmail._domainkey`, enter just that. Do not enter `agentmail._domainkey.yourdomain.com`, or the record will be created incorrectly. +- **Name field auto-strips domain:** Cloudflare removes the domain portion from the Name field automatically. If your DKIM selector is `selector._domainkey`, enter just that. Do not enter `selector._domainkey.yourdomain.com`, or the record will be created incorrectly. diff --git a/fern/pages/knowledge-base/dns-godaddy.mdx b/fern/pages/knowledge-base/dns-godaddy.mdx index 0b128d09..0bb8c6a5 100644 --- a/fern/pages/knowledge-base/dns-godaddy.mdx +++ b/fern/pages/knowledge-base/dns-godaddy.mdx @@ -24,19 +24,23 @@ slug: knowledge-base/dns-godaddy GoDaddy automatically wraps TXT values in double quotes, so do **not** add your own quotes around the value. If you do, the record will end up double-quoted and fail validation. Also, if you already have an SPF record, add `include:agentmail.to` to the existing record rather than creating a second one. -## Adding a CNAME Record (DKIM) +## Adding a DKIM Record | Field | Value | | --- | --- | -| Type | `CNAME` | -| Name | The DKIM selector from AgentMail (e.g., `agentmail._domainkey`) | -| Value | The DKIM target from AgentMail | +| Type | `TXT` for new domains; `CNAME` for legacy domains if AgentMail shows CNAME | +| Name | The DKIM selector host from AgentMail (e.g., `selector._domainkey`) | +| Value | The DKIM value from AgentMail | | TTL | `1 Hour` | -GoDaddy automatically appends your domain to the Name field. Enter only the subdomain portion. For example, enter `agentmail._domainkey`, not `agentmail._domainkey.yourdomain.com`. +GoDaddy automatically appends your domain to the Name field. Enter only the selector host portion. For example, enter `selector._domainkey`, not `selector._domainkey.yourdomain.com`. + +As of July 6, 2026, newly created domains authenticate DKIM with TXT selector records. Older domains may still show DKIM CNAME records. Add the exact type and value shown in AgentMail. + + ## Adding an MX Record (Receiving) | Field | Value | @@ -59,7 +63,7 @@ GoDaddy DNS typically propagates within **15 to 30 minutes**, but it can occasio - **Double-quoted TXT values:** GoDaddy adds quotes around TXT records automatically. If you paste a value that already includes quotes, the final record will be double-quoted and will fail. Paste the raw value without quotes. -- **Name field auto-appends domain:** GoDaddy appends your domain to the Name field. Enter only the subdomain portion (e.g., `agentmail._domainkey`). If you enter the full hostname, it will be duplicated as `agentmail._domainkey.yourdomain.com.yourdomain.com`. +- **Name field auto-appends domain:** GoDaddy appends your domain to the Name field. Enter only the selector host portion (e.g., `selector._domainkey`). If you enter the full hostname, it will be duplicated as `selector._domainkey.yourdomain.com.yourdomain.com`. - **Existing SPF record:** If you already have a TXT record starting with `v=spf1`, add `include:agentmail.to` before the `~all` or `-all` in that existing record. Do not create a second SPF TXT record. diff --git a/fern/pages/knowledge-base/dns-namecheap.mdx b/fern/pages/knowledge-base/dns-namecheap.mdx index 0e41f72b..a9dbabb7 100644 --- a/fern/pages/knowledge-base/dns-namecheap.mdx +++ b/fern/pages/knowledge-base/dns-namecheap.mdx @@ -28,19 +28,23 @@ Make sure your domain is using **Namecheap BasicDNS** or **Namecheap PremiumDNS* If you already have an SPF record for your domain, do **not** create a second one. Instead, add `include:agentmail.to` to your existing SPF record. Having multiple SPF records will cause validation failures. -## Adding a CNAME Record (DKIM) +## Adding a DKIM Record | Field | Value | | --- | --- | -| Type | `CNAME Record` | -| Host | The DKIM selector from AgentMail (e.g., `agentmail._domainkey`) | -| Value | The DKIM target from AgentMail | +| Type | `TXT Record` for new domains; `CNAME Record` for legacy domains if AgentMail shows CNAME | +| Host | The DKIM selector host from AgentMail (e.g., `selector._domainkey`) | +| Value | The DKIM value from AgentMail | | TTL | `Automatic` | -**Namecheap automatically appends your domain to the Host field.** Enter only the subdomain portion. For example, enter `agentmail._domainkey`, not `agentmail._domainkey.yourdomain.com`. +**Namecheap automatically appends your domain to the Host field.** Enter only the selector host portion. For example, enter `selector._domainkey`, not `selector._domainkey.yourdomain.com`. + +As of July 6, 2026, newly created domains authenticate DKIM with TXT selector records. Older domains may still show DKIM CNAME records. Add the exact type and value shown in AgentMail. + + ## Adding an MX Record (Receiving) | Field | Value | @@ -61,7 +65,7 @@ Namecheap DNS typically propagates within **15 to 30 minutes**, but in some case ## Common Namecheap Issues -- **Host field auto-appends domain:** Namecheap adds your domain automatically. If your DKIM selector is `agentmail._domainkey`, enter just that, not the full `agentmail._domainkey.yourdomain.com`. If you enter the full value, the actual record will end up as `agentmail._domainkey.yourdomain.com.yourdomain.com`. +- **Host field auto-appends domain:** Namecheap adds your domain automatically. If your DKIM selector is `selector._domainkey`, enter just that, not the full `selector._domainkey.yourdomain.com`. If you enter the full value, the actual record will end up as `selector._domainkey.yourdomain.com.yourdomain.com`. - **Existing SPF record:** If you already have a TXT record starting with `v=spf1`, add `include:agentmail.to` before the `~all` or `-all` in that existing record. Do not create a second SPF TXT record. diff --git a/fern/pages/knowledge-base/dns-route53.mdx b/fern/pages/knowledge-base/dns-route53.mdx index 59fa3a7a..237165b9 100644 --- a/fern/pages/knowledge-base/dns-route53.mdx +++ b/fern/pages/knowledge-base/dns-route53.mdx @@ -28,16 +28,20 @@ If your domain is registered with a different registrar but uses Route 53 for DN Route 53 requires TXT values to be **wrapped in double quotes**. If you omit the quotes, the record will fail validation. Also, if you already have an SPF record, add `include:agentmail.to` to the existing record rather than creating a second one. Multiple SPF records on the same domain will cause authentication failures. -## Adding a CNAME Record (DKIM) +## Adding a DKIM Record | Field | Value | | --- | --- | -| Record name | The DKIM selector from AgentMail (e.g., `agentmail._domainkey`) | -| Record type | `CNAME` | -| Value | The DKIM target from AgentMail | +| Record name | The DKIM selector host from AgentMail (e.g., `selector._domainkey`) | +| Record type | `TXT` for new domains; `CNAME` for legacy domains if AgentMail shows CNAME | +| Value | The DKIM value from AgentMail | | TTL | `300` | -CNAME values should **not** be wrapped in quotes. +Route 53 requires TXT values to be **wrapped in double quotes**. CNAME values should not be wrapped in quotes. If a DKIM TXT value is longer than 255 characters, split it into adjacent quoted strings within one TXT record. + + +As of July 6, 2026, newly created domains authenticate DKIM with TXT selector records. Older domains may still show DKIM CNAME records. Add the exact type and value shown in AgentMail. + ## Adding an MX Record (Receiving) @@ -60,9 +64,7 @@ Route 53 name servers typically pick up changes within **60 seconds**, but full ## Common Route 53 Issues -- **TXT records must be quoted:** Unlike most DNS providers, Route 53 requires double quotes around TXT record values. If your SPF or other TXT records are missing quotes, they won't validate. - -- **CNAME at root domain:** Route 53 does not allow CNAME records on the root domain (zone apex). If you need to set up DKIM, the selector (e.g., `agentmail._domainkey`) is a subdomain, so this is typically not an issue. However, if you run into conflicts, consider using a subdomain for sending. +- **TXT records must be quoted:** Unlike most DNS providers, Route 53 requires double quotes around TXT record values. If your SPF, DKIM, or DMARC TXT records are missing quotes, they won't validate. - **Existing SPF record:** If you already have a TXT record starting with `v=spf1`, add `include:agentmail.to` before the `~all` or `-all` in that existing record. Do not create a second SPF TXT record. @@ -70,7 +72,7 @@ Route 53 name servers typically pick up changes within **60 seconds**, but full - **Multiple values in one record:** Route 53 lets you add multiple values to a single record. If you need to add a second MX entry, add it as a new line in the same MX record rather than creating a separate record. -- **DKIM TXT record too long (CharacterStringTooLong error):** If your DKIM record is provided as a TXT value (rather than a CNAME), the DKIM public key is often longer than the 255-character limit that Route 53 enforces per string segment. You will see an error like `CharacterStringTooLong (Value is too long)`. To fix this, split the value into two quoted strings within a single record. The split point should be near the middle of the `p=` value. The two quoted strings must have **no space and no line break** between the closing and opening quotes. For example: +- **DKIM TXT record too long (CharacterStringTooLong error):** DKIM public keys are often longer than the 255-character limit that Route 53 enforces per string segment. You will see an error like `CharacterStringTooLong (Value is too long)`. To fix this, split the value into two quoted strings within a single record. The split point should be near the middle of the `p=` value. The two quoted strings must have **no space and no line break** between the closing and opening quotes. For example: ``` "v=DKIM1; k=rsa; p=MIIBIjANBgkqhki...firsthalf""secondhalf...wIDAQAB" diff --git a/fern/pages/knowledge-base/domain-not-verifying.mdx b/fern/pages/knowledge-base/domain-not-verifying.mdx index 4d39b883..aebf8075 100644 --- a/fern/pages/knowledge-base/domain-not-verifying.mdx +++ b/fern/pages/knowledge-base/domain-not-verifying.mdx @@ -21,16 +21,21 @@ DNS changes can take anywhere from a few minutes to 48 hours to propagate, depen ## 2. Wrong record type -Make sure you are adding the correct record type as specified by AgentMail. A common mistake is adding a TXT record where a CNAME is needed, or vice versa. +Make sure you are adding the exact record type AgentMail provides. AgentMail uses TXT records for SPF, DMARC, and new DKIM selector verification, plus MX records when the domain receives mail. Older domains may still use DKIM CNAME records. | Record | Correct type | | --- | --- | | SPF | TXT | -| DKIM | CNAME | +| DKIM | TXT for domains created on or after July 6, 2026; CNAME for legacy domains if shown | +| DMARC | TXT | | MX | MX | Double check the records in the AgentMail Console under **Domains** to see the exact type and value required. + +As of July 6, 2026, new DKIM records are authenticated with custom TXT selector records instead of CNAME records. For existing domains, do not convert a working CNAME unless AgentMail provides replacement TXT records. + + ## 3. Extra quotes or spaces Some DNS providers (like GoDaddy) automatically wrap TXT values in quotes. If you paste a value that already includes quotes, you end up with double-quoted values that fail verification. @@ -41,15 +46,15 @@ Route 53 is the opposite: it **requires** quotes around TXT values. If you omit ## 4. Domain name auto-appended -Many DNS providers (Namecheap, GoDaddy, Cloudflare) automatically append your domain to the record name. If you enter `agentmail._domainkey.yourcompany.com` instead of just `agentmail._domainkey`, the actual record becomes `agentmail._domainkey.yourcompany.com.yourcompany.com`, which will fail. +Many DNS providers (Namecheap, GoDaddy, Cloudflare) automatically append your domain to the record name. If AgentMail provides a DKIM selector host like `selector._domainkey.yourcompany.com`, entering the full hostname may create `selector._domainkey.yourcompany.com.yourcompany.com`, which will fail. -**What to do:** Enter only the subdomain portion. For example, enter `agentmail._domainkey`, not the full hostname. +**What to do:** Enter only the host portion your DNS provider expects. For example, if your provider appends the domain automatically, enter `selector._domainkey`, not the full hostname. ## 5. Conflicting records -CNAME records cannot coexist with other record types on the same name. If you have an existing TXT or A record on the same subdomain as your DKIM CNAME, verification may fail. +Some DNS providers reject multiple records with the same host and type, and multiple SPF records on one host will fail authentication. If an old DKIM record or another stale record exists at the same selector host, it can also prevent the new TXT selector record from validating. -**What to do:** Check your DNS dashboard for conflicts on the DKIM selector subdomain and remove any conflicting records. +**What to do:** Check your DNS dashboard for conflicts on the DKIM selector host. Keep the current DKIM record from AgentMail and remove stale or duplicate records that use the same host. ## 6. Nameservers pointing elsewhere diff --git a/fern/pages/knowledge-base/mx-record-conflicts.mdx b/fern/pages/knowledge-base/mx-record-conflicts.mdx index 97c05f58..bf95b347 100644 --- a/fern/pages/knowledge-base/mx-record-conflicts.mdx +++ b/fern/pages/knowledge-base/mx-record-conflicts.mdx @@ -26,10 +26,10 @@ import { AgentMailClient } from "agentmail"; const client = new AgentMailClient({ apiKey: "am_..." }); -// Use a subdomain to avoid MX conflicts +// use a subdomain to avoid MX conflicts const domain = await client.domains.create("agents.yourcompany.com"); -// Create inboxes on the subdomain +// create inboxes on the subdomain const inbox = await client.inboxes.create({ username: "support", domain: "agents.yourcompany.com", @@ -48,7 +48,7 @@ The setup above puts all your agents on one subdomain. If you instead want inbox Yes, but only in these scenarios: -**Sending only (no receiving):** If you only need AgentMail to send emails from your root domain, you only need SPF (TXT) and DKIM (CNAME) records. These do not conflict with existing MX records, so your Gmail or Outlook inbound mail is unaffected. +**Sending only (no receiving):** If you only need AgentMail to send emails from your root domain, you only need SPF and DMARC TXT records plus the DKIM record AgentMail provides. New domains use DKIM TXT records as of July 6, 2026, while legacy domains may still use DKIM CNAME records. These do not conflict with existing MX records, so your Gmail or Outlook inbound mail is unaffected. **Full AgentMail (sending and receiving):** If you want AgentMail to also receive emails on your root domain, you would need to replace your existing MX records with AgentMail's. This means all incoming mail for that domain routes to AgentMail instead of Gmail or Outlook. Only do this if you want AgentMail to handle all inbound email for that domain. @@ -68,9 +68,11 @@ yourcompany.com MX 10 aspmx.l.google.com. yourcompany.com MX 20 alt1.aspmx.l.google.com. agents.yourcompany.com MX 10 inbound.agentmail.to. agents.yourcompany.com TXT v=spf1 include:agentmail.to ~all -agents.yourcompany.com CNAME (DKIM record from AgentMail) +selector._domainkey.agents.yourcompany.com TXT (DKIM value from AgentMail) ``` +Older AgentMail domains may show a DKIM CNAME instead of the TXT example above. Use whichever record type AgentMail returns for your domain. + Your team's email continues to flow through Gmail. Agent emails go through AgentMail. Clean separation with no conflicts. ## Common subdomain choices diff --git a/fern/pages/knowledge-base/spf-dkim-dmarc.mdx b/fern/pages/knowledge-base/spf-dkim-dmarc.mdx index de66c5b3..e783ed66 100644 --- a/fern/pages/knowledge-base/spf-dkim-dmarc.mdx +++ b/fern/pages/knowledge-base/spf-dkim-dmarc.mdx @@ -36,18 +36,22 @@ v=spf1 include:_spf.google.com include:agentmail.to ~all ## DKIM (DomainKeys Identified Mail) -DKIM adds a cryptographic signature to every email, proving it was sent by an authorized server and was not tampered with in transit. It uses CNAME records that point to signing keys managed by AgentMail. +DKIM adds a cryptographic signature to every email, proving it was sent by an authorized server and was not tampered with in transit. For newly created domains, AgentMail uses a custom TXT record under a DKIM selector host so your domain publishes the exact key used for signing. + + +As of July 6, 2026, newly created domains authenticate DKIM with TXT selector records. Older domains may still use DKIM CNAME records. Always publish the record type shown in the AgentMail Console or API response. + **What AgentMail provides:** ```text -CNAME | agentmail._domainkey | (target provided by AgentMail) +TXT | selector._domainkey | v=DKIM1; k=rsa; p=(public key provided by AgentMail) ``` -AgentMail manages the signing keys automatically. Once you add the CNAME records, every email from your domain is signed with no ongoing maintenance required. +AgentMail provides the selector name and public key value for your domain. Once you add the DKIM record, every email from your domain is signed with the matching private key. If your domain still shows a CNAME record, keep using that CNAME value until AgentMail provides a TXT replacement. -If you use Cloudflare, make sure the CNAME proxy status is set to **DNS only** (grey cloud). Proxied CNAME records will break DKIM verification. +Use the exact selector host shown in the AgentMail Console or API response. Many DNS providers append your domain automatically, so you may need to enter only the `selector._domainkey` portion. ## DMARC (Domain-based Message Authentication, Reporting, and Conformance) diff --git a/fern/pages/resources/security/email-protocols.mdx b/fern/pages/resources/security/email-protocols.mdx index 22be70ce..e7ce7c6e 100644 --- a/fern/pages/resources/security/email-protocols.mdx +++ b/fern/pages/resources/security/email-protocols.mdx @@ -34,15 +34,17 @@ Your DNS records are simply the way you tell the world that you've authorized us - **What it is:** DKIM is like a digital signature for your emails. This signature proves two things: that the email actually came from your domain and that its content hasn't been messed with with in transit from you to who you are trying to send to. - **How it works:** We generate a unique, secure key for your domain. When we send an email, we "sign" it with this key. The public part of that key is published in your DNS. Receiving servers use this public key to verify the signature. -These are a couple of records we might ask you to add. +This is the kind of record we might ask you to add. - **Your Records:** ```text - CNAME | b4w..._domainkey.payment... | b4w...dkim.agentmail.com - CNAME | 32c..._domainkey.payment... | 32c...dkim.agentmail.com - CNAME | xl4..._domainkey.payment... | xl4...dkim.agentmail.com + TXT | b4w..._domainkey.payment... | v=DKIM1; k=rsa; p=MIIB... ``` - Instead of having you publish the raw key (which can be messy and needs to be rotated), we use `CNAME` records. These records act as aliases, pointing a specific address on your domain to one managed by us. This allows us to manage the security of your signing keys automatically without you ever needing to change them. + AgentMail gives you a custom DKIM selector host and TXT value. Publishing the key directly at that selector gives receiving servers a precise public key to verify signatures from your domain. + + +As of July 6, 2026, newly created domains use DKIM TXT records. Older domains may still use DKIM CNAME records, so always publish the exact record type AgentMail returns. + ### DMARC: Domain-based Message Authentication, Reporting, and Conformance