> ## Documentation Index > Fetch the complete documentation index at: https://docs.openmail.sh/llms.txt > Use this file to discover all available pages before exploring further. # Change custom domain pod scope > Change which pods can create inboxes on a custom domain. Pass `podId: null` to make it account-wide (always allowed), or a pod id to scope it to that pod — allowed only while every inbox on the domain already lives in that pod, since inboxes cannot move between pods. DNS records and verification are untouched. Requires an account-wide API key. ## OpenAPI ````yaml https://api.openmail.sh/openapi.json patch /v1/domains/{id} openapi: 3.0.3 info: title: OpenMail API description: >- Email infrastructure API for AI agents. Create inboxes, send and receive email, and get real-time notifications via webhooks. version: 1.0.0 license: name: Proprietary servers: - url: https://api.openmail.sh security: - bearerAuth: [] tags: - name: pods description: Isolated sub-accounts for your end users or tenants - name: inboxes description: Email inboxes and their webhook configuration - name: domains description: >- Custom domains: add your own sending/receiving domain, publish DNS, and verify it - name: messages description: Sending and listing messages - name: threads description: Conversation threads and read status - name: attachments description: Downloading and extracting text from attachments - name: policy description: >- Correspondent policy — provider-enforced allow/block rules and allowlist mode, scoped per account, pod, or inbox. Account-wide key only. - name: feedback description: Reporting bugs, friction, and feature requests to the OpenMail team paths: /v1/domains/{id}: patch: tags: - domains summary: Change custom domain pod scope description: >- Change which pods can create inboxes on a custom domain. Pass `podId: null` to make it account-wide (always allowed), or a pod id to scope it to that pod — allowed only while every inbox on the domain already lives in that pod, since inboxes cannot move between pods. DNS records and verification are untouched. Requires an account-wide API key. operationId: updateDomain parameters: - schema: type: string in: path name: id required: true requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - podId properties: podId: type: string description: >- Pod to scope the domain to (id or clientId). `null` makes the domain available to all pods. nullable: true responses: '200': description: Scope changed; the returned domain reflects the new `podId` content: application/json: schema: description: Scope changed; the returned domain reflects the new `podId` allOf: - $ref: '#/components/schemas/Domain' '400': description: Pod not found or not yours (`invalid_pod`) content: application/json: schema: description: Pod not found or not yours (`invalid_pod`) allOf: - $ref: '#/components/schemas/Error' '403': description: The API key is scoped and cannot change domain scope (`forbidden`) content: application/json: schema: description: >- The API key is scoped and cannot change domain scope (`forbidden`) allOf: - $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: description: Not found allOf: - $ref: '#/components/schemas/Error' '409': description: >- Inboxes on this domain live outside the target pod (`domain_has_inboxes`); the body includes `outsideCount` content: application/json: schema: description: >- Inboxes on this domain live outside the target pod (`domain_has_inboxes`); the body includes `outsideCount` allOf: - $ref: '#/components/schemas/Error' components: schemas: Domain: type: object additionalProperties: true properties: id: type: string description: OpenMail domain ID domain: type: string description: >- The domain or subdomain, e.g. `example.com` or `agent-mail.example.com`. podId: type: string description: >- Pod this domain is scoped to, so only inboxes in that pod can use it, or null for an account-wide domain. nullable: true status: type: string enum: - pending - verifying - verified - failed - under_review description: >- `pending` — added, records not yet published. `verifying` — being checked. `verified` — sending and receiving enabled. `failed` — records missing or wrong; publishing them and calling verify again is the fix. `under_review` — flagged as suspicious; DNS setup is blocked until approved. records: type: array items: $ref: '#/components/schemas/DomainRecord' description: >- The DNS records to publish for this domain. Returned even where the values are the same for every customer, so sending infrastructure can change without breaking clients. warnings: type: array items: $ref: '#/components/schemas/DomainWarning' description: >- Problems detected in the domain's DNS that do not block verification but do lose mail. Empty when none. Check this even when `status` is `verified` — every record can be correct and the zone still broken by something else in it. verifiedAt: type: string format: date-time nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time Error: type: object additionalProperties: true properties: error: type: string message: type: string DomainRecord: type: object additionalProperties: true description: >- A single DNS record to publish for a custom domain. Publish every record whose `status` is not already `valid`, then the domain verifies automatically within a couple of minutes. properties: type: type: string enum: - TXT - CNAME - MX name: type: string description: >- The record's host, fully qualified, e.g. `_dmarc.agent-mail.example.com`. value: type: string description: The record value to publish. priority: type: integer description: MX records only. nullable: true purpose: type: string enum: - spf - dkim - dmarc - mx - return-path description: >- What the record is for. Act on this rather than inferring from record shape: SPF must be merged into any the owner already has rather than replacing it, a DMARC policy at an apex can override the owner's own, and an apex MX takes over all their inbound mail. status: type: string enum: - missing - invalid - valid description: >- Whether this individual record is published and correct as of the last check. `missing` — not found yet. `invalid` — found but wrong. `valid` — published and correct. Shows which records are still outstanding, not only whether the whole domain passed. DomainWarning: type: object properties: code: type: string enum: - competing_mx description: >- `competing_mx` — another MX record is published at the same or a more preferred priority than ours, so senders split the domain's inbound mail between us and a server that does not know its inboxes. Part of the mail bounces `550` while every record shows `valid`. Fix: remove the other MX, or give it a higher priority number than ours. message: type: string description: >- Human-readable explanation and fix, safe to show to the domain owner. hosts: type: array items: type: string description: The competing MX hosts, lowercase, without trailing dot. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.