Shared Domain vs Custom Domain

By default, agent mailboxes use the shared domain agentmail.usetransactional.com. For branded addresses, you can bring your own domain.

	Shared Domain	Custom Domain
Address	`agent@agentmail.usetransactional.com`	`agent@yourdomain.com`
Setup	Instant	5-10 minutes
Deliverability	Shared reputation	Your own reputation
Branding	Transactional branding	Your branding

Add a Custom Domain

1. Register the Domain

const domain = await tx.agentEmail.domains.create({
  domain: 'mail.yourdomain.com',
});
 
console.log(domain.id);     // dom_abc123
console.log(domain.status); // 'pending_verification'
console.log(domain.dnsRecords);
// → Array of DNS records to configure

2. Configure DNS Records

Add the following DNS records to your domain's DNS provider:

DKIM (DomainKeys Identified Mail)

Type:  TXT
Name:  transactional._domainkey.mail.yourdomain.com
Value: v=DKIM1; k=rsa; p=MIGfMA0GCSq...

SPF (Sender Policy Framework)

Type:  TXT
Name:  mail.yourdomain.com
Value: v=spf1 include:spf.usetransactional.com ~all

DMARC (Domain-based Message Authentication)

Type:  TXT
Name:  _dmarc.mail.yourdomain.com
Value: v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com

MX (Mail Exchange) — for receiving inbound email

Type:  MX
Name:  mail.yourdomain.com
Value: 10 inbound.usetransactional.com

3. Verify the Domain

After adding DNS records, trigger verification:

const result = await tx.agentEmail.domains.verify(domain.id);
 
console.log(result.status);      // 'verified' or 'pending'
console.log(result.dkim);        // 'verified'
console.log(result.spf);         // 'verified'
console.log(result.mx);          // 'verified'
console.log(result.dmarc);       // 'verified'

DNS propagation typically takes 5-10 minutes but can take up to 48 hours in rare cases.

4. Create Mailboxes on Your Domain

Once verified, create agent mailboxes on your custom domain:

const mailbox = await tx.agentEmail.mailboxes.create({
  name: 'research-agent',
  domain: 'mail.yourdomain.com',
});
 
console.log(mailbox.address);
// → research-agent@mail.yourdomain.com

Domain Verification Status

Check verification status at any time:

const domain = await tx.agentEmail.domains.get(domainId);
 
// Status: 'pending_verification' | 'verified' | 'failed'
console.log(domain.status);
 
// Individual record status
console.log(domain.records.dkim);   // 'verified' | 'pending' | 'failed'
console.log(domain.records.spf);    // 'verified' | 'pending' | 'failed'
console.log(domain.records.mx);     // 'verified' | 'pending' | 'failed'
console.log(domain.records.dmarc);  // 'verified' | 'pending' | 'failed'

Manage Domains

// List all domains
const domains = await tx.agentEmail.domains.list();
 
// Delete a domain (removes all associated mailboxes)
await tx.agentEmail.domains.delete(domainId);

Best Practices

Use a subdomain (e.g., mail.yourdomain.com) rather than your root domain to separate agent email reputation from your primary domain
Set up DMARC reporting (rua tag) to monitor authentication results
Start with p=quarantine DMARC policy and move to p=reject once verified
Keep the shared domain for development and testing; use custom domains in production

Next Steps

Sending Email — Send from your custom domain
Webhooks — Event notifications
API Reference — Domain endpoints

Custom Domains