Custom inbound domains

Custom domains let your customers email you on your own branded address — for example [email protected] or [email protected] — instead of the default [email protected] style address Chatlane gives every new inbox. Replies still land in the right Chatlane inbox; the customer just sees your brand on every reply chain.

This guide walks through the full setup end-to-end, then explains how addresses are routed and how to wire them into both standard inboxes and entity inboxes.

What you get

• Branded addresses — [email protected] instead of [email protected].
• Per-record routing on entity inboxes — [email protected] lands directly on the conversation tied to order #12345, no manual triaging.
• Multiple inboxes can share one domain — [email protected], [email protected], [email protected] can all live on the same verified domain and route to different inboxes.
• No SendGrid account needed — Chatlane manages the underlying SendGrid Inbound Parse on your behalf. You only manage the DNS records.

Before you start

You'll need:

• An Admin or Owner role on the team. Members can't add or verify domains.
• Access to your DNS provider (Cloudflare, Route 53, GoDaddy, Namecheap, etc.). You'll be adding four records per domain.
• A subdomain you don't already use for sending — e.g. orders, mail, inbound, support. Don't reuse a subdomain that already hosts a website or another mail service; the records we ask for would conflict.

Tip: pick the subdomain name carefully — it's what your customers will see in every reply they get. support.acme.com reads cleaner than mail-server-7.acme.com.

Step-by-step setup

1. Add the domain in Chatlane

Open Team Settings → Custom Domains and click Add domain.

Type the subdomain you want to receive mail on — for example orders.translayte.dev — and click Add domain. Chatlane registers the domain with its underlying SendGrid account and generates the DNS records you need to add. You'll land on Step 2 of the dialog with four records listed.

2. Add the DNS records at your registrar

Copy each record from the dialog into your DNS provider. You'll add four records in total:

Each row has a Copy button on both the Host and the Value cells. Paste them into your DNS provider exactly as shown — including any leading s1._domainkey. prefixes. The TTL value (3600) is a recommendation; your provider may default to a different number, which is fine.

Most DNS providers reflect changes within 5–30 minutes, though some can take up to 24 hours.

3. Verify

Once the records are saved at your provider, click Verify now in the Chatlane dialog. Chatlane:

1. Resolves each DNS record from our end to confirm it's live and pointing at the right value.
2. Asks SendGrid to validate the sender-authentication records.
3. Once validated, sets up the MX route that delivers inbound mail into your Chatlane inbox.

If everything lines up, the status flips to Verified and the domain becomes available in your inbox channel settings. If any record is Not found or Mismatch, fix it at your registrar and click Verify now again — the rest of the records keep their state, so you only need to re-fix what's wrong.

Heads up: The MX record sometimes shows as Detected before you add an explicit MX entry — that's because DNS follows the mail CNAME chain to SendGrid's infrastructure and finds an MX record there. Inbound mail will route correctly either way; you don't need to add a separate MX line.

4. Done — domain is ready to use

A verified domain doesn't do anything by itself. You still need to assign it to one or more inboxes.

Assigning a domain to an inbox

Open the inbox you want to use the new domain on, go to Settings → Channels, and find the Inbound Email Addresses section under the Email channel card.

In the Domain dropdown, pick your verified domain (e.g. orders.translayte.dev). The "Use Chatlane default" option is still there if you ever want to revert.

What appears next depends on whether the inbox is a standard inbox or an entity inbox.

Standard inboxes

You'll see one row: Email (your inbox name) with a single editable local-part input ending in @yourdomain.com. The local part is what comes before the @ — e.g. support, hello, contact. Type whatever you want customers to email and the changes save automatically when you click out of the field. The "Saved" check confirms.

Email (Support Inbox)        support  @ translayte.dev    [Copy]
                             ℹ Sends to [email protected]   ✓ Saved

That's it — [email protected] will now land in this inbox.

Entity inboxes

Entity inboxes (e.g. an Orders inbox grouped by order record) get two rows:

1. Email (your inbox name) — the inbox-level address, used when a customer just wants to reach the team generally. Type whatever you want, e.g. orders → [email protected].
2. {Entity}-Specific Email Format (marked with an Entity badge) — a templated address that routes mail to a specific entity record. The local part must contain {external_id} so Chatlane knows which record to attach the conversation to.

Common templates for the entity row:

The Sends to: preview line under the input shows exactly what the address will look like for the next entity record, so you can see the result as you type.

Available placeholders

On entity inboxes you can use any of these in your templates:

{inbox_id} and {team_id} are also available on standard inbox templates if you ever want, say, multiple teams using the same domain.

Validation

Chatlane validates your template as you type:

• Entity inboxes must include {external_id} in the entity template. Otherwise every order would land on the same conversation, defeating the point of an entity inbox. Saving without {external_id} shows the error inline and rolls back.
• Local parts can contain letters, numbers, dot, dash, plus, underscore, plus the placeholders above. Anything else (spaces, quotes, @) is rejected.
• Local parts longer than 40 characters trigger a warning — some email clients truncate them.

Routing logic — how mail finds its inbox

When mail arrives at Chatlane, we match it to an inbox in this order:

1. Custom domain match — if the recipient's domain matches a verified Team Domain in our database, we iterate the inboxes assigned to that domain and try each inbox's templates against the local part. The entity template is tried first (it's more specific). On a hit, the message routes to that inbox; on an entity hit, the conversation gets attached to the matching entity record.
2. Legacy entity format — addresses like [email protected] still route exactly as they did before.
3. Per-channel inbound_email / from_email — addresses you configured at the channel level (forwarding hashes, OAuth Gmail/Outlook setups) still resolve unchanged.

Adding a custom domain does not change how existing addresses behave. Customers who reply to old emails sent from a Chatlane-default address still land in the right place. The new domain is purely additive.

When the entity record doesn't exist

If the entity template captures an {external_id} that doesn't match any record in Chatlane — common during migrations from a legacy system, or when a customer replies to an email about a record that was later deleted — the mail still lands in the inbox. It just gets routed as a contact-level conversation instead of an entity-attached one, and Chatlane adds two markers so your team can triage:

1. A conversation tag named Entity not found (auto-created the first time it's needed, orange so it's visually distinct).
2. An activity log entry on the conversation explaining which external_id was referenced and that the conversation needs reattaching to the right entity record.

Example body of the activity entry:

Mail referenced Orders ID "100100" but no matching record was found. This conversation landed as a general inbox conversation — create the orders record and reattach, or reply as a one-off.

Repeat inbound mail on the same thread reuses the existing tag and activity entry rather than duplicating them. Filter the inbox by the Entity not found tag to find any conversations that need attention.

This applies only on the custom-domain path. The legacy {slug}-{external_id}-{inbox_id}@inbound.chatlane.io path still 404s on unknown IDs — unchanged behaviour for any team using it.

Verification status

Each domain in the Custom Domains list shows one of these statuses:

• Verified — all DNS records resolve and SendGrid has confirmed them. Inbound mail is routing.
• Pending DNS — domain is registered with SendGrid but DNS hasn't propagated yet. We re-check every 5 minutes; you can also click Verify now anytime.
• Verification failed — at least one DNS record is wrong. Click into the domain to see exactly which record is mismatched, with the expected vs. found values inline.

Troubleshooting

"Not found" on every record after 30 minutes — Either your DNS provider hasn't published the records yet (check with dig or dnschecker.org), or you added them at the wrong host. Common gotcha: Cloudflare strips trailing dots, so s1._domainkey is fine; GoDaddy sometimes appends your root domain automatically — paste s1._domainkey not s1._domainkey.yourdomain.com.yourdomain.com.

"Mismatch" — The DNS record exists but points at the wrong value. The detail panel shows what we expected (e.g. mx.sendgrid.net) vs. what we found (e.g. mxa.eforward.registrar-servers.com). Update the record at your registrar to the expected value and re-verify.

Status flips back to Pending after working — SendGrid revokes validation if it stops seeing the DNS records — usually because someone deleted them or your DNS provider is intermittently failing. The address keeps working for in-flight mail, but new senders may bounce. Re-add the records and re-verify.

Verified but mail doesn't arrive — Check the domain detail page; if the MX record is in any state other than Detected, mail won't land. If your DNS provider doesn't let you add an explicit MX record at a subdomain that already has a CNAME (some don't), that's fine — Chatlane will route via the CNAME chain. If it shows Not found and your provider does allow it, add: <your subdomain> → mx.sendgrid.net priority 10.

Multiple inboxes on one domain

You don't need a separate verified domain per inbox. After verifying translayte.dev once, you can have:

• [email protected] → Support Inbox (standard)
• [email protected] → Orders Inbox (entity, primary row)
• [email protected] → Orders Inbox (entity, entity row resolving to order #12345)
• [email protected] → Billing Inbox (standard)
• [email protected] → Sales Inbox (standard)

The Custom Domains list shows a count of inboxes using each domain so you can see at a glance who's attached.

Removing a domain

Open the domain in the Custom Domains list and scroll to Danger zone → Remove domain. The button is disabled while any inbox still references the domain — you must first unassign it (switch the inbox back to "Use Chatlane default") on each affected inbox.

Removing the domain:

1. Deletes the Inbound Parse setting from SendGrid (mail to the domain stops being routed).
2. Deletes the sender-authentication record from SendGrid.
3. Deletes the row from Chatlane's database.

This cannot be undone. To bring the domain back you'd add it again and re-add all the DNS records. The DNS records aren't touched — those live at your registrar, not in Chatlane, so they stay until you remove them.

Side effects worth knowing

Forwarding addresses

When an inbox is on Chatlane default, the Email channel card surfaces the hash-style forwarding address (inbox-94356ccb…@inbound.chatlane.io) so Gmail / Outlook OAuth channels can forward into it. When a custom domain is selected, that whole forwarding section hides — mail goes directly to the custom domain via the MX records, so the Chatlane forwarding address is redundant.

If you switch back to Chatlane default later, the forwarding section reappears and the addresses are exactly what they were before (each channel keeps its unique hash).

Outbound From address

Custom domains only affect inbound routing. The address replies are sent from (the "From" header) is still controlled by your email channel's from_email setting — typically something like [email protected] configured against your own SendGrid or Mailgun account. To make the reply chain feel consistent, you'd usually set the From to match the inbound address (e.g. both [email protected]). They don't have to match — replies route by header threading regardless — but matching keeps the customer experience tidy.

Website Chat Widget handoff

On entity inboxes, the chat widget's "Continue by email" option automatically offers both the inbox-level and entity-specific addresses, when the widget is initialised with the entity context. For example:

<script>
  ChatlaneWidget('init', {
    user: { name: 'Visitor', email: '[email protected]' },
    entity: { slug: 'orders', external_id: '12345' },
  });
</script>

In the handoff panel the visitor sees:

✉  For this order        [Recommended]
   [email protected]

✉  For anything else
   [email protected]

Clicking either opens the visitor's mail client with the address pre-filled. The entity-specific row threads directly into the existing order conversation; the primary row creates a fresh inquiry. No extra config — this happens as soon as you verify a domain and assign it to the entity inbox.

FAQ

Can I use the apex domain (translayte.dev) instead of a subdomain?
Technically yes, but we don't recommend it. The DNS records Chatlane needs (DKIM CNAMEs in particular) might conflict with records you already use for outbound sending, MX records for an existing mailserver, or your website's TXT records. Subdomains keep concerns separate.

Do I need a separate SendGrid account?
No. Chatlane uses its own SendGrid account for inbound parsing — that's why no API key is asked for in the Add Domain dialog. Inbound Parse is free on SendGrid, so this costs you nothing.

What about my outbound sending?
Outbound sending is per-channel and uses whatever provider you configured on the inbox's Email channel (your own SendGrid, Mailgun, Amazon SES, SMTP, or Gmail/Outlook OAuth). Custom domains and outbound sending are independent — you can have a custom inbound domain with Gmail OAuth outbound, or vice versa.

Can customers reply to messages we send from a Chatlane-default address?
Yes. Old emails with a Chatlane-default Reply-To still route correctly — see the routing precedence above. Switching to a custom domain doesn't break any in-flight conversations.

What happens if I delete an entity record that has an active address?
Mail sent to [email protected] after the record is deleted lands in the inbox as a contact-level conversation with an Entity not found tag and an activity log entry explaining which ID was referenced. The conversation is plainly visible — no silent drops, no bounces. See the When the entity record doesn't exist section above for details. Same behaviour for the migration scenario where a team only imports newer records but customers still email about older ones.

Why does the verification check three sender-auth records plus a DMARC?
SendGrid requires the domain to be authenticated (DKIM + SPF) before it'll route inbound mail to it. The DMARC record is recommended by SendGrid as part of the same setup — it tells other mail servers how to handle messages claiming to be from your domain. Strictly speaking it's only required for outbound, not inbound, but we surface it so the records you see in Chatlane match what you'd see in SendGrid's dashboard.

Will this work on free DNS providers (Cloudflare free tier, etc.)?
Yes. The records we ask for are standard CNAMEs and TXT — every DNS provider supports them.

---

For the underlying inbox model and how entity inboxes differ from standard ones, see Inbox types — standard vs entity. For how channels work inside an inbox, see Connect your channels.