---
title: "Update domain"
method: PUT
path: "/v1/domains/{domain_id}"
tags: ["Domains"]
---

# Update domain

`PUT /v1/domains/{domain_id}`

## Request

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

Update a specific domain.

## Request body

- UpdateDomainInput
  - `smtp_port` union: Custom port to configure for SMTP forwarding (default is '25')
    - string
    - number
  - `has_adult_content_protection` boolean: Whether to enable Spam Scanner adult content protection on this domain
  - `has_phishing_protection` boolean: Whether to enable Spam Scanner phishing protection on this domain
  - `has_executable_protection` boolean: Whether to enable Spam Scanner executable protection on this domain
  - `has_virus_protection` boolean: Whether to enable Spam Scanner virus protection on this domain
  - `has_recipient_verification` boolean: Global domain default for whether to require alias recipients to click an email verification link for emails to flow through
  - `ignore_mx_check` boolean: Whether to ignore the MX record check on the domain for verification (mainly for advanced MX 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 store outbound SMTP emails (0 = purge immediately)
  - `bounce_webhook` union: Webhook URL to receive bounce notifications, or false to disable
    - string, uri
    - false
  - `max_quota_per_alias` string: Storage quota per alias (e.g. '1 GB', parsed into bytes)
  - `has_custom_s3` boolean: Whether to enable custom S3-compatible storage for IMAP/SQLite backups on this domain
  - `s3_endpoint` string, uri: Custom S3-compatible endpoint URL (e.g. https://s3.us-east-1.amazonaws.com)
  - `s3_access_key_id` string: S3 access key ID. Encrypted at rest. Leave blank when updating to keep existing value.
  - `s3_secret_access_key` string: S3 secret access key. Encrypted at rest. Leave blank when updating to keep existing value.
  - `s3_region` string: S3 region (e.g. us-east-1, auto). Defaults to auto.
  - `s3_bucket` string: S3 bucket name for storing backups. The bucket must already exist and must not be publicly accessible.
  - `allowlist` string[]: List of allowlisted senders (IP addresses, fully qualified domain names, email addresses, or wildcard TLDs). When set, only mail from these senders will be accepted. Replaces the existing list. Wildcard public-suffix rules may contain multiple labels, for example `*.gov.co` and `*.gov.br`; they match senders under that exact suffix.
  - `denylist` string[]: List of denylisted senders (IP addresses, fully qualified domain names, email addresses, or wildcard TLDs). Mail from these senders will be rejected. Replaces the existing list. Wildcard public-suffix rules may contain multiple labels, for example `*.gov.co` and `*.gov.br`; they match senders under that exact suffix.

## Response `200`

Domain updated 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

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found

---

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