Domains

Every inbox lives on a domain. Use the shared domain to start sending immediately, or add a custom domain for branded addresses and isolated sender reputation.

Shared domain vs custom domain

	Shared domain	Custom domain
Setup	Instant — no DNS required	5 min DNS configuration
Address format	`agent@agents.commune.email`	`agent@yourdomain.com`
DKIM signing	Commune’s key	Your domain’s key
Sender reputation	Shared across tenants	Isolated to your org
Best for	Getting started, prototyping	Production, branded emails

Create a custom domain

const domain = await commune.domains.create({ name: 'mail.mycompany.com' });
console.log(domain.id); // Use this ID for subsequent operations

domain = client.domains.create(name="mail.mycompany.com")
print(domain.id)

create_domain(name="mail.mycompany.com")

curl -X POST https://api.commune.email/v1/domains \
  -H "Authorization: Bearer comm_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "mail.mycompany.com"}'

Parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	Domain name (e.g., `mail.mycompany.com`)
`region`	`string`	No	AWS region (e.g., `us-east-1`, `eu-west-1`)

Response

{
  "data": {
    "id": "d_abc123",
    "name": "mail.mycompany.com",
    "status": "pending",
    "region": "us-east-1",
    "createdAt": "2026-02-14T10:00:00Z"
  }
}

Get DNS records

After creating a domain, retrieve the DNS records you need to add at your registrar.

const records = await commune.domains.records('d_abc123');
for (const record of records) {
  console.log(`${record.type} ${record.name} → ${record.value}`);
}

records = client.domains.records("d_abc123")
for record in records:
    print(f"{record.type} {record.name} → {record.value}")

get_domain_records(domain_id="d_abc123")

curl "https://api.commune.email/v1/domains/d_abc123/records" \
  -H "Authorization: Bearer comm_..."

Example DNS records

The API returns records like these that you add to your DNS provider:

Type	Name	Value	Purpose
`MX`	`mail.mycompany.com`	`feedback-smtp.us-east-1.amazonses.com`	Receive email
`TXT`	`mail.mycompany.com`	`v=spf1 include:amazonses.com ~all`	SPF authentication
`CNAME`	`commune._domainkey.mail.mycompany.com`	`dkim.commune.email...`	DKIM signing
`TXT`	`_dmarc.mail.mycompany.com`	`v=DMARC1; p=none; ...`	DMARC policy

The exact records depend on your domain configuration and the email provider. Add all returned records exactly as shown.

Verify domain

After adding DNS records, trigger verification. DNS propagation typically takes 5–30 minutes.

const result = await commune.domains.verify('d_abc123');
console.log(result); // { status: "verified" } or { status: "pending", ... }

result = client.domains.verify("d_abc123")
print(result.status)

verify_domain(domain_id="d_abc123")

curl -X POST "https://api.commune.email/v1/domains/d_abc123/verify" \
  -H "Authorization: Bearer comm_..."

Domain statuses

Status	Description
`pending`	DNS records not yet verified
`verified`	All DNS records confirmed — domain is ready to use
`failed`	Verification failed — check DNS records

List domains

const domains = await commune.domains.list();

domains = client.domains.list()

list_domains()

curl "https://api.commune.email/v1/domains" \
  -H "Authorization: Bearer comm_..."

Get domain details

const domain = await commune.domains.get('d_abc123');

domain = client.domains.get("d_abc123")

curl "https://api.commune.email/v1/domains/d_abc123" \
  -H "Authorization: Bearer comm_..."

Domain setup guide

Step 1: Create the domain

curl -X POST https://api.commune.email/v1/domains \
  -H "Authorization: Bearer comm_..." \
  -d '{"name": "mail.mycompany.com"}'

Step 2: Add DNS records

Get the records from the API and add them at your DNS provider (Cloudflare, Route53, GoDaddy, etc.):

curl "https://api.commune.email/v1/domains/DOMAIN_ID/records" \
  -H "Authorization: Bearer comm_..."

Step 3: Wait for DNS propagation

DNS changes typically take 5–30 minutes to propagate. Some providers may take up to 48 hours.

Step 4: Verify

curl -X POST "https://api.commune.email/v1/domains/DOMAIN_ID/verify" \
  -H "Authorization: Bearer comm_..."

Step 5: Create inboxes on your domain

curl -X POST https://api.commune.email/v1/inboxes \
  -H "Authorization: Bearer comm_..." \
  -d '{"local_part": "support", "domain_id": "DOMAIN_ID"}'

Domain limits

Tier	Custom domains
Free	0 (shared domain only)
Pro	3
Business	10
Enterprise	Unlimited

Domain object

Field	Type	Description
`id`	`string`	Unique domain ID
`name`	`string`	Domain name
`status`	`string`	`pending`, `verified`, or `failed`
`region`	`string \| null`	AWS region
`records`	`array`	DNS records for verification
`createdAt`	`string`	ISO creation timestamp

What’s next?

Inboxes

Create email addresses on your verified custom domain.

Email Authentication

Understand DKIM, SPF, and DMARC authentication in detail.

Delivery Monitoring

Track delivery rates and sender reputation per domain.

Security Overview

Full picture of Commune’s inbound and outbound security layers.

Get Started

SDKs

Email

Commune OAuth

Phone & SMS

Security

Integrations

Examples

Community

Shared domain vs custom domain

Create a custom domain

Parameters

Response

Get DNS records

Example DNS records

Verify domain

Domain statuses

List domains

Get domain details

Domain setup guide

Step 1: Create the domain

Step 2: Add DNS records

Step 3: Wait for DNS propagation

Step 4: Verify

Step 5: Create inboxes on your domain

Domain limits

Domain object

What’s next?

Inboxes

Email Authentication

Delivery Monitoring

Security Overview

​Shared domain vs custom domain

​Create a custom domain

​Parameters

​Response

​Get DNS records

​Example DNS records

​Verify domain

​Domain statuses

​List domains

​Get domain details

​Domain setup guide

​Step 1: Create the domain

​Step 2: Add DNS records

​Step 3: Wait for DNS propagation

​Step 4: Verify

​Step 5: Create inboxes on your domain

​Domain limits

​Domain object

​What’s next?

Inboxes

Email Authentication

Delivery Monitoring

Security Overview

Shared domain vs custom domain

Create a custom domain

Parameters

Response

Get DNS records

Example DNS records

Verify domain

Domain statuses

List domains

Get domain details

Domain setup guide

Step 1: Create the domain

Step 2: Add DNS records

Step 3: Wait for DNS propagation

Step 4: Verify

Step 5: Create inboxes on your domain

Domain limits

Domain object

What’s next?