---
name: saasco-add-domain
description: "Adds the domain a Saasco app needs when the project does not have one yet. Reuses a hostname already on the project, otherwise picks one from the product's own site that will not break the mail or site it already serves, confirms it, turns on sending, receiving, short links, or the help center, and sees its records added and verified once. Use when connecting a sending domain, a support mailbox domain, a short-link domain, or a help-center domain."
compatibility: "Requires the Saasco MCP server (https://www.saasco.com/api/mcp). https://www.saasco.com/agent-setup/prompt.md installs and connects it."
---
# Add a domain

Uses the Saasco MCP. If the `saasco_search_tools` tool is not available, or you do not know which project `YOUR-PROJECT-ID` is, fetch and execute https://www.saasco.com/agent-setup/prompt.md first, then come back to this skill.

A domain is added when the hostname is on `YOUR-PROJECT-ID`, the capability it is for is on, its records are at the DNS host, and it was verified once. The domain tools say what each call does and what it returns. This page is which hostname to use, and when you are done.

## 1. Know what it is for

One hostname, one job. Find out which one you are adding, from the skill that sent you here or from the user:

| For                                 | Turn it on with                  | Verify with                        |
| ----------------------------------- | -------------------------------- | ---------------------------------- |
| Sending email                       | `domains_activateEmailSending`   | `domains_verifyEmailDNS`           |
| Receiving email, such as `support@` | `domains_activateEmailReceiving` | `domains_verifyEmailReceiving`     |
| Short links                         | `domains_enableShortlink`        | `domains_verifyShortlink`          |
| The help center                     | `knowledge_setHelpCenterDomain`  | `knowledge_verifyHelpCenterDomain` |

## 2. Reuse what is there

Call `domains_listDomains` without `readyToSend`. That filter hides a domain whose tracking record is still missing. A help-center domain is not in this list: read the help center first.

A hostname already has this job when sending has `emailStatus` other than `INACTIVE`, receiving has `emailReceivingStatus` other than `INACTIVE`, or short links have `shortlinkEnabled` true.

If it already has this job and that job is verified, use it and finish. Do not add the same hostname twice. For sending, verified means `emailStatus` is `ACTIVE` and tracking is verified: `trackingVerificationStatus` is `VALID`, or `trackingSubdomain` is null. Sending `ACTIVE` with tracking still pending is not finished. Go to step 5 and add the tracking CNAME.

If it already has this job but it is not verified, use it and go to step 5.

If a listed hostname could be used but the capability is still off, do not turn it on here. Turning receiving or short links on takes over that hostname's mail or its site. It still has to pass step 3 and the confirm in step 4.

## 3. Pick the hostname

These rules apply to a new hostname and to a listed hostname whose capability is still off.

Start from the domain this product is served on. Find it in this repo: the production URL in config, environment examples, site metadata, or the README. Then apply the rule for the job:

- **Sending:** the product's own domain, so mail matches the site people signed up on. If that root already sends mail through another provider, such as Google Workspace, Microsoft 365, or a transactional email service, use a subdomain such as `mail.example.com`. Its records then cannot disturb the mail they already send.
- **Receiving:** receiving replaces the MX records of the hostname it is on. If that hostname already receives mail, their current inbox would stop getting it. Use a subdomain such as `help.example.com`, and say why.
- **Short links:** a short subdomain such as `go.example.com` or `link.example.com`. Never a hostname that already serves a site. Short links take over the whole hostname, so that site would stop loading.
- **Help center:** a subdomain such as `help.example.com` or `docs.example.com`. Never one that already serves a site.

You can tell whether a root already sends or receives mail from its SPF (TXT) and MX records. If you cannot look them up, ask.

## 4. Confirm, then add it

Tell the user the hostname and why it passes the rule for this job. Add nothing they did not agree to. That includes turning a capability on for a hostname already on the project. A hostname that belongs to another Saasco project cannot be added. Ask for another.

If it is already listed, turn on the capability from the table. Do not call `domains_createDomain` again. If it is not listed, call `domains_createDomain`, then turn the capability on. For the help center, `knowledge_setHelpCenterDomain` is the whole step. It replaces any domain the help center already had, so ask first if one is set.

## 5. Records and verify

Add every record the tools return with [`saasco-dns`](https://www.saasco.com/.well-known/agent-skills/saasco-dns/SKILL.md). For sending, that includes the tracking CNAME. Without it, opens and clicks are not counted, and the domain is not ready to send. When `emailStatus` is already `ACTIVE` and `trackingVerificationStatus` is not `VALID`, read `domains_getDomain` and add the tracking row from `emailConfig.records`. Do not activate sending again.

Then call the verify tool from the table once. DNS can take minutes or hours to reach the provider. If a record is still pending, name it and say Saasco keeps checking in the background. Do not poll.

## 6. Finish

Tell the user:

- the hostname, and what it is for
- which records were added, and at which host
- what is verified, and what is still pending

Then go back to the skill that sent you here, if one did.