---
title: Update domain receiving
openapi: /openapi/mailfully.yaml PATCH /v1/domains/{id}
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

`PATCH https://api.mailfully.com/v1/domains/{id}`

Turn receiving on or off for a domain. The body takes exactly one field, `receiving`; any other field, or none, is a `422`.

Turning receiving on requires a `verified` domain (`409 domain_not_verified`) and looks up the domain's current MX records first. If any of them points at another mail provider, the request is refused with `409 mx_conflict` and nothing changes: receive on a subdomain such as `inbound.<domain>` instead, added as a new domain. A failed lookup returns `503 dns_lookup_failed`. On success the response includes the receiving MX record to publish at the domain name.

Turning receiving off is always allowed. Repeating the current state is a no-op `200` that runs no checks and no DNS lookup. Requires the `send` scope.

## Authentication

- `apiKey` — http bearer

## Path parameters

- `id` (string, required) — The domain id (`dom_…`).

## Request body

- Content type: `application/json`
  - request body (object)
    - `receiving` (boolean, required) — Turn receiving on (`true`) or off (`false`).

## Response 200

The domain with its full DNS record set.
  - response
    - (allOf)
      - value
        - (allOf)
          - value (object)
            - object: … (nested further)
            - id: … (nested further)
            - name: … (nested further)
            - region: … (nested further)
            - mail_from_subdomain: … (nested further)
            - dkim_tokens: … (nested further)
            - dkim_status: … (nested further)
            - mail_from_status: … (nested further)
            - dmarc_status: … (nested further)
            - tracking_status: … (nested further)
            - tracking_enabled: … (nested further)
            - config_set: … (nested further)
            - status: … (nested further)
            - created_at: … (nested further)
            - receiving: … (nested further)
          - value (object)
            - records: … (nested further)
      - value (object)
        - `receiving_enabled_at` (string, date-time, required) — When receiving was last turned on; `null` while it is off.

## Response 401

Authentication failed.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.

## Response 403

The credential is valid but not permitted.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.

## Response 404

The requested resource was not found.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.

## Response 409

Receiving cannot be turned on for this domain.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.

## Response 422

The request failed validation.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.

## Response 500

An unexpected error occurred.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.

## Response 503

The MX lookup failed; nothing was changed.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.


---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://mailfully.com/docs/api-specs.zip