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

# Update domain allowlist

`PUT /v1/domains/{domain_id}/allowlist`

## Request

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

Replace the allowlist for a domain. The allowlist restricts inbound mail to only the specified senders. Each entry must be a valid IP address, fully qualified domain name (FQDN), email address, or wildcard top-level domain (e.g. `*.com`). A maximum of 1000 entries is allowed. Wildcard public-suffix rules may contain multiple labels, for example `*.gov.co` and `*.gov.br`; they match senders under that exact suffix.

## Path parameters

- `domain_id` string, required

## Request body

- object
  - `allowlist` string[], required: Array of allowlisted senders (IP addresses, FQDNs, email addresses, or wildcard TLDs such as `*.com`). Pass an empty array to clear the allowlist. 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

- `400`: Bad Request
- `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)