API Reference

Domains API

Endpoints for listing verified domains for sender addresses.

Read-Only API

Domains can only be added and managed in the ArtaMail dashboard under Settings → Sender Addresses. The API provides read-only access to view your verified domains. Creating, verifying, and deleting domains must be done through the dashboard interface.

GET/api/v1/domains

Get all domains for your organization, including their verification status on both AWS accounts.

Example Request

Terminal

curl https://artamail.artatol.com/api/v1/domains \
  -H "Authorization: Bearer am_live_sk_xxx"

Response

json

[
  {
    "id": "domain-uuid-1",
    "domain": "example.com",
    "primary_verified": true,
    "secondary_verified": true,
    "verification_token": "_amazonses.abc123...",
    "dkim_tokens": [
      "token1._domainkey",
      "token2._domainkey",
      "token3._domainkey"
    ],
    "created_at": "2024-01-15T10:00:00Z",
    "last_checked_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": "domain-uuid-2",
    "domain": "company.io",
    "primary_verified": true,
    "secondary_verified": false,
    "verification_token": "_amazonses.xyz789...",
    "dkim_tokens": [
      "token1._domainkey",
      "token2._domainkey",
      "token3._domainkey"
    ],
    "created_at": "2024-01-14T09:00:00Z",
    "last_checked_at": "2024-01-15T09:00:00Z"
  }
]

Domain Fields

Field	Type	Description
`id`	string (uuid)	Unique domain identifier
`domain`	string	Domain name (e.g., "example.com")
`primary_verified`	boolean	Verification status on primary AWS account
`secondary_verified`	boolean	Verification status on secondary AWS account
`verification_token`	string \| null	TXT record value for domain verification
`dkim_tokens`	string[]	Array of 3 DKIM tokens for CNAME records
`created_at`	string (ISO 8601)	When the domain was added
`last_checked_at`	string (ISO 8601) \| null	Last verification status check timestamp

Verification Status

A domain has three possible verification states:

Fully Verified

primary_verified: true AND secondary_verified: true
Can be used to create sender addresses.

Partially Verified

Verified on only one AWS account.
Cannot be used for sender addresses until fully verified.

Not Verified

primary_verified: false AND secondary_verified: false
DNS records not yet propagated or incorrect.

Using Verified Domains

Once a domain is fully verified, you can create sender addresses with any local part:

typescript

// List verified domains
const domains = await artamail.listDomains();
const fullyVerified = domains.filter(
  d => d.primary_verified && d.secondary_verified
);
// Create sender address with verified domain
// (must be done in dashboard)
// Example: [email protected], [email protected]

Adding & Verifying Domains

To add and verify a custom domain:

1Go to Settings → Sender Addresses → Domains tab in the dashboard
2Click "Add Domain" and enter your domain name
3Copy the provided DNS records (1 TXT + 3 CNAME) and add them to your DNS provider
4Wait for DNS propagation (5-30 minutes typically)
5Click "Refresh Status" to check verification on both AWS accounts

DNS Records Required

For each domain, you must add the following DNS records:

TXT Record (Domain Verification)

text

Name: _amazonses.example.com
Type: TXT
Value: <verification_token from API>

CNAME Records (DKIM - 3 records)

text

Name: token1._domainkey.example.com
Type: CNAME
Value: token1.dkim.amazonses.com
Name: token2._domainkey.example.com
Type: CNAME
Value: token2.dkim.amazonses.com
Name: token3._domainkey.example.com
Type: CNAME
Value: token3.dkim.amazonses.com

Dual Account Verification Required

ArtaMail uses two AWS SES accounts for load balancing and redundancy. Your domain must be verified on both accounts before it can be used for sender addresses. This happens automatically when you add a domain in the dashboard - DNS records work for both accounts simultaneously.