Domains

The Domains API allows you to manage and verify sending domains for your email campaigns.

Overview

The Domains API enables you to register, verify, and manage custom domains for sending emails through Unsent. Proper domain configuration with DNS records (DKIM, SPF, DMARC) ensures high deliverability and authentication of your emails.

Base URL

https://api.unsent.dev/v1/domains

Features

Add sending domains

Domain verification

Automate DNS setup for DKIM, SPF, and DMARC

DNS management

Get DNS records needed for verification

Domain monitoring

Check verification status and health

Regional settings

Configure domains for different AWS regions

Tracking options

Enable open and click tracking per domain

Endpoints

List All Domains

GET /v1/domains

Retrieve all domains accessible by your API key

curl -X GET https://api.unsent.dev/v1/domains \
  -H "Authorization: Bearer your-api-key"

Response (200 OK):

[
  {
    "id": "0Lleb1FOUnB60jSueJ/mkPId1vrdB68T8/u9tiInsi4=",
    "name": "example.com",
    "teamId": "jonVNF8M+EbJObaRAz2XBHnoJ6Add/tazP9lfOiPJ3E=",
    "status": "SUCCESS",
    "region": "us-east-1",
    "clickTracking": true,
    "openTracking": true,
    "publicKey": "MIIBIjANBgkqhkiG9w...",
    "dkimStatus": "Success",
    "spfDetails": "v=spf1 include:amazonses.com ~all",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T11:00:00Z",
    "dmarcAdded": true,
    "isVerifying": false,
    "errorMessage": null,
    "subdomain": null,
    "verificationError": null,
    "lastCheckedTime": "2024-01-15T11:00:00Z",
    "dnsRecords": [
      {
        "type": "TXT",
        "name": "_amazonses.example.com",
        "value": "abc123verification",
        "ttl": "Auto",
        "priority": null,
        "status": "SUCCESS",
        "recommended": true
      }
    ]
  }
]

[!NOTE] If your API key is restricted to a specific domain, only that domain will be returned. Otherwise, all team domains are returned.

Get Domain by ID

GET /v1/domains/{id}

Retrieve detailed information about a specific domain

Path Parameters:

id (string, required) - The domain ID

curl -X GET https://api.unsent.dev/v1/domains/QmeegZSZyFXvpkEN3Ojsa5Aa7ehAeJ+vrd8MjyQM/SY= \
  -H "Authorization: Bearer your-api-key"

Response (200 OK):

{
  "id": "QmeegZSZyFXvpkEN3Ojsa5Aa7ehAeJ+vrd8MjyQM/SY=",
  "name": "example.com",
  "teamId": "jonVNF8M+EbJObaRAz2XBHnoJ6Add/tazP9lfOiPJ3E=",
  "status": "SUCCESS",
  "region": "us-east-1",
  "clickTracking": false,
  "openTracking": false,
  "publicKey": "MIIBIjANBgkqhkiG9w...",
  "dkimStatus": "Success",
  "spfDetails": "v=spf1 include:amazonses.com ~all",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z",
  "dmarcAdded": true,
  "isVerifying": false,
  "errorMessage": null,
  "subdomain": null,
  "verificationError": null,
  "lastCheckedTime": "2024-01-15T11:00:00Z",
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "_amazonses.example.com",
      "value": "abc123verification",
      "ttl": "Auto",
      "priority": null,
      "status": "SUCCESS",
      "recommended": true
    },
    {
      "type": "TXT",
      "name": "_dmarc.example.com",
      "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com",
      "ttl": "Auto",
      "priority": null,
      "status": "SUCCESS",
      "recommended": true
    }
  ]
}

Error Responses:

404 Not Found - Domain not found
403 Forbidden - API key doesn't have access to this domain

Create Domain

POST /v1/domains

Request Body:

Field	Type	Required	Description
`name`	string	Yes	The domain name (e.g., "example.com")
`region`	string	Yes	AWS region (e.g., "us-east-1")

curl -X POST https://api.unsent.dev/v1/domains \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "yourdomain.com",
    "region": "us-east-1"
  }'

Response (200 OK):

{
  "id": "Uh/A9L2Sarmc6CIr3zbHeRc6O2jsd4INYX+ezfbRQjA=",
  "name": "yourdomain.com",
  "teamId": "jonVNF8M+EbJObaRAz2XBHnoJ6Add/tazP9lfOiPJ3E=",
  "status": "NOT_STARTED",
  "region": "us-east-1",
  "clickTracking": false,
  "openTracking": false,
  "publicKey": "MIIBIjANBgkqhkiG9w...",
  "dkimStatus": null,
  "spfDetails": null,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "dmarcAdded": false,
  "isVerifying": false,
  "errorMessage": null,
  "subdomain": null,
  "verificationError": null,
  "lastCheckedTime": null,
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "_amazonses.yourdomain.com",
      "value": "verification-token-here",
      "ttl": "Auto",
      "priority": null,
      "status": "NOT_STARTED",
      "recommended": true
    },
    {
      "type": "TXT",
      "name": "yourdomain.com",
      "value": "v=spf1 include:amazonses.com ~all",
      "ttl": "Auto",
      "priority": null,
      "status": "NOT_STARTED",
      "recommended": true
    },
    {
      "type": "TXT",
      "name": "dkim._domainkey.yourdomain.com",
      "value": "k=rsa; p=MIIBIjANBgkqhkiG9w...",
      "ttl": "Auto",
      "priority": null,
      "status": "NOT_STARTED",
      "recommended": true
    }
  ]
}

[!IMPORTANT] After creating a domain, you must configure the DNS records provided in the dnsRecords array with your domain provider before the domain can be verified.

Verify Domain

PUT /v1/domains/{id}/verify

Start the verification process for a domain

Path Parameters:

id (string, required) - The domain ID to verify

curl -X PUT https://api.unsent.dev/v1/domains/qfdxzQOVX4jzcAbhyfethMd/aCIyDiSZKYDV+mkCvlE=/verify \
  -H "Authorization: Bearer your-api-key"

Response (200 OK):

{
  "message": "Domain verification started"
}

Error Responses:

404 Not Found - Domain not found
```
{
  "error": "Domain not found"
}
```

403 Forbidden - API key doesn't have access to this domain

{
  "error": "API key doesn't have access to this domain"
}

[!NOTE] The verification process runs asynchronously. Check the domain's status field using the GET endpoint to monitor verification progress.

Delete Domain

DELETE /v1/domains/{id}

Delete a domain from your account

Path Parameters:

id (string, required) - The domain ID to delete

curl -X DELETE https://api.unsent.dev/v1/domains/Uh/A9L2Sarmc6CIr3zbHeRc6O2jsd4INYX+ezfbRQjA= \
  -H "Authorization: Bearer your-api-key"

Response (200 OK):

{
  "success": true,
  "message": "Domain deleted successfully"
}

Error Responses:

404 Not Found - Domain not found
```
{
  "error": "Domain not found"
}
```

403 Forbidden - API key doesn't have access to this domain

{
  "error": "API key doesn't have access to this domain"
}

[!WARNING] Deleting a domain is permanent and cannot be undone. Any emails scheduled to be sent from this domain will fail.

Get Domain Analytics

GET /v1/domains/{id}/analytics

Retrieve analytics data for a specific domain.

Path Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes	The unique identifier of the domain

Query Parameters:

Parameter	Type	Required	Default	Description
`period`	`string`	No	`month`	Time period for analytics (`day`, `week`, `month`)

curl -X GET https://api.unsent.dev/v1/domains/domain_123/analytics?period=month \
  -H "Authorization: Bearer your-api-key"

Response (200 OK):

{
  "period": "month",
  "totalSent": 15000,
  "totalDelivered": 14800,
  "totalOpened": 9500,
  "totalClicked": 2300,
  "deliveryRate": 98.6,
  "openRate": 64.2,
  "clickRate": 24.2
}

Error Responses:

400 Bad Request - Invalid parameters
401 Unauthorized - Invalid API key
500 Internal Server Error - Server error

Get Domain Stats

GET /v1/domains/{id}/stats

Retrieve detailed statistics for a specific domain within a date range.

Path Parameters:

Parameter	Type	Required	Description
`id`	`string`	Yes	The unique identifier of the domain

Query Parameters:

Parameter	Type	Required	Description
`startDate`	`string`	No	Start date (ISO 8601)
`endDate`	`string`	No	End date (ISO 8601)

curl -X GET "https://api.unsent.dev/v1/domains/domain_123/stats?startDate=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer your-api-key"

Response (200 OK):

{
  "totalSent": 5000,
  "totalDelivered": 4950,
  "totalOpened": 3000,
  "totalClicked": 1000,
  "totalBounced": 50,
  "totalComplained": 5,
  "deliveryRate": 99.0,
  "openRate": 60.6,
  "clickRate": 33.3,
  "bounceRate": 1.0,
  "complaintRate": 0.1
}

Error Responses:

400 Bad Request - Invalid date format
401 Unauthorized - Invalid API key
500 Internal Server Error - Server error

Domain Schema

Domain Object

Field	Type	Description
`id`	string	Unique identifier for the domain
`name`	string	Domain name (e.g., "example.com")
`teamId`	string	Team/organization ID
`status`	string	Verification status (see Domain Status below)
`region`	string	AWS region (default: "us-east-1")
`clickTracking`	boolean	Whether click tracking is enabled
`openTracking`	boolean	Whether open tracking is enabled
`publicKey`	string	DKIM public key
`dkimStatus`	string \| null	DKIM verification status
`spfDetails`	string \| null	SPF record details
`createdAt`	string	ISO 8601 timestamp of creation
`updatedAt`	string	ISO 8601 timestamp of last update
`dmarcAdded`	boolean	Whether DMARC record has been configured
`isVerifying`	boolean	Whether verification is in progress
`errorMessage`	string \| null	Error message if verification failed
`subdomain`	string \| null	Subdomain configuration
`verificationError`	string \| null	Detailed verification error
`lastCheckedTime`	string \| null	ISO 8601 timestamp of last verification check
`dnsRecords`	array	Array of DNS records (see DNS Record Schema)

DNS Record Schema

Field	Type	Description
`type`	string	DNS record type ("MX" or "TXT")
`name`	string	DNS record name/host
`value`	string	DNS record value/content
`ttl`	string	Time to live (usually "Auto")
`priority`	string \| null	Priority for MX records
`status`	string	Verification status of this record
`recommended`	boolean	Whether this record is recommended

Domain Status

Status Codes

NOT_STARTED - Domain added but DNS records not yet configured
PENDING - DNS records are being verified
SUCCESS - Domain fully verified and ready for sending emails
FAILED - DNS verification failed permanently
TEMPORARY_FAILURE - Temporary DNS issues, verification will retry automatically

DNS Configuration Guide

Step-by-Step Setup

Create the domain via API

Use the POST /v1/domains endpoint to register your domain. This generates the necessary DNS records.

curl -X POST https://api.unsent.dev/v1/domains \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "yourdomain.com",
    "region": "us-east-1"
  }'

Add DNS records

Add the DNS records from the response to your domain's DNS settings (via your domain registrar or DNS provider). The response includes:

Verification TXT Record - Proves you own the domain
SPF TXT Record - Authorizes Unsent to send on your behalf
DKIM TXT Record - Enables email authentication
DMARC TXT Record (optional but recommended) - Email policy enforcement

Trigger verification

Once DNS records are added, trigger verification:

curl -X PUT https://api.unsent.dev/v1/domains/{domainId}/verify \
  -H "Authorization: Bearer your-api-key"

Monitor verification status

Check the domain status periodically:

curl -X GET https://api.unsent.dev/v1/domains/{domainId} \
  -H "Authorization: Bearer your-api-key"

Wait until status becomes "SUCCESS" before sending emails.

Required DNS Records

Verification TXT Record

Name: _amazonses.yourdomain.com
Type: TXT
Value: [verification token from API response]

SPF TXT Record

Name: yourdomain.com
Type: TXT
Value: v=spf1 include:amazonses.com ~all

DKIM TXT Record

Name: [dkim selector]._domainkey.yourdomain.com
Type: TXT
Value: k=rsa; p=[public key from API response]

DMARC TXT Record (recommended)

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

API Key Domain Restrictions

Some API keys may be restricted to specific domains for security purposes. When using a domain-restricted API key:

GET /v1/domains - Returns only the allowed domain
GET /v1/domains/{id} - Returns 404 if requesting a different domain
PUT /v1/domains/{id}/verify - Returns 403 if verifying a different domain
DELETE /v1/domains/{id} - Returns 403 if deleting a different domain

Supported Regions

Region Code	Region Name
`us-east-1`	US East (N. Virginia)

[!NOTE] Additional regions may be supported in the future. Contact support for region-specific requirements.

Best Practices

Use a subdomain for transactional emails
Keep your main domain reputation separate by using something like mail.yourdomain.com
Configure all recommended DNS records
Include DKIM, SPF, and DMARC for maximum deliverability
Monitor domain health regularly
Check the status field and dnsRecords array periodically
Enable tracking thoughtfully
Set clickTracking and openTracking based on your use case and privacy requirements
Test before production
Send test emails to various providers (Gmail, Outlook, etc.) before going live
Maintain DNS records
Keep DNS records up-to-date and monitor for unauthorized changes
Start with low volume
Build sender reputation gradually by starting with smaller email volumes

Common Issues & Troubleshooting

Domain stuck in PENDING status

Cause: DNS propagation delays or misconfigured records

Solution:

Verify DNS records are correctly configured
Wait 24-48 hours for DNS propagation
Use dig or online DNS lookup tools to verify records
Retry verification using PUT /v1/domains/{id}/verify

Verification fails with TEMPORARY_FAILURE

Cause: Temporary DNS resolution issues

Solution:

Wait a few minutes and the system will automatically retry
Check your domain's DNS server is responding

403 Forbidden errors

Cause: API key is restricted to a different domain

Solution:

Verify you're using the correct API key
Check which domain your API key has access to
Contact your team admin to adjust API key permissions

Security Considerations

[!CAUTION]

Only add domains you own and control

Keep DNS records secure and monitor for unauthorized changes

Rotate domain verification tokens if compromised

Use HTTPS/TLS for all API communications

Audit API key permissions regularly

Domains

Overview

Base URL

Features

Add sending domains

Domain verification

DNS management

Domain monitoring

Regional settings

Tracking options

Endpoints

List All Domains

Get Domain by ID

Create Domain

Verify Domain

Delete Domain

Get Domain Analytics

Get Domain Stats

Domain Schema

Domain Object

DNS Record Schema

Domain Status

DNS Configuration Guide

Step-by-Step Setup

Create the domain via API

Add DNS records

Trigger verification

Monitor verification status

Required DNS Records

API Key Domain Restrictions

Supported Regions

Best Practices

Common Issues & Troubleshooting

Domain stuck in PENDING status

Verification fails with TEMPORARY_FAILURE

403 Forbidden errors

Security Considerations

OpenAPI Specification

On this page