Mailfully logo

Adding a domain was refused

Tell apart the ways a domain add is refused: a reserved or unownable domain, another org holding the parent, your plan's domain limit, a rate limit, and a conflict.

POST /v1/domains can be refused seven ways, and the status and error type tell you which.

422 validation_error

The name is empty or is not a valid domain. param is name, and the message says "name must be a valid domain, e.g. acme.com." Send a bare domain such as mail.acme.com.

422 domain_reserved

You cannot add mailfully.app, mailfully.ai, mailfully.net, or a name under one of them. param is name. Use a domain you own. To receive mail without your own domain, use the hosted mailfully.app address (see Receiving email).

422 domain_not_owned

Nobody can own the domain you entered, so its DNS records could never be published. Examples are an email provider's own domain such as gmail.com, and a name under a site host such as myblog.wordpress.com. param is name, and the message says which domain it refused. Use a domain you own, such as yourcompany.com.

409 domain_parent_taken

Another organization already verified a domain under the same registrable parent, which is why checking your own domain list will not explain this one. Legitimate for agencies and subsidiaries: write to contact@mailfully.com for an allowlist entry.

403 domain_limit_reached

Your organization already holds as many domains as its plan allows. Every domain counts, pending ones included, so a half-finished add you forgot about can put you over the limit. Test and live share one limit. Delete a domain you don't use, including a stalled pending one, on the domain page or with Delete a domain, or upgrade your plan. See Quotas and plan limits for what each plan includes.

429 rate_limit_exceeded

Adding and deleting domains share a limit of 10 a minute per environment. Wait for retry-after seconds and try again. See Rate limits.

409 conflict

Three different messages share this status:

  • Domain 'acme.com' is already added. Your organization already has it. Find it with GET /v1/domains or on the Domains page.
  • Domain 'acme.com' is already registered to another account. Email contact@mailfully.com.
  • Domain 'acme.com' already has an email identity that cannot be claimed automatically. Please contact support. Email contact@mailfully.com.

Check what you already have

GET /v1/domains lists every domain on the org with its current status:

curl https://api.mailfully.com/v1/domains \
  -H "Authorization: Bearer mf_live_xxxxxxxxxxxx"

Use it to find pending domains that count toward your limit. See GET /v1/domains.

Subdomains are separate domains

mail.acme.com and acme.com are separate domain records: each is verified separately and each counts against the limit on its own. See Subdomain or root domain.