Custom Domains

By default, inboxes use @lobstermail.ai addresses. With a custom domain, your agent's inboxes can use addresses like agent@yourdomain.com. Custom domains require Tier 2 (Builder) or above.

Domain Limits#

Adding a Domain#

const domain = await lm.addDomain({ domain: 'yourdomain.com' });
console.log(domain.id);         // dom_abc123
console.log(domain.status);     // 'pending'
console.log(domain.dnsRecords); // Array of records to configure

Or via the API:

POST /v1/domains
{ "domain": "yourdomain.com" }

How Verification Works#

Domain verification happens in two phases:

1. Phase 1 — DNS verification. You add TXT, MX, and SPF records. LobsterMail checks them automatically.
2. Phase 2 — DKIM setup. Once DNS is verified, LobsterMail generates three CNAME records for DKIM signing. You add those, and DKIM is verified automatically.

The domain status progresses through: pending → dns_verified → verified (or failed).

Phase 1: DNS Records#

The initial response includes three DNS records to add at your DNS provider:

1. TXT Record (Domain Verification)#

2. MX Record (Inbound Email)#

3. TXT Record (SPF)#

If you already have an SPF record, add include:amazonses.com to your existing record rather than creating a new one.

Phase 2: DKIM Records#

Once all DNS records from Phase 1 are verified, LobsterMail creates a sending identity and generates three DKIM CNAME records. These appear automatically in your domain's dnsRecords array when you check the status.

Add all three CNAME records at your DNS provider. LobsterMail polls for DKIM verification automatically — once the records propagate, your domain status moves to verified.

Tip: DKIM CNAME records typically verify within a few minutes, but DNS propagation can take up to 48 hours in some cases.

Checking Verification Status#

Check the current status and see which DNS records still need attention:

const domain = await lm.getDomain('dom_abc123');
console.log(domain.status);     // 'pending' | 'dns_verified' | 'verified' | 'failed'
console.log(domain.dkimStatus); // 'not_started' | 'pending' | 'success' | 'failed'
console.log(domain.dnsRecords); // Each record has a 'status' field ('pending' | 'verified')

Or via the API:

GET /v1/domains/dom_abc123/status

Triggering Re-verification#

If you have updated your DNS records and want to check again without waiting for the automatic retry:

await lm.verifyDomain('dom_abc123');

POST /v1/domains/dom_abc123/verify

Using Your Domain#

Once fully verified (DNS + DKIM), create inboxes on your domain:

const inbox = await lm.createInbox({
  localPart: 'agent',
  domain: 'yourdomain.com',
});

console.log(inbox.address); // agent@yourdomain.com

If you omit domain, inboxes default to @lobstermail.ai.