Skip to main content
An IP allow list restricts an API key to a set of IP addresses. Once a key has an allow list, requests made with it from anywhere else are rejected, so a leaked key is useless outside your own infrastructure.
Scope of this feature: IP allow lists apply to Management API keys only. SMTP credentials and sending credentials are not affected.

​
How it works

Every API key carries an ip_allow_list. It is empty by default, and an empty list means no restriction, so existing keys keep working exactly as before. When the list is not empty:
  • Requests from an IP covered by an entry are processed normally.
  • Requests from any other IP are rejected on every endpoint, regardless of the scopes granted to the key.
  • Changes take effect immediately.
The IP check runs before scope validation, so it is not another permission dimension. It is a gate in front of the key.
Prefer static addresses you own and control. An allow list is only as stable as the IPs behind it. Egress from a fixed NAT gateway, a bastion host, or a dedicated server works well. Dynamic addresses do not.

​
Blocked requests

A request made with a restricted key from an IP that is not covered by the list is rejected with HTTP 403 on every v2 endpoint, whatever the key’s scopes allow.
Do not parse the error message. The API returns no stable machine-readable error code, and several conditions share HTTP 403. Treat any 403 as a request your key was not permitted to make, and check the key’s allow list and scopes to find out which applied.
IP allow list checks run before the idempotency layer, so a blocked request is never stored or replayed against an Idempotency-Key. Retrying the same request from an allowed IP with the same key executes normally.

​
Supported entries

You can enter individual addresses or CIDR ranges, in IPv4 or IPv6: A few rules apply when you save:
  • Entries are canonicalized, which means host bits are masked, and duplicates are removed.
  • A key can hold up to 100 entries after de-duplication. A longer list is rejected.
  • The allow-all prefixes 0.0.0.0/0 and ::/0 are rejected. To remove a restriction, clear the list instead.

​
Configure in the dashboard

Open your API keys

Go to Settings and then API Keys.

Edit the key

Click Edit on the key you want to restrict and scroll to the IP Allow List section at the bottom.

Add addresses or ranges

Click Add IP address or range and enter one address or CIDR range per field. Repeat for each entry you need.

Save and confirm

Save the change. Because this affects who can use the key, you are asked to confirm your identity before the change is applied.
To lift the restriction again, delete every entry and save. An empty list allows all IPs.

​
Configure with the Management API

Set the ip_allow_list field when you create a key, or when you update an existing one. The same field is available on the sub-account API key endpoints.
To change the list on an existing key, send a PUT to the key’s endpoint:
An update replaces the list rather than merging into it, so send the complete set of entries you want the key to keep: The field is always present on API key responses. An empty array means the key can be used from any IP.
Self-lockout protection: If a key updates its own allow list to a value that excludes the IP the request is coming from, the update is rejected with HTTP 409 and nothing is persisted. Updating a sub-account key from a parent key has no such guard, so check the sub-account’s egress IP before you restrict its keys.

Scoped API Keys

Restrict what a key can do with domain and permission scoping

API Key Scopes

Complete reference of available permission scopes

Create API Key

Endpoint reference including the ip_allow_list field