Domains API
Register and verify sending domains for email authentication.
Why Verify Domains?
Domain verification ensures your emails are properly authenticated with DKIM, improving deliverability and protecting against spoofing.
DKIM Signing
Cryptographically sign emails to prove authenticity.
Better Deliverability
Verified domains have higher inbox placement rates.
Brand Protection
Prevent unauthorized use of your domain for emails.
Endpoints
/api/v1/domainsAdd Domain
Register a new sending domain. Returns DNS records required for DKIM verification.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| domain | string | Required | Domain name (e.g., "yourcompany.com") |
| external_id | string | Optional | Your external system ID for correlation |
| metadata | object | Optional | Custom key-value pairs for your application |
Example Request
curl -X POST https://sendmailos.com/api/v1/domains \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"domain": "yourcompany.com",
"external_id": "client_domain_123",
"metadata": {
"client_name": "Acme Corp",
"plan": "enterprise"
}
}'Response (201 Created)
{
"success": true,
"domain": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"domain_name": "yourcompany.com",
"status": "pending",
"external_id": "client_domain_123",
"metadata": {
"client_name": "Acme Corp",
"plan": "enterprise"
},
"dkim_tokens": [
"abc123xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"def456xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"ghi789xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
],
"created_at": "2024-01-15T10:30:00Z",
"dns_records": [
{
"type": "CNAME",
"name": "abc123._domainkey.yourcompany.com",
"value": "abc123.dkim.amazonses.com"
},
{
"type": "CNAME",
"name": "def456._domainkey.yourcompany.com",
"value": "def456.dkim.amazonses.com"
},
{
"type": "CNAME",
"name": "ghi789._domainkey.yourcompany.com",
"value": "ghi789.dkim.amazonses.com"
}
]
}
}Setting Up DNS Records
After adding a domain, configure the CNAME records in your DNS provider.
Add the domain via API
Call POST /domains to get your DKIM tokens
Configure CNAME records
Add the 3 CNAME records to your DNS provider
Wait for verification
AWS SES automatically verifies DNS records (usually within 72 hours)
DNS propagation
DNS changes can take up to 48 hours to propagate worldwide. The domain status will automatically update once verified.
/api/v1/domainsList Domains
Retrieve all domains for your organization with their verification status.
Example Request
curl -X GET https://sendmailos.com/api/v1/domains \
-H "Authorization: Bearer sk_live_..."Response
{
"success": true,
"domains": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"domain_name": "yourcompany.com",
"status": "verified",
"external_id": "client_domain_123",
"metadata": { "client_name": "Acme Corp" },
"dkim_tokens": ["abc123...", "def456...", "ghi789..."],
"created_at": "2024-01-15T10:30:00Z",
"verified_at": "2024-01-15T14:45:00Z"
},
{
"id": "660f9500-f30c-52e5-b919-557766551111",
"domain_name": "marketing.yourcompany.com",
"status": "pending",
"external_id": null,
"metadata": {},
"dkim_tokens": ["jkl012...", "mno345...", "pqr678..."],
"created_at": "2024-01-20T09:00:00Z",
"verified_at": null
}
]
}Domain Status
Domains can have one of the following statuses:
| Status | Description |
|---|---|
pending | Waiting for DNS verification |
verified | DKIM verified, ready to send emails |
failed | Verification failed, check DNS records |
Automatic verification
SendMailOS automatically checks DNS records periodically. Once your CNAME records are properly configured, the status will update to "verified".