Skip to main content
GET
/
api
/
v2
/
domains
import { Inbound } from '@inboundemail/sdk'

const inbound = new Inbound('YOUR_API_KEY')

const { data: domains, error } = await inbound.domain.list()
if (error) {
  console.error('Error:', error)
} else {
  console.log('Domains:', domains.data)
}

{
  "data": [
    {
      "id": "dom_abc123",
      "domain": "example.com",
      "status": "verified",
      "canReceiveEmails": true,
      "hasMxRecords": true,
      "domainProvider": "Cloudflare",
      "providerConfidence": "high",
      "lastDnsCheck": "2024-01-15T10:30:00Z",
      "lastSesCheck": "2024-01-15T10:30:00Z",
      "isCatchAllEnabled": true,
      "catchAllEndpointId": "end_xyz789",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "userId": "user_123",
      "stats": {
        "totalEmailAddresses": 5,
        "activeEmailAddresses": 4,
        "hasCatchAll": true
      },
      "catchAllEndpoint": {
        "id": "end_xyz789",
        "name": "Main Webhook",
        "type": "webhook",
        "isActive": true
      },
      "verificationCheck": {
        "dnsRecords": [
          {
            "type": "TXT",
            "name": "_amazonses.example.com",
            "value": "abc123def456ghi789",
            "isVerified": true
          },
          {
            "type": "MX",
            "name": "example.com",
            "value": "10 inbound-smtp.us-east-1.amazonaws.com",
            "isVerified": true
          }
        ],
        "sesStatus": "Success",
        "isFullyVerified": true,
        "lastChecked": "2024-01-15T10:30:00Z"
      }
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "hasMore": false
  },
  "meta": {
    "totalCount": 1,
    "verifiedCount": 1,
    "withCatchAllCount": 1,
    "statusBreakdown": {
      "verified": 1,
      "pending": 0,
      "failed": 0
    }
  }
}

​
Overview

This endpoint retrieves a paginated list of all domains associated with the authenticated user. It supports filtering by domain status and whether domains can receive emails, with optional real-time verification checks.

​
Authentication

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

​
Parameters

​
limit
integer
default:"50"
Maximum number of domains to return. Range: 1-100.
​
offset
integer
default:"0"
Number of domains to skip for pagination. Must be non-negative.
​
status
string
Filter domains by verification status. Valid values: pending, verified, failed.
​
canReceive
string
Filter domains by email receiving capability. Valid values: true, false.
​
check
string
Perform real-time DNS and SES verification checks. Set to true to include verification status in response. This may slow down the response but provides current verification status.

​
Response

​
data
array
required
Array of domain objects with detailed information and statistics.
​
pagination
object
required
Pagination information for the result set.
​
meta
object
required
Summary statistics about the user’s domains.

​
Examples

​
Basic Request

import { Inbound } from '@inboundemail/sdk'

const inbound = new Inbound('YOUR_API_KEY')

const { data: domains, error } = await inbound.domain.list()
if (error) {
  console.error('Error:', error)
} else {
  console.log('Domains:', domains.data)
}

​
Filtered Request with Verification Check

import { Inbound } from '@inboundemail/sdk'

const inbound = new Inbound('YOUR_API_KEY')

const { data: domains, error } = await inbound.domain.list({
  status: 'verified',
  check: 'true',
  limit: 10
})
if (error) {
  console.error('Error:', error)
} else {
  console.log('Verified domains:', domains.data)
}

​
Response Example (with Verification Check)

{
  "data": [
    {
      "id": "dom_abc123",
      "domain": "example.com",
      "status": "verified",
      "canReceiveEmails": true,
      "hasMxRecords": true,
      "domainProvider": "Cloudflare",
      "providerConfidence": "high",
      "lastDnsCheck": "2024-01-15T10:30:00Z",
      "lastSesCheck": "2024-01-15T10:30:00Z",
      "isCatchAllEnabled": true,
      "catchAllEndpointId": "end_xyz789",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "userId": "user_123",
      "stats": {
        "totalEmailAddresses": 5,
        "activeEmailAddresses": 4,
        "hasCatchAll": true
      },
      "catchAllEndpoint": {
        "id": "end_xyz789",
        "name": "Main Webhook",
        "type": "webhook",
        "isActive": true
      },
      "verificationCheck": {
        "dnsRecords": [
          {
            "type": "TXT",
            "name": "_amazonses.example.com",
            "value": "abc123def456ghi789",
            "isVerified": true
          },
          {
            "type": "MX",
            "name": "example.com",
            "value": "10 inbound-smtp.us-east-1.amazonaws.com",
            "isVerified": true
          }
        ],
        "sesStatus": "Success",
        "isFullyVerified": true,
        "lastChecked": "2024-01-15T10:30:00Z"
      }
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "hasMore": false
  },
  "meta": {
    "totalCount": 1,
    "verifiedCount": 1,
    "withCatchAllCount": 1,
    "statusBreakdown": {
      "verified": 1,
      "pending": 0,
      "failed": 0
    }
  }
}

​
Error Responses

{
  "error": "Limit must be between 1 and 100"
}

​
Important Notes

The check=true parameter performs real-time DNS and SES verification checks, which may slow down the response but provides the most current verification status.
Use the check=true parameter when you need to verify the current status of domains, especially after making DNS changes or when troubleshooting verification issues.
The verificationCheck field is only included when check=true is specified. This parameter may increase response time as it performs live DNS lookups and AWS SES API calls.

​
Notes

  • The catchAllEndpoint field is only populated when isCatchAllEnabled is true and a valid endpoint is configured
  • Domain statistics are calculated in real-time and may impact response performance for users with many domains
  • The providerConfidence field indicates how certain the system is about the detected domain provider
  • Domains in pending status are still undergoing verification and cannot receive emails yet
  • When check=true is used, the domain status may be automatically updated based on current SES verification status

​
Verification Status

1.0 - ✅