Skip to main content

domain_scope_restricted

The key you authenticated with is restricted to a named set of domains, and this request used a domain outside that set. Nothing was sent and nothing was charged.

Status: 403

{
  "status": 403,
  "type": "domain_scope_restricted",
  "message": "This API key is restricted to mail.example.com and cannot be used with example.com",
  "request_id": "req_01J8K2P...",
  "doc_url": "https://docs.epostix.com/errors/domain_scope_restricted"
}

Why you got this​

  • The from address belongs to a domain the key is not allowed to use.
  • Sending moved to a new subdomain while the key stayed pinned to the previous one. example.com and mail.example.com are separate domains here.
  • A key was issued to one team for one domain and is now being used across the workspace.

How to fix it​

Read the message. It names both the domain you used and the domains the key covers. Either change the from address to a domain on that list, or authenticate with a key that carries no domain restriction. The restriction is fixed when the key is created, so it cannot be widened afterwards: issue a new key instead.

This is separate from scopes. A key can hold the sending scope and still be refused here, and a key missing the permission entirely returns insufficient_scope. See authentication for how the two combine.

Is it safe to retry​

No. The same key and the same domain fail the same way every time. Change one of them and send a new request.

Reusing the Idempotency-Key afterwards is safe, because a rejected request was never stored.