---
title: "Add receiving domain"
method: POST
path: "/receiving-domains"
tags: ["Receiving Domains"]
---

# Add receiving domain

`POST /receiving-domains`

## Request

- Base URL: `https://api.sequenzy.com/api/v1`
- URL: `https://api.sequenzy.com/api/v1/receiving-domains`
- Auth: HTTP bearer

Adds your workspace's receiving domain, a domain or subdomain whose mail should reach your Inbox, and returns the DNS records to publish. A workspace has one receiving domain. Once it is verified, replies to emails from all your sending domains come back to reply addresses on it, and its first verification turns Inbox on; until then replies use inbound.sequenzy.com. Mail for a domain goes wherever its MX records point, so a domain whose MX records already point at another mail service (Google Workspace, Microsoft 365, Cloudflare Email Routing) is refused: use a subdomain such as support.acme.com instead. When the workspace already has a receiving domain, a different name is refused with limit_reached before any DNS lookup. Adding a name this workspace already has returns it unchanged with created false, without checking its MX records again, so retries are safe. Adding the first receiving domain also sets the company's reply domain mode to custom. Requires the websites:write scope and owner or admin access.

## Request body

- object
  - `domain` string, required: Domain or subdomain you own, such as acme.com or support.acme.com. Case and a trailing dot are ignored.

## Response `200`

This workspace already has the domain; returned unchanged

- ReceivingDomainCreateResponse
  - `success` boolean, required
  - `created` boolean, required: True when the domain was added; false when this workspace already had it.
  - `receivingDomain` ReceivingDomain, required: A domain or subdomain whose mail reaches your Inbox, such as acme.com or support.acme.com. Every address on it lands in Inbox. Once it is verified, replies to emails you send from any of your sending domains come back to reply addresses on it.
    - `id` string, required
    - `domain` string, required: Lowercase domain name without a trailing dot.
    - `status` 'pending' | 'verified' | 'failed', required: verified: mail arrives and new reply addresses use the domain. pending: waiting for the DNS records; a newly added name stays reserved for your workspace for 7 days. failed: the domain was set up and something broke, or its 7-day reservation ran out before the records were found; mail that still arrives is accepted, and new reply addresses use inbound.sequenzy.com until it is fixed.
    - `records` ReceivingDomainDnsRecord[], required: DNS records to publish. Always the MX record; the TXT record at _amazonses.<domain> is listed only when Amazon SES needs proof that you own the name.
      - `type` 'MX' | 'TXT', required
      - `name` string, required: Fully qualified record name.
      - `value` string, required
      - `priority` integer: MX records only.
      - `status` 'pending' | 'verified' | 'misconfigured', required: misconfigured (MX only) means the name also has MX records for another mail service, which would split its mail.
    - `error` string, nullable, required: What to fix, when known. Always null while verified.
    - `claimExpiresAt` string, date-time, nullable, required: When a new domain that has never verified stops being reserved for your workspace, after which another workspace may add it. Null once verified, and for domains moved over from an earlier reply setup.
    - `verifiedAt` string, date-time, nullable, required: When the domain first verified.
    - `lastCheckedAt` string, date-time, nullable, required
    - `createdAt` string, date-time, required

## Other responses

- `201`: Receiving domain added
- `400`: Not a valid domain (code invalid_domain), or a Sequenzy domain or an email provider's domain such as gmail.com (code reserved_domain)
- `401`: Unauthorized
- `403`: View-only access, the API key is missing the websites:write scope, or it is a marketer personal key
- `404`: Company not found
- `409`: Another workspace receives on the name or sends from it or a parent domain (code domain_taken), the domain already receives email through another mail service such as Google Workspace or Microsoft 365 (code domain_has_mailbox), or this workspace already has a receiving domain (code limit_reached, checked before the MX lookup)
- `422`: Missing or empty domain
- `503`: The domain's MX records could not be looked up right now (code dns_check_failed). Nothing was added; retry in a minute.

## Changes

- **2026-10-16** `db3873ca3d4d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sequenzy/apis/sequenzy-api/changes/receiving-domains/post.md)

---

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