Domain Management

The Domains API allows you to register and manage custom domains for email sending and receiving.

Overview

Custom domains enable you to:

Send emails from your own domain (e.g., noreply@yourcompany.com)
Receive emails at addresses on your domain
Maintain brand consistency in email communications
Configure SPF, DKIM, and DMARC for deliverability

Domain States

Domains progress through the following states:

State	Description
`pending`	Domain registered, awaiting DNS verification
`active`	Domain verified and ready for use
`suspended`	Domain temporarily disabled
`failed`	Verification failed, requires action

Base URL

/api/email/domains

Endpoints

List Domains

Retrieve all domains for the authenticated organization.

GET /api/email/domains

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by: `pending`, `active`, `failed`
`limit`	number	Number of results (default: 20)
`offset`	number	Pagination offset

Response:

{
  "domains": [
    {
      "id": "dom_987654321",
      "domain": "yourcompany.com",
      "status": "active",
      "isDefault": true,
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-10T09:30:00Z",
      "verifiedAt": "2024-01-10T09:30:00Z",
      "inboxCount": 5,
      "sentCount": 1250
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Register Domain

POST /api/email/domains

Request Body:

{
  "domain": "yourcompany.com",
  "isDefault": false,
  "region": "us-east-1"
}

Response:

{
  "id": "dom_987654321",
  "domain": "yourcompany.com",
  "status": "pending",
  "isDefault": false,
  "dnsRecords": [
    {
      "type": "MX",
      "name": "yourcompany.com",
      "value": "10 inbound-smtp.us-east-1.amazonaws.com",
      "priority": 10
    },
    {
      "type": "TXT",
      "name": "_amazonses.yourcompany.com",
      "value": "v=spf1 include:amazonses.com ~all"
    },
    {
      "type": "TXT",
      "name": "_domainkey.yourcompany.com",
      "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqG..."
    }
  ],
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z"
}

Get Domain

Retrieve detailed information about a specific domain.

GET /api/email/domains/:id

Response:

{
  "id": "dom_987654321",
  "domain": "yourcompany.com",
  "status": "active",
  "isDefault": true,
  "region": "us-east-1",
  "dnsRecords": [
    {
      "type": "MX",
      "name": "yourcompany.com",
      "value": "10 inbound-smtp.us-east-1.amazonaws.com",
      "priority": 10,
      "verified": true
    },
    {
      "type": "TXT",
      "name": "_amazonses.yourcompany.com",
      "value": "v=spf1 include:amazonses.com ~all",
      "verified": true
    }
  ],
  "verificationStatus": {
    "mx": true,
    "dkim": true,
    "spf": true,
    "dmarc": false
  },
  "createdAt": "2024-01-10T08:00:00Z",
  "verifiedAt": "2024-01-10T09:30:00Z",
  "stats": {
    "inboxCount": 5,
    "sentCount": 1250,
    "receivedCount": 3420
  }
}

Update Domain

Update domain settings.

PATCH /api/email/domains/:id

Request Body:

{
  "isDefault": true,
  "status": "suspended"
}

Response:

{
  "id": "dom_987654321",
  "domain": "yourcompany.com",
  "isDefault": true,
  "status": "suspended",
  "updatedAt": "2024-01-15T11:00:00Z"
}

Verify Domain

Trigger a DNS verification check for a pending domain.

POST /api/email/domains/:id/verify

Response:

{
  "id": "dom_987654321",
  "domain": "yourcompany.com",
  "status": "active",
  "verificationStatus": {
    "mx": true,
    "dkim": true,
    "spf": true,
    "dmarc": false
  },
  "verifiedAt": "2024-01-15T11:30:00Z"
}

Delete Domain

Remove a domain from your account.

DELETE /api/email/domains/:id

Response:

{
  "success": true,
  "message": "Domain removed successfully",
  "deletedAt": "2024-01-15T12:00:00Z"
}

DNS Records

When you register a domain, you'll receive DNS records to configure:

Required Records

Type	Name	Value	Purpose
MX	`@`	`10 inbound-smtp.us-east-1.amazonaws.com`	Receive emails
TXT	`_amazonses`	Token provided by API	Verify domain ownership

Recommended Records

Type	Name	Value	Purpose
TXT	`@`	`v=spf1 include:amazonses.com ~all`	SPF authentication
TXT	`_domainkey`	DKIM public key	DKIM signing
TXT	`_dmarc`	`v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com`	DMARC policy

Code Examples

Register and Verify Domain

// Step 1: Register the domain
const domain = await fetch('/api/email/domains', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ domain: 'yourcompany.com' })
});

const { dnsRecords } = await domain.json();

// Step 2: Display DNS records to user
console.log('Add these DNS records:');
dnsRecords.forEach(record => {
  console.log(`${record.type}: ${record.name} -> ${record.value}`);
});

// Step 3: Verify after DNS propagation
setTimeout(async () => {
  await fetch(`/api/email/domains/${domain.id}/verify`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });
}, 60000); // Wait 1 minute for DNS propagation

List Active Domains

const response = await fetch(
  '/api/email/domains?status=active',
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);

const { domains } = await response.json();

domains.forEach(domain => {
  console.log(`${domain.domain} - ${domain.inboxCount} inboxes`);
});

Check Verification Status

const response = await fetch(
  `/api/email/domains/${domainId}`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);

const domain = await response.json();

const allVerified = Object.values(domain.verificationStatus)
  .every(status => status === true);

console.log(`Domain verified: ${allVerified}`);

Error Codes

Code	Description
`DOMAIN_NOT_FOUND`	Domain does not exist
`DOMAIN_EXISTS`	Domain already registered
`DOMAIN_INVALID`	Invalid domain format
`VERIFICATION_FAILED`	DNS verification failed
`DOMAIN_IN_USE`	Cannot delete domain with active inboxes

DNS Verification - Step-by-step verification guide
Inboxes - Create inboxes on verified domains
Sending Email - Send from custom domains

Domain Management

On this page