---
title: "Enable or disable catch-all for a verified custom domain"
method: PATCH
path: "/domains/{id}/catch_all"
tags: ["domains"]
---

# Enable or disable catch-all for a verified custom domain

`PATCH /domains/{id}/catch_all`

## Request

- Base URL: `https://dash.mailsocket.app/api/v1`
- URL: `https://dash.mailsocket.app/api/v1/domains/{id}/catch_all`
- Auth: HTTP bearer

Business plan only. Enabling requires the domain to be `verified`
(else `409 domain_not_verified`). `inbox_id` is optional: when
omitted, a catch-all inbox is created and bound to the domain
(subject to the plan's inbox cap, else `403 inbox_limit_reached`);
when given, it must be a live inbox already bound to this domain
(else `422 catch_all_target_invalid`, or `404
domain_not_found_or_unverified` if it does not exist / is not
owned by the caller). Disabling keeps the designated inbox bound
(inert while `catch_all` is false) so re-enabling is cheap.
Rate-limited: at most 6 toggle calls per domain per hour
(`429 catch_all_rate_limited`).

## Path parameters

- `id` string, required

## Request body

- object
  - `catch_all` boolean, required
  - `inbox_id` string, nullable: Optional; only meaningful when enabling.

## Response `200`

The domain after the catch-all toggle.

- object
  - `data` Domain, required
    - `id` string, required: The domain public ID.
    - `name` string, required: The FQDN, stored lowercase. Immutable after create.
    - `status` 'pending_dns' | 'verified' | 'failed' | 'disabled', required
    - `verification_txt_host` string, required: The TXT record host to publish (`_mailsocket-verify.<name>`).
    - `verification_token` string, required: The TXT record value to publish at `verification_txt_host`.
    - `mx_target` string, required: The MX target that must be present once DNS is live (`mx.mailsocket.app`).
    - `last_checked_at` string, date-time, nullable, required
    - `last_error` string, required
    - `verified_at` string, date-time, nullable, required
    - `catch_all` boolean: True when unmatched local parts on this (verified) domain route to catch_all_inbox_id. Toggled via `PATCH /domains/{id}/catch_all`.
    - `catch_all_inbox_id` string, nullable: The catch-all inbox's public ID, or null when catch-all has never been configured.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `401`: Missing or invalid API key.
- `403`: Account forbidden, BYOD disabled (`byod_disabled`), or the plan does not include catch-all (`catch_all_entitlement_required`), or the plan's inbox limit is reached (`inbox_limit_reached`).
- `404`: Resource not found (unknown or not owned).
- `409`: Domain is not verified (`domain_not_verified`), or the designated inbox is the active catch-all target and cannot be reused this way (`catch_all_target`).
- `422`: The designated inbox_id is not a live inbox bound to this domain (`catch_all_target_invalid`).
- `429`: Catch-all toggle rate limit exceeded (`catch_all_rate_limited`).

---

[API](https://skmtc.dev/mailsocket/apis/mailsocket-api.md) · [All operations](https://skmtc.dev/mailsocket/apis/mailsocket-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailsocket/apis/mailsocket-api/revisions/e579500dfb7e?raw)