> ## Documentation Index > Fetch the complete documentation index at: https://docs.senderkit.com/llms.txt > Use this file to discover all available pages before exploring further. # Claim a custom inbound domain > Claims a domain or subdomain you own for receiving mail. Publish the returned `records`, then poll `GET /v1/inbound/domains/{id}` until `status` is `verified`. Publishing our MX replaces wherever the domain's mail currently goes. If the domain already has a live mail host, this call 409s with `existing_mx` and the current hosts; retry with `acknowledgeExistingMx: true` once you've confirmed the redirect is intended. ## OpenAPI ````yaml https://www.senderkit.com/openapi.yaml post /v1/inbound/domains openapi: 3.1.0 info: title: SenderKit Public API version: 1.0.0 description: > Public REST API for SenderKit — send transactional messages (email, SMS, push, web push), list message history, and read/render templates. ## Authentication All endpoints require a Bearer API key: Authorization: Bearer sk_live_xxx The `sk_live_` / `sk_test_` prefix selects the environment (live vs. test). The prefix is only a hint for humans; the secret is the full token. Keys are created in the dashboard and shown once at creation. ## Sends are asynchronous `POST /v1/send` enqueues the message and returns `202` with `status: "queued"`. Delivery happens out of band; poll `GET /v1/messages` to observe progress. ## Rate limits All endpoints are rate limited per API key. Sends and reads count against separate budgets, so listing messages never competes with sending them. A `429` response includes a `Retry-After` header (seconds). servers: - url: https://api.senderkit.com description: Production - url: http://localhost:3000/api description: Local development security: - apiKey: [] tags: - name: Context description: Inspect the workspace and environment an API key operates in. - name: Send description: Dispatch messages. - name: Messages description: Read message history and cancel pending sends. - name: Templates description: Read and render stored templates. - name: Inbound description: | Provision addresses on your workspace's shared receiving domain and read mail sent to them. Requires an API key with the `inbound` scope. paths: /v1/inbound/domains: post: tags: - Inbound summary: Claim a custom inbound domain description: | Claims a domain or subdomain you own for receiving mail. Publish the returned `records`, then poll `GET /v1/inbound/domains/{id}` until `status` is `verified`. Publishing our MX replaces wherever the domain's mail currently goes. If the domain already has a live mail host, this call 409s with `existing_mx` and the current hosts; retry with `acknowledgeExistingMx: true` once you've confirmed the redirect is intended. operationId: createInboundDomain requestBody: required: true content: application/json: schema: type: object required: - domain properties: domain: type: string minLength: 4 maxLength: 253 description: | The domain or subdomain to receive mail on, e.g. `inbound.acme.com`. acknowledgeExistingMx: type: boolean description: | Required to claim a domain that already has a live MX pointing somewhere else — publishing ours would redirect that domain's existing mail. examples: default: value: domain: inbound.acme.com responses: '201': description: The claimed domain, with the DNS records to publish. content: application/json: schema: $ref: '#/components/schemas/InboundDomain' '400': description: Body must be valid JSON (`invalid_request`). content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- The API key is missing the required `inbound` scope (`insufficient_scope`). content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: | You already receive on this domain (`already_exists`), another workspace has already claimed it (`domain_claimed`), or the domain currently has a live MX elsewhere and `acknowledgeExistingMx` was not set — in that case the response also carries `hosts`, the domain's current mail exchangers, so a caller can show them in a confirmation step (`existing_mx`). content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: | Failed body validation (`invalid_body`), or not a domain you can receive on (`invalid_domain`). content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/RateLimited' '503': description: Managed inbound email is not available (`managed_disabled`). content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: InboundDomain: type: object properties: id: type: string format: uuid description: Inbound domain ID (the row's UUID — there is no separate public id). domain: type: string example: inbound.acme.com kind: type: string enum: - shared - custom description: | `shared` is the workspace's auto-provisioned `{slug}.in.senderkit.email` domain, which needs no DNS of its own. `custom` is a domain you claimed and must verify by publishing `records`. status: type: string enum: - pending - verified - failed records: type: array description: | DNS records to publish for this domain to verify. Always empty for `shared` domains — the wildcard MX on the shared domain already covers them. items: type: object required: - type - name - value - purpose - check properties: type: type: string enum: - TXT - MX name: type: string value: type: string priority: type: integer description: Present on `MX` records. purpose: type: string description: Human-readable explanation of what this record does. check: type: string enum: - dkim - inboundMx description: | Identifies which mechanism confirms this record is correctly published. For `dkim` records, confirmation comes from the domain's SES identity verification status. For `inboundMx` records, confirmation comes from a live DNS lookup that finds the MX already pointing at SenderKit's receiving endpoint. verifiedAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Stable machine-readable error code. example: invalid_request message: type: string issues: type: array description: Present on validation failures (Zod issues). items: type: object additionalProperties: true limit: type: integer description: Present on rate-limit errors. responses: Unauthorized: description: Missing, malformed, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Rate limit exceeded. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: http scheme: bearer description: API key with an `sk_live_` or `sk_test_` prefix. ````