---
title: "Attaching a custom domain"
description: "Serve a hosted site at your own hostname with automatic HTTPS: the two DNS records, managed versus external mode, and what each state means."
canonical: "https://help.sitesmojo.com/kb/sites-and-domains/attaching-a-custom-domain/"
---

Serve a site at `docs.example.com` instead of — or alongside —
`<slug>.sitesmojo.com`, with a certificate issued and renewed automatically once
DNS points at the platform.

Attach from the portal: **Site detail → Domains tab**.

## Two modes, inferred for you

**Managed** — the hostname sits inside a DNS zone this workspace already
controls. The pointing record and the ownership TXT are written for you. If a
conflicting record set already exists, the attach *refuses and names it*; repeat
with the replace-existing confirmation to go ahead. That confirmation is
deliberate, because writes replace the whole record set.

**External** — DNS lives somewhere else. Nothing is written; you publish the
records yourself.

## The two records

For `docs.example.com` on a site with slug `acme`:

| Type | Name | Value |
|---|---|---|
| CNAME | `docs.example.com` | `acme.sitesmojo.com` |
| TXT | `_maestro-verify.docs.example.com` | the token shown in the reply |

An apex name (`example.com` with no subdomain) gets an `A` record to the serving
IP instead of the CNAME, because a CNAME at a zone apex is not valid DNS.

**The TXT record is not optional.** It proves you control the DNS, and no
certificate is ever issued without it. "The name resolves here" proves nothing on
its own — any stale record could do that.

## The states

DNS status:

- **pending** — the records are not visible yet, or only one of the two checks
  passes. The status message says which, and what it saw.
- **verified** — both checks pass. Certificate issuance starts automatically.
  There is no "request certificate" step.
- **broken** — a domain that was verified stopped resolving here, or the TXT
  disappeared. Serving continues while the certificate is valid; renewals stop
  until it is fixed.

Certificate status runs `none → queued → issuing → active`, or lands on
**failed** with the certificate authority's own message attached. Issuance is
gated hard: nothing is requested while the domain does not resolve here with
proven ownership. Repeated failures back off and park at failed after eight
attempts. Fix the cause, then retry.

## What works once the certificate is active

The domain is a full address for the site, not just an HTTPS front door.
Analytics count into the same site's numbers with nothing to configure. Forms
accept submissions from it — your own domains are implicit. Navigating between
apex and www counts the view and adds no referrer row.

Two honest limits:

- **Analytics and forms start at certificate-active**, not at attach. That is the
  same moment the domain starts serving HTTPS, so there is no window where the
  page loads but the numbers do not.
- **DNS is not re-checked per request.** An active certificate proves the checks
  passed at issuance and at each renewal. Re-point the hostname elsewhere and it
  keeps being served and attributed to your site until the certificate expires —
  detach if you want that to stop now.

## robots.txt and sitemap.xml

These name the **primary** domain, and only from the next deploy. Marking a
domain primary does not rewrite content that was already generated. Deploy again.

## Detaching

Serving stops within about 30 seconds. Managed mode restores the DNS snapshot
taken at attach and reports each record individually. Certificate material is
retained, so re-attaching the same hostname inside the certificate's validity
serves again without re-issuance.