Domains

Create domain

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).

post/v1/domains

Request

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

Request body

domainstring required

Fully qualified domain name (FQDN) or IP address

team_domainstring 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)

has_adult_content_protectionboolean

Enable Spam Scanner adult content protection

has_phishing_protectionboolean

Enable Spam Scanner phishing protection

has_executable_protectionboolean

Enable Spam Scanner executable protection

has_virus_protectionboolean

Enable Spam Scanner virus protection

has_recipient_verificationboolean

Require alias recipients to click email verification link

ignore_mx_checkboolean

Ignore MX record check for advanced mail routing setups

allow_subdomain_forwardingboolean

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_logsboolean

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_daysinteger

Number of days to retain outbound SMTP logs (0–30, default: 0)

max_quota_per_aliasstring

Storage max quota per alias (e.g. '1 GB')

Response

Domain created successfully

domain_updatesobject[]
has_pending_domain_updatesboolean
has_newsletterboolean
ignore_mx_checkboolean
allow_subdomain_forwardingboolean

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_logsboolean
retention_daysinteger
has_regexboolean
has_catchallboolean
allowliststring[]
denyliststring[]
restricted_alias_namesstring[]
has_adult_content_protectionboolean
has_phishing_protectionboolean
has_executable_protectionboolean
has_virus_protectionboolean
is_catchall_regex_disabledboolean
has_smtpboolean
is_smtp_suspendedboolean
planstring
max_recipients_per_aliasinteger
alias_default_smtp_limitinteger

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_portstring
membersobject[]
invitesobject[]
namestring
has_mx_recordboolean
has_txt_recordboolean
has_dkim_recordboolean
has_return_path_recordboolean
has_dmarc_recordboolean
has_strict_dmarcboolean
has_spf_recordboolean
has_autoconfig_recordboolean
has_autodiscover_recordboolean
has_recipient_verificationboolean
has_custom_verificationboolean
has_custom_s3boolean

Whether this domain uses custom S3-compatible storage for backups

s3_endpointstring

Custom S3-compatible endpoint URL (e.g. https://s3.us-east-1.amazonaws.com, https://<accountid>.r2.cloudflarestorage.com)

s3_regionstring

S3 region (e.g. us-east-1, auto). Defaults to auto if not specified.

s3_bucketstring

S3 bucket name for storing backups. The bucket must already exist.

require_tls_inboundboolean

When enabled, reject inbound emails not sent over TLS

verification_recordstring
idstring
object'domain'
created_atstring date-time
updated_atstring date-time
storage_usedinteger
storage_used_by_aliasesinteger
storage_quotainteger
zone_filestring

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.

linkstring uri

Changes

No recorded changes to this operation across all 1 revision of this API.