Add an email domain to a site

add_site_email_domain

Adds a domain you own, or a subdomain of it, to a site so the site can send email from it and, when you want, receive email at it.

POST /v1/add_site_email_domainScopeconfig:writeMakes changes

It requires a paid plan and is refused on a free workspace, it needs the Manage domains permission, and it works on sites only, refusing any other project with Email domains are only available for sites! A site holds at most 3 email domains. A workspace can add at most 10 email domains an hour and 30 a day across its sites. Every add that passes the checks on the domain, the plan and the site's limit counts, including one that then fails because the mail provider is busy and a domain removed again, and an add over that is refused with how long to wait.

Give the domain without www., such as example.com, or a subdomain such as mail.example.com, which leaves the mailboxes of the main domain untouched. A domain starting with www. is refused with Use the domain without www, such as example.com!

Adding it does not verify it. The answer is the site's email settings, and emailDomains.items holds the new domain with the DNS records to add at its DNS host: an ownership TXT record that has to stay in place, three DKIM CNAME records and a recommended DMARC record. Each record name is the full DNS name, such as _modulify-email.example.com, while many DNS hosts expect only the part in front of the zone, such as _modulify-email. The tool tells the client to give you those records, to say which form your DNS host wants and never to let the zone appear twice. The ownership TXT record only counts at exactly its own name, never through a CNAME.

Once every required record is found and the mail provider confirms them, which can take up to 72 hours, the domain turns verified on its own, and check_site_email_domain checks it again straight away. With sendWhenVerified true, the default, the site starts sending from the domain the first time it is verified, unless another of its email domains is chosen as the sending domain by then.

A domain another site holds moves to this site once this site's ownership record is verified. The other site stops sending from it and receiving its mail, and receiving starts off on this site until set_site_email_domain_receiving turns it on. A domain still not verified 14 days after it was added, after it was last checked with check_site_email_domain or while the site's email settings were open, or after its verification was last restarted, is removed on its own. The built-in sending address keeps working throughout. See Use your own domain.

Request

Call it with a POST to https://api.modulify.ai/v1/add_site_email_domain, sending the inputs below as a JSON object. The token needs the config:write scope.

It makes changes, so send an Idempotency-Key header whenever you might retry it. A retry with the same key gets the first answer back instead of running again.

curl -X POST https://api.modulify.ai/v1/add_site_email_domain \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","domain":"DOMAIN"}'

Over MCP, the same method is the add_site_email_domain tool.

Inputs

Input	Type	Required	Description
`projectId`	string	Yes	The site id.
`domain`	string	Yes	The domain to add, without `www.`, for example `example.com` or `mail.example.com`.
`sendWhenVerified`	boolean	No	True, the default, to start sending from the domain the first time it is verified, as long as no email domain is chosen as the sending domain then (`selectedDomain` is null). False to keep sending from the current address until the domain is chosen with `set_site_email_sending_domain`.

Response

Every call answers with the JSON envelope of success, message, data, code and version. data holds the result described above, and on a method that returns a total, count carries it. The response headers carry the call's X-Request-Id and what is left of your per-minute budget in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Errors explains every status code a call can answer with.