--- title: "Add a sending domain" method: POST path: "/tenants/{tenantId}/domains" tags: ["Domains"] --- # Add a sending domain `POST /tenants/{tenantId}/domains` ## Request - Base URL: `https://api.arkhq.io/v1` - URL: `https://api.arkhq.io/v1/tenants/{tenantId}/domains` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Add a new sending domain to a tenant. Returns DNS records that must be configured before the domain can be verified. Each tenant gets their own isolated mail server for domain isolation. **Required DNS records:** - **SPF** - TXT record for sender authentication - **DKIM** - TXT record for email signing - **Return Path** - CNAME for bounce handling After adding DNS records, call `POST /tenants/{tenantId}/domains/{domainId}/verify` to verify. ## Path parameters - `tenantId` string, required ## Request body - object - `name` string, required: Domain name (e.g., "mail.example.com") ## Response `200` Domain added - DomainResponse - `success` true, required - `data` object, required - `id` integer, required: Unique domain identifier - `uuid` string, uuid, required: UUID of the domain - `name` string, required: The domain name used for sending emails - `verified` boolean, required: Whether all DNS records (SPF, DKIM, Return Path) are correctly configured. Domain must be verified before sending emails. - `verifiedAt` string, date-time, nullable: Timestamp when the domain ownership was verified, or null if not yet verified - `dnsRecords` object, nullable, required: DNS records that must be added to your domain's DNS settings. Null if records are not yet generated. **Important:** The `name` field contains the relative hostname that you should enter in your DNS provider. Most DNS providers auto-append the zone name, so you only need to enter the relative part. For subdomains like `mail.example.com`, the zone is `example.com`, so: - SPF `name` would be `mail` (not `@`) - DKIM `name` would be `ark-xyz._domainkey.mail` - Return Path `name` would be `psrp.mail` - `zone` string: The DNS zone (registrable domain) where records should be added. This is the root domain that your DNS provider manages. For `mail.example.com`, the zone is `example.com`. For `example.co.uk`, the zone is `example.co.uk`. - `spf` DnsRecord: A DNS record that needs to be configured in your domain's DNS settings. The `name` field contains the relative hostname to enter in your DNS provider (which auto-appends the zone). The `fullName` field contains the complete fully-qualified domain name (FQDN) for reference. **Example for subdomain `mail.example.com`:** - `name`: `"mail"` (what you enter in DNS provider) - `fullName`: `"mail.example.com"` (the complete hostname) **Example for root domain `example.com`:** - `name`: `"@"` (DNS shorthand for apex/root) - `fullName`: `"example.com"` - `type` 'TXT' | 'CNAME' | 'MX', required: The DNS record type to create - `name` string, required: The relative hostname to enter in your DNS provider. Most DNS providers auto-append the zone name, so you only need to enter this relative part. - `"@"` means the apex/root of the zone (for root domains) - `"mail"` for a subdomain like `mail.example.com` - `"ark-xyz._domainkey.mail"` for DKIM on a subdomain - `fullName` string, required: The complete fully-qualified domain name (FQDN). Use this as a reference to verify the record is configured correctly. - `value` string, required: The value to set for the DNS record - `status` 'OK' | 'Missing' | 'Invalid' | 'null', nullable: Current verification status of this DNS record: - `OK` - Record is correctly configured and verified - `Missing` - Record was not found in your DNS - `Invalid` - Record exists but has an incorrect value - `null` - Record has not been checked yet - `dkim` DnsRecord: A DNS record that needs to be configured in your domain's DNS settings. The `name` field contains the relative hostname to enter in your DNS provider (which auto-appends the zone). The `fullName` field contains the complete fully-qualified domain name (FQDN) for reference. **Example for subdomain `mail.example.com`:** - `name`: `"mail"` (what you enter in DNS provider) - `fullName`: `"mail.example.com"` (the complete hostname) **Example for root domain `example.com`:** - `name`: `"@"` (DNS shorthand for apex/root) - `fullName`: `"example.com"` - `type` 'TXT' | 'CNAME' | 'MX', required: The DNS record type to create - `name` string, required: The relative hostname to enter in your DNS provider. Most DNS providers auto-append the zone name, so you only need to enter this relative part. - `"@"` means the apex/root of the zone (for root domains) - `"mail"` for a subdomain like `mail.example.com` - `"ark-xyz._domainkey.mail"` for DKIM on a subdomain - `fullName` string, required: The complete fully-qualified domain name (FQDN). Use this as a reference to verify the record is configured correctly. - `value` string, required: The value to set for the DNS record - `status` 'OK' | 'Missing' | 'Invalid' | 'null', nullable: Current verification status of this DNS record: - `OK` - Record is correctly configured and verified - `Missing` - Record was not found in your DNS - `Invalid` - Record exists but has an incorrect value - `null` - Record has not been checked yet - `returnPath` DnsRecord: A DNS record that needs to be configured in your domain's DNS settings. The `name` field contains the relative hostname to enter in your DNS provider (which auto-appends the zone). The `fullName` field contains the complete fully-qualified domain name (FQDN) for reference. **Example for subdomain `mail.example.com`:** - `name`: `"mail"` (what you enter in DNS provider) - `fullName`: `"mail.example.com"` (the complete hostname) **Example for root domain `example.com`:** - `name`: `"@"` (DNS shorthand for apex/root) - `fullName`: `"example.com"` - `type` 'TXT' | 'CNAME' | 'MX', required: The DNS record type to create - `name` string, required: The relative hostname to enter in your DNS provider. Most DNS providers auto-append the zone name, so you only need to enter this relative part. - `"@"` means the apex/root of the zone (for root domains) - `"mail"` for a subdomain like `mail.example.com` - `"ark-xyz._domainkey.mail"` for DKIM on a subdomain - `fullName` string, required: The complete fully-qualified domain name (FQDN). Use this as a reference to verify the record is configured correctly. - `value` string, required: The value to set for the DNS record - `status` 'OK' | 'Missing' | 'Invalid' | 'null', nullable: Current verification status of this DNS record: - `OK` - Record is correctly configured and verified - `Missing` - Record was not found in your DNS - `Invalid` - Record exists but has an incorrect value - `null` - Record has not been checked yet - `createdAt` string, date-time, required: Timestamp when the domain was added - `tenant_id` string: ID of the tenant this domain belongs to - `tenant_name` string: Name of the tenant this domain belongs to - `meta` ApiMeta, required - `requestId` string, required: Unique request identifier for debugging and support ## Other responses - `400`: Invalid request parameters - `401`: Invalid or missing API key - `404`: Tenant not found - `409`: Domain already exists - `429`: Rate limit exceeded - `500`: Internal server error ## Changes - **2026-02-08** `37bce0c9a4d7`: 1 info - endpoint added [Operation history](https://skmtc.dev/arkhq-io/apis/ark-email-api/changes/tenants/:tenantId/domains/post.md) --- [API](https://skmtc.dev/arkhq-io/apis/ark-email-api.md) - [All operations](https://skmtc.dev/arkhq-io/apis/ark-email-api/llms.txt) - [OpenAPI document](https://skmtc.dev/arkhq-io/apis/ark-email-api/revisions/98a90852ffca?raw)