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

const inbound = new InboundEmailClient('YOUR_API_KEY');

const { data, error } = await inbound.domain.update('dom_abc123', {
  isCatchAllEnabled: true,
  catchAllEndpointId: 'end_xyz789'
});

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

{
  "id": "dom_abc123",
  "domain": "example.com",
  "status": "verified",
  "isCatchAllEnabled": true,
  "catchAllEndpointId": "end_xyz789",
  "catchAllEndpoint": {
    "id": "end_xyz789",
    "name": "Main Webhook",
    "type": "webhook",
    "isActive": true
  },
  "receiptRuleName": "example.com-catchall-rule",
  "updatedAt": "2024-01-15T10:30:00Z"
}

​
Overview

This endpoint allows you to enable or disable catch-all email forwarding for a domain. When enabled, all emails sent to any address on the domain (including non-existent ones) will be forwarded to the specified endpoint.
This endpoint can only be used with verified domains. Domains in pending or failed status cannot have catch-all enabled.

​
Authentication

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

​
Parameters

​
id
string
required
The unique identifier of the domain to update.
​
isCatchAllEnabled
boolean
required
Whether to enable or disable catch-all email forwarding for this domain.
​
catchAllEndpointId
string | null
The ID of the endpoint to use for catch-all email forwarding. Required when isCatchAllEnabled is true. Set to null when disabling catch-all.

​
Response

​
id
string
required
Unique identifier for the domain.
​
domain
string
required
The domain name (e.g., “example.com”).
​
status
string
required
Current verification status: pending, verified, or failed.
​
isCatchAllEnabled
boolean
required
Whether catch-all email forwarding is enabled for this domain.
​
catchAllEndpointId
string | null
ID of the endpoint used for catch-all email forwarding.
​
catchAllEndpoint
object | null
Information about the catch-all endpoint (if configured).
​
receiptRuleName
string | null
Name of the AWS SES receipt rule created for this catch-all configuration.
​
awsConfigurationWarning
string
Warning message if there were issues with AWS SES configuration.
​
updatedAt
string
required
ISO 8601 timestamp when the domain was last updated.

​
Examples

​
Enable Catch-All

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

const inbound = new InboundEmailClient('YOUR_API_KEY');

const { data, error } = await inbound.domain.update('dom_abc123', {
  isCatchAllEnabled: true,
  catchAllEndpointId: 'end_xyz789'
});

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

​
Disable Catch-All

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

const inbound = new InboundEmailClient('YOUR_API_KEY');

const { data, error } = await inbound.domain.update('dom_abc123', {
  isCatchAllEnabled: false,
  catchAllEndpointId: null
});

if (error) {
  console.error('Error:', error);
} else {
  console.log('Catch-all disabled:', data);
}

​
Success Response

{
  "id": "dom_abc123",
  "domain": "example.com",
  "status": "verified",
  "isCatchAllEnabled": true,
  "catchAllEndpointId": "end_xyz789",
  "catchAllEndpoint": {
    "id": "end_xyz789",
    "name": "Main Webhook",
    "type": "webhook",
    "isActive": true
  },
  "receiptRuleName": "example.com-catchall-rule",
  "updatedAt": "2024-01-15T10:30:00Z"
}

​
Error Responses

{
  "error": "Domain must be verified before configuring catch-all"
}

​
Important Notes

When catch-all is enabled, it configures AWS SES receipt rules to forward all emails to the specified endpoint. This includes emails to non-existent addresses on your domain.
Enabling catch-all will remove any existing individual email receipt rules for this domain to prevent conflicts. When disabling catch-all, individual email rules will be restored automatically.
The endpoint you specify must be active and belong to your account. We recommend using webhook endpoints for catch-all forwarding as they provide the most flexibility.

​
Behavior Details

​
When Enabling Catch-All:

  1. The system validates that the domain is verified
  2. The specified endpoint is validated to ensure it exists and is active
  3. AWS SES receipt rules are configured to forward all emails to the endpoint
  4. Any existing individual email rules for this domain are removed to prevent conflicts
  5. The domain’s catch-all configuration is updated in the database

​
When Disabling Catch-All:

  1. AWS SES catch-all receipt rules are removed
  2. Individual email rules for existing email addresses are restored
  3. The domain’s catch-all configuration is cleared in the database

​
AWS SES Integration:

  • Receipt rules are created using the domain name (e.g., example.com-catchall-rule)
  • AWS SES uses the domain name pattern to catch all emails to that domain
  • If AWS configuration is incomplete, the database will still be updated but no receipt rules will be created
1.0 - ✅