> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Receiving Domain

> Receive mail for a domain or subdomain in your Inbox

Add your workspace's receiving domain, a domain or subdomain whose mail should
reach your Inbox such as `support.acme.com`, and get the DNS records to
publish. Once the records are found, every address on the domain lands in your
Inbox, and replies to emails from all your sending domains come back to reply
addresses on it, the same way your tracking domain serves every sending
domain. Until then, replies keep using `inbound.sequenzy.com`. The first
verification also turns Inbox on.

A workspace has one receiving domain. To use a different one, remove the
current one first.

<Warning>
  Mail for a domain goes wherever its MX records point, for every address at
  once. If the domain already receives email somewhere else, such as Google
  Workspace, Microsoft 365 or Cloudflare Email Routing, the request is refused
  with `domain_has_mailbox`, because receiving it here would break that mailbox.
  Use a subdomain such as `support.acme.com` instead, which leaves your existing
  mailboxes on `acme.com` untouched. If the MX lookup gets no answer, the
  request fails with `503` and `dns_check_failed`; try again in a minute.
</Warning>

Publish the returned records with your DNS provider. The MX record is always
listed. A TXT record at `_amazonses.<domain>` is listed too when Amazon SES
needs proof that you own the name. Sequenzy then checks the domain
automatically, or you can check right away with [Verify Receiving
Domain](./verify).

When the name is also one of your sending domains, no TXT record is listed:
the sending domain's own Amazon SES verification covers it, so receiving
starts once that sending domain is verified. If `error` says the domain can't
receive because of how it is set up for sending, receive on a subdomain such
as `support.acme.com` instead.

A new name is reserved for your workspace for 7 days (`claimExpiresAt`). If the
records are not found by then, another workspace may add the name, which
removes it from yours.

Adding a name this workspace already has returns it unchanged with
`created: false` and HTTP 200, without checking its MX records again, so
retries are safe. Adding your first receiving domain also sets the company's
`replyTrackingDomainMode` to `custom`, so reply addresses use your receiving
domain once it is verified.

Requires the `websites:write` scope and owner or admin access.

CLI: `sequenzy receiving-domains add support.acme.com`. MCP:
`add_receiving_domain`.

## Request

<ParamField body="domain" type="string" required>
  A domain or subdomain you own, such as `acme.com` or `support.acme.com`. Case
  and a trailing dot are ignored. Sequenzy's own domains and email providers'
  domains such as `gmail.com` can't be added.
</ParamField>

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/receiving-domains" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "support.acme.com"}'
```

## Response fields

<ResponseField name="created" type="boolean">
  `true` when the domain was added (HTTP 201), `false` when this workspace
  already had it (HTTP 200).
</ResponseField>

<ResponseField name="receivingDomain" type="object">
  The receiving domain, with the fields described in [Get Receiving
  Domain](./get).
</ResponseField>

## Responses

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "created": true,
    "receivingDomain": {
      "id": "k3x9rd2m8q1pz7w4v6n0b5c",
      "domain": "support.acme.com",
      "status": "pending",
      "records": [
        {
          "type": "MX",
          "name": "support.acme.com",
          "value": "inbound-smtp.us-east-1.amazonaws.com",
          "priority": 10,
          "status": "pending"
        },
        {
          "type": "TXT",
          "name": "_amazonses.support.acme.com",
          "value": "pmBGN/7MjnfhTKUZ06Enqq1PeGUaOkw8lGhcfwefcHU=",
          "status": "pending"
        }
      ],
      "error": null,
      "claimExpiresAt": "2026-10-17T09:00:00.000Z",
      "verifiedAt": null,
      "lastCheckedAt": "2026-10-10T09:00:00.000Z",
      "createdAt": "2026-10-10T09:00:00.000Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": "Enter a domain you own, such as acme.com or support.acme.com.",
    "code": "invalid_domain"
  }
  ```

  ```json 400 theme={null}
  {
    "error": "gmail.com belongs to an email provider. Use a domain you own.",
    "code": "reserved_domain"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "You have view-only access to this company. Contact the owner to request edit permissions."
  }
  ```

  ```json 409 theme={null}
  {
    "error": "support.acme.com is already used by another workspace.",
    "code": "domain_taken"
  }
  ```

  ```json 409 theme={null}
  {
    "error": "acme.com already receives email through Google Workspace, so we can't receive it here without breaking that mailbox. Use a subdomain such as support.acme.com, or another domain you own.",
    "code": "domain_has_mailbox"
  }
  ```

  ```json 409 theme={null}
  {
    "error": "A workspace has one receiving domain. Remove it first to use a different one.",
    "code": "limit_reached"
  }
  ```

  ```json 503 theme={null}
  {
    "error": "We couldn't check where acme.com receives email right now. Try again in a minute.",
    "code": "dns_check_failed"
  }
  ```
</ResponseExample>

A name is `domain_taken`, always with the same message, when another workspace
receives on it, receives or sends on a parent domain (for example `acme.com` for
`support.acme.com`), or still receives on it through a sending domain set up
before receiving domains. Another workspace's claim that never verified stops
counting after 7 days.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.