POST
/
api
/
v2
/
domains
import { InboundEmailClient } from '@inboundemail/sdk';

const inbound = new InboundEmailClient('YOUR_API_KEY');

const { data, error } = await inbound.domain.create({
  domain: 'example.com'
});

if (error) {
  console.error('Error:', error);
} else {
  console.log('Domain created:', data);
}

{
  "id": "dom_abc123",
  "domain": "example.com",
  "status": "pending",
  "canReceiveEmails": true,
  "hasMxRecords": false,
  "domainProvider": "Cloudflare",
  "providerConfidence": "high",
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "_amazonses.example.com",
      "value": "abc123def456ghi789jkl",
      "isRequired": true
    },
    {
      "type": "MX",
      "name": "example.com",
      "value": "10 inbound-smtp.us-east-1.amazonaws.com",
      "isRequired": true
    },
    {
      "type": "TXT",
      "name": "example.com",
      "value": "v=spf1 include:amazonses.com ~all",
      "isRequired": false
    },
    {
      "type": "TXT",
      "name": "_dmarc.example.com",
      "value": "v=DMARC1; p=none; rua=mailto:dmarc@example.com; ruf=mailto:dmarc@example.com; fo=1; aspf=r; adkim=r",
      "isRequired": false
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

​
Overview

This endpoint adds a new domain to your account for email receiving. It performs DNS validation, checks domain limits, and initiates AWS SES verification automatically.
The domain must not have existing MX or CNAME records that would conflict with email receiving. The endpoint will check for these conflicts before creating the domain.

​
Authentication

​
Authorization
string
required
Bearer token for API authentication. Format: Bearer YOUR_API_KEY

​
Request Body

​
domain
string
required
The domain name to add (e.g., “example.com”). Must be a valid domain format and not already exist in your account.

​
Response

​
id
string
required
Unique identifier for the newly created domain.
​
domain
string
required
The domain name that was added.
​
status
string
required
Initial verification status: pending, verified, or failed.
​
canReceiveEmails
boolean
required
Whether the domain is configured to receive emails (based on initial DNS check).
​
hasMxRecords
boolean
required
Whether the domain has valid MX records configured.
​
domainProvider
string | null
Detected domain provider (e.g., “Cloudflare”, “GoDaddy”).
​
providerConfidence
string | null
Confidence level of provider detection: high, medium, low.
​
dnsRecords
array
required
Array of DNS records that need to be added to complete verification.
​
createdAt
string
required
ISO 8601 timestamp when the domain was created.
​
updatedAt
string
required
ISO 8601 timestamp when the domain was last updated.

​
Examples

​
Request

import { InboundEmailClient } from '@inboundemail/sdk';

const inbound = new InboundEmailClient('YOUR_API_KEY');

const { data, error } = await inbound.domain.create({
  domain: 'example.com'
});

if (error) {
  console.error('Error:', error);
} else {
  console.log('Domain created:', data);
}

​
Response

{
  "id": "dom_abc123",
  "domain": "example.com",
  "status": "pending",
  "canReceiveEmails": true,
  "hasMxRecords": false,
  "domainProvider": "Cloudflare",
  "providerConfidence": "high",
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "_amazonses.example.com",
      "value": "abc123def456ghi789jkl",
      "isRequired": true
    },
    {
      "type": "MX",
      "name": "example.com",
      "value": "10 inbound-smtp.us-east-1.amazonaws.com",
      "isRequired": true
    },
    {
      "type": "TXT",
      "name": "example.com",
      "value": "v=spf1 include:amazonses.com ~all",
      "isRequired": false
    },
    {
      "type": "TXT",
      "name": "_dmarc.example.com",
      "value": "v=DMARC1; p=none; rua=mailto:dmarc@example.com; ruf=mailto:dmarc@example.com; fo=1; aspf=r; adkim=r",
      "isRequired": false
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

​
Error Responses

{
  "error": "Invalid domain format"
}

​
Domain Verification Process

After creating a domain, you’ll need to complete the verification process:
1

Add DNS Records

Add the DNS records returned in the dnsRecords array to your domain’s DNS configuration. This includes:
  • TXT record for SES domain verification (required)
  • MX record for email routing (required)
  • SPF record for email authentication (recommended)
  • DMARC record for email policy (recommended)
The exact method depends on your DNS provider. Most providers have a DNS management interface where you can add TXT and MX records. While SPF and DMARC records are not required for basic functionality, they significantly improve email deliverability.
2

Wait for Propagation

DNS changes can take up to 24 hours to propagate, but typically complete within 1-2 hours.
You can check the current verification status using the GET endpoint with check=true parameter.
3

Verification Complete

Once all DNS records are verified, the domain status will automatically update to verified and you can start receiving emails.
Verified domains can receive emails and have catch-all forwarding configured.

​
Important Notes

Domain creation includes automatic checks for plan limits using the billing system. If you’ve reached your domain limit, you’ll need to upgrade your plan.
The domain must not have existing MX or CNAME records that would conflict with email receiving. Remove any existing email routing before adding the domain.
Use descriptive domain names and ensure you have admin access to the DNS configuration before adding a domain.
After creating a domain, you might want to:
  • Check verification status: Use GET /api/v2/domains/{id}?check=true
  • Configure catch-all: Use PUT /api/v2/domains/{id}
  • View DNS records: Use GET /api/v2/domains/{id}/dns-records

​
Notes

  • Domain verification is initiated automatically upon creation
  • The dnsRecords array contains all 4 records needed for complete verification and optimal deliverability
  • 2 records (TXT and MX) are required for basic functionality
  • 2 additional records (SPF and DMARC) are recommended for enhanced email authentication
  • Domain limits are checked against your current plan before creation
  • Provider detection helps identify the DNS service for better user guidance
  • All domains start in pending status until required DNS records are verified
1.0 - ✅