---
title: "Create domain"
method: POST
path: "/v1/domains"
tags: ["Domains"]
---

# Create domain

`POST /v1/domains`

## Request

- Base URL: `https://api.forwardemail.net`
- URL: `https://api.forwardemail.net/v1/domains`
- Auth: HTTP basic

Creates a new domain in the system. This endpoint allows you to register a fully qualified domain name (FQDN) or IP address for use with the platform.

Optional configuration options include assigning the domain to an existing team, setting a plan type (e.g., free, enhanced protection, or team), and configuring advanced protections such as spam filtering, virus scanning, and recipient verification. You can also configure whether a catch-all alias should be created by default, set a custom bounce webhook URL for SMTP failures, and define storage quota limits for email aliases on this domain. This endpoint performs domain-level validation and provisioning. If the `ignore_mx_check` option is enabled, MX record verification is skipped (recommended only for advanced routing setups). The response will contain full details of the created domain object, including DNS records needed for configuration.

The response includes `zone_file`, a zone file with every DNS record the domain needs (MX, verification, SPF, DKIM, Return-Path, DMARC, and autodiscovery) that you can import into your DNS provider (domain admins only).

## Request body

- CreateDomainInput
  - `domain` string, required: Fully qualified domain name (FQDN) or IP address
  - `team_domain` string, nullable: Assign to same team from another domain; can be a domain ID or FQDN. Use "none" to explicitly disable.
  - `plan` 'free' | 'enhanced_protection' | 'team': Plan type (defaults to 'free' or the user's current paid plan)
  - `catchall` union: Create a default catch-all alias (defaults to true)
    - boolean
    - string: Delimited list of email addresses (comma, space, or newline separated)
  - `has_adult_content_protection` boolean: Enable Spam Scanner adult content protection
  - `has_phishing_protection` boolean: Enable Spam Scanner phishing protection
  - `has_executable_protection` boolean: Enable Spam Scanner executable protection
  - `has_virus_protection` boolean: Enable Spam Scanner virus protection
  - `has_recipient_verification` boolean: Require alias recipients to click email verification link
  - `ignore_mx_check` boolean: Ignore MX record check for advanced mail routing setups
  - `allow_subdomain_forwarding` boolean: Allow wildcard subdomain forwarding. When enabled on a paid plan (Enhanced Protection or Team), any subdomain that has no DNS records of its own inherits the forwarding configuration published at this domain’s root (apex). Verified ownership is required: the apex must publish a forward-email-site-verification record matching this domain. This setting does not apply to the free plan.
  - `has_delivery_logs` boolean: Opt-in to store headers and metadata (excluding message content) for successfully forwarded, webhook-sent, outbound SMTP, and IMAP-delivered emails, with logs retained for 7 days. This feature helps you monitor and troubleshoot email delivery performance with detailed insights into successful transmissions.
  - `retention_days` integer: Number of days to retain outbound SMTP logs (0–30, default: 0)
  - `bounce_webhook` union
    - string, uri: Webhook URL to receive bounce events
    - false: Disable bounce webhook
  - `max_quota_per_alias` string: Storage max quota per alias (e.g. '1 GB')

## Response `200`

Domain created successfully

- Domain
  - `domain_updates` object[]
  - `has_pending_domain_updates` boolean
  - `has_newsletter` boolean
  - `ignore_mx_check` boolean
  - `allow_subdomain_forwarding` boolean: Allow wildcard subdomain forwarding. When enabled on a paid plan (Enhanced Protection or Team), any subdomain that has no DNS records of its own inherits the forwarding configuration published at this domain’s root (apex). Verified ownership is required: the apex must publish a forward-email-site-verification record matching this domain. This setting does not apply to the free plan.
  - `has_delivery_logs` boolean
  - `retention_days` integer
  - `has_regex` boolean
  - `has_catchall` boolean
  - `allowlist` string[]
  - `denylist` string[]
  - `restricted_alias_names` string[]
  - `has_adult_content_protection` boolean
  - `has_phishing_protection` boolean
  - `has_executable_protection` boolean
  - `has_virus_protection` boolean
  - `is_catchall_regex_disabled` boolean
  - `has_smtp` boolean
  - `is_smtp_suspended` boolean
  - `plan` string
  - `max_recipients_per_alias` integer
  - `alias_default_smtp_limit` integer: Default daily SMTP sending limit applied to newly created aliases on this domain. Set to 0 to disable (aliases will use the domain-wide limit). Cannot exceed the domain's effective SMTP limit.
  - `smtp_port` string
  - `members` object[]
  - `invites` object[]
  - `name` string
  - `has_mx_record` boolean
  - `has_txt_record` boolean
  - `has_dkim_record` boolean
  - `has_return_path_record` boolean
  - `has_dmarc_record` boolean
  - `has_strict_dmarc` boolean
  - `has_spf_record` boolean
  - `has_autoconfig_record` boolean
  - `has_autodiscover_record` boolean
  - `has_recipient_verification` boolean
  - `has_custom_verification` boolean
  - `has_custom_s3` boolean: Whether this domain uses custom S3-compatible storage for backups
  - `s3_endpoint` string: Custom S3-compatible endpoint URL (e.g. https://s3.us-east-1.amazonaws.com, https://<accountid>.r2.cloudflarestorage.com)
  - `s3_region` string: S3 region (e.g. us-east-1, auto). Defaults to auto if not specified.
  - `s3_bucket` string: S3 bucket name for storing backups. The bucket must already exist.
  - `require_tls_inbound` boolean: When enabled, reject inbound emails not sent over TLS
  - `verification_record` string
  - `id` string
  - `object` 'domain'
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `storage_used` integer
  - `storage_used_by_aliases` integer
  - `storage_quota` integer
  - `smtp_dns_records` object
    - `dkim` object
      - `name` string
      - `value` string
    - `return_path` object
      - `name` string
      - `value` string
    - `dmarc` object
      - `name` string
      - `value` string
  - `zone_file` string: Every DNS record the domain needs (MX, verification, SPF, DKIM, Return-Path, DMARC, and autodiscovery) as a zone file to import into a DNS provider. Only included when a domain is retrieved or created, for domain admins.
  - `link` string, uri

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `429`: Too Many Requests

---

[API](https://skmtc.dev/forwardemail/apis/forward-email-api.md) · [All operations](https://skmtc.dev/forwardemail/apis/forward-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/forwardemail/apis/forward-email-api/revisions/ecefab4527f6?raw)