# add_site_email_domain

Source: https://modulify.ai/docs/api/emails/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.

- Title: Add an email domain to a site
- Scope: `config:write`
- Access: Makes changes
- Endpoint: `POST /v1/add_site_email_domain`

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](https://modulify.ai/docs/automations/emails#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](https://modulify.ai/docs/api/idempotency) header whenever you might retry it. A retry with the same key gets the first answer back instead of running again.

```bash
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](https://modulify.ai/docs/mcp/emails/add-site-email-domain).

## 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](https://modulify.ai/docs/api/requests-and-responses#the-response) 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](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) 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](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.