> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hocdoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom domain and sender domain

> Offers and emails under your own domain, as a subdomain or root domain: set up, www variant, proof of ownership, understanding the status, deadline, removing.

With a custom domain, your offers run under your address, for example `angebote.deine-firma.de` or `deine-firma.de`, instead of under `app.hocdoc.com`. With a sender domain, the emails to recipients and signers come from an address on your domain instead of `mail.hocdoc.com`. You find both in [Settings](https://docs.hocdoc.com/en/guides/settings.md) in the "Domain" tab, each on its own card. The two domains are independent of each other.

The sections up to [Common errors](#common-errors) apply to the offer pages. The [Sender domain for emails](#sender-domain-for-emails) follows after that.

## Requirements

* You are an owner or admin of the workspace. Members and viewers see domain and status but have no buttons.
* You have access to the domain's DNS provider, because that is where you enter a record.
* You use a subdomain, for example `angebote.deine-firma.de`, or the root domain, for example `deine-firma.de` (also `deine-firma.co.uk`). With the A record, the whole domain points to HocDoc.
* Your plan includes the custom domain. Starter, Pro and Team do.

Each workspace has at most one domain.

## Set up

**1. Open the tab**

Choose "Settings" and then the "Domain" tab. The card is called "Custom domain".

**2. Enter the domain**

In the **Domain** field, enter your subdomain, for example `angebote.deine-firma.de`, or your root domain, for example `deine-firma.de`, and choose **Add domain**.

**3. Set the DNS record**

Under "DNS records", the card shows a table with "Type", "Name" and "Value". With **Copy** you take over a value. For a subdomain it is a CNAME record, for a root domain an A record with your domain's name and an IP address as the value. Create the record at your DNS provider. It can take a few hours until it is visible everywhere. If your DNS provider knows ALIAS or ANAME for the root domain, you can set such a record instead of the A record. The note "Does your DNS provider support ALIAS or ANAME for the root domain?" names the target.

**4. Check again**

Choose **Check again**. Next to the button it says when the last check was ("Last checked: …"). Repeat the check until the status shows "Active".

The table shows the record's value. Take it from there. If the records are not available yet, it says: "The DNS records are not available yet. Check again in a moment."

## www variant of the root domain

If you enter a root domain, for example `deine-firma.de`, you set up the www address along with it. For this the card shows the "www variant" section: "For a root domain you can set up the www address as well. One of the two addresses then redirects to the other." Under **Redirect** you choose:

| Choice | Effect |
| - | - |
| "Only deine-firma.de" | No www address. |
| "[www.deine-firma.de](http://www.deine-firma.de) redirects to deine-firma.de" | The www address leads to the root domain. |
| "deine-firma.de redirects to [www.deine-firma.de](http://www.deine-firma.de)" | The root domain leads to the www address. |

Choose **Save**. For the www address, you enter the additional CNAME record at your DNS provider, and it is in the DNS list. The www variant has no row of its own. Status, check, deadline and removal apply to both addresses. HocDoc sets the redirect as soon as both names are confirmed. A new domain only becomes active when both addresses are right. A domain that is already active stays active, even if the new www variant does not point yet. You cannot enter a www address that belongs to another workspace's root domain.

## The statuses

| Status | Meaning |
| - | - |
| "Waiting for DNS" | "Add the CNAME record at your DNS provider. It can take a few hours until it is visible everywhere." For a root domain it says "A record". |
| "Proof required" | The domain is already attached to another account at our hosting provider. You additionally enter the TXT record shown, to prove that it belongs to you. Until then it stays inactive. More under [Proof of ownership](#proof-of-ownership). |
| "Checking" | A check is running right now. |
| "Active" | "New offer links use this domain. Links under app.hocdoc.com keep working." |
| "Error" | The domain was rejected. The reason is below the status (see [Common errors](#common-errors)). |

When you open the tab, the app checks the state on its own if the last check was a while ago. HocDoc also reconciles domains in the background: every 15 minutes in the first 48 hours, then every 6 hours. You do not need to keep the tab open for that. With **Check again** you trigger the check yourself. If the status cannot be checked, the app reports "The status could not be checked" and shows the saved state. Try again in a few minutes then.

## Proof of ownership

If a domain was already attached at our hosting provider before HocDoc attached it itself, it does not automatically count as yours. You then prove with a TXT record that it belongs to your workspace:

* **Name:** `_hocdoc-verify.deine-firma.de`, that is `_hocdoc-verify.` in front of your domain.
* **Value:** your token. There is a separate one per workspace and domain.

The card's DNS list shows the record with name and value. Take it from there. If it is missing, the status "Error" gives the reason: "The domain is already attached at our hosting provider. Add the TXT record to prove that it belongs to your workspace. We then check it again automatically." The background reconciliation keeps checking. The 14-day deadline applies here too.

## Deadline for setup

A domain you enter but never finish setting up expires. As long as it is not active, the card shows "Deadline for setup": "Set up the domain by" followed by the date ". After that we remove it automatically. You get an email beforehand." The deadline is 14 days after entering. On day 10 and after expiry, HocDoc sends an email to owners and admins. After expiry the card shows "Domain expired" with the sentence that the domain was removed because it was not set up for 14 days. You can enter it again at any time.

## What changes with an active domain

New offer links use the custom domain:

* in the emails to recipients,
* when copying the public link on the detail page,
* for the link to the summary.

Links already sent under `app.hocdoc.com` stay valid.

Some things stay on the main domain: the verification page from the certificate, links to the dashboard, the logo in emails and the sign-in emails.

## What is reachable under the domain

Under your domain, only your workspace's offer pages are reachable. The app itself (sign-in, dashboard) does not exist there. If someone opens a link that belongs to another workspace or does not exist, they see "not found".

## Remove the domain

Choose **Remove** and confirm the question "Remove domain?" with **Remove**. The consequences:

* Offers are then only reachable under `app.hocdoc.com`.
* Links in emails already sent that point to your domain no longer work.
* Afterwards, also remove the CNAME record at your DNS provider.

A domain that was once active stays blocked for other workspaces for 30 days after removal. You yourself can enter it again right away.

If your workspace already has a domain, you cannot enter a second one: "This workspace already has a domain. Remove it first." So switching means first removing, then entering anew.

## Does the domain belong to you and is blocked?

If a domain cannot be set up even though it belongs to you, for example because "This domain is already taken." appears when entering, or the domain is already in use elsewhere, the box **Is this your domain?** appears for owners and admins below the message. With **Write an email to [support@hocdoc.com](mailto:support@hocdoc.com)**, a prepared email opens. Workspace ID, domain, the area (custom domain for offers or sender domain for emails) and the error code are already in it. Add how you can show that the domain belongs to you. We check the claim and get back to you.

The box says nothing about who else uses the domain. The same applies to our answer.

## Common errors

Messages when entering:

| Message | What to do |
| - | - |
| "This is not a valid domain." | Check the spelling. |
| "This domain is already taken." | Another workspace uses the domain or has blocked it. Use a different subdomain. |
| "This domain cannot be used." | The domain is blocked. Use a different one. |
| "Only owners and admins can manage the domain." | Ask an owner or admin. |
| "Your plan does not include a custom domain." | The card then shows "Not in your plan" instead of the form. |
| "Too many attempts. Try again later." | Wait briefly. |
| "The setup service is not reachable right now. Try again later." | Try again later. |

Reasons in the status "Error":

| Reason | What to do |
| - | - |
| "The domain is already assigned to another project at our hosting provider." | Remove and enter a different subdomain. |
| "The domain belongs to another account at our hosting provider and cannot be taken over this way." | Remove and enter a different subdomain. |
| "The hosting provider rejected the domain. Check the spelling." | Check the spelling, remove, enter again. |
| "This domain cannot be used. Remove it and add a different one." | Remove and enter a different domain. |
| "The domain could not be set up." | Remove and enter it once more. |

If the status stays "Waiting for DNS", check the record at your DNS provider: name and value must match the table exactly. If the status shows "Proof required", the TXT record `_hocdoc-verify.` is missing (see [Proof of ownership](#proof-of-ownership)).

## Sender domain for emails

With a sender domain, emails to recipients and signers come from an address on your domain, for example `angebote@deine-firma.de`. The card is called "Sender domain for emails" and sits in the "Domain" tab below the "Custom domain" card.

### Requirements

* You are an owner or admin of the workspace. Members and viewers see address, status and DNS records but have no buttons.
* You have access to the domain's DNS records. This is also shown as a note on the field.
* Each workspace has at most one sender domain. It is independent of the domain for offer pages.

### Plan, deadline and reconciliation

* **Plan:** Whether you can enter a sender domain depends on the plan. If it is not included in your plan, the card shows "Not in your plan" instead of the form, and emails keep coming from HocDoc. If you switch to a plan without a sender domain, an existing domain stays until you remove it. After that you cannot enter a new one.
* **Reconciliation:** HocDoc also checks the DNS records in the background, every 15 minutes in the first 48 hours, then every 6 hours.
* **Deadline:** If the DNS records are not set up 14 days after entering, HocDoc removes the sender domain. Until then the card shows "Deadline for setup" with the date. On day 10 and after expiry an email goes to owners and admins. The card then shows "Sender domain expired". You can enter it again at any time.

### Set up

**1. Enter domain and address**

Under **Sender domain**, enter the domain after the @, for example `deine-firma.de`. Under **Address before the @** is the default, which you can change. Allowed are lowercase letters, digits, period, hyphen and underscore, at most 32 characters. Below it, the preview "Emails come from …" shows the finished address. Choose **Add sender domain**.

**2. Set the DNS records**

Under "DNS records", the card shows three records with "Type", "Name", "Value" and a status per record ("Found", "Still missing", "Not found" or "Unchecked"). With **Copy name** and **Copy value** you take over the details. Create the records at your DNS provider. The name is relative to your root domain. Some DNS providers append the domain themselves. It can take a few hours until the records are visible everywhere.

**3. Check again**

Choose **Check again**. Next to the button it says when the last check was ("Last checked: …"). Repeat the check until the status shows "Active". Then the card says: "Emails to recipients and signers come from" followed by your address.

When you open the tab, the app checks the state on its own. If the records are not available yet, it says: "The DNS records are not available yet. Check again in a moment." Until the domain is active, all emails come from HocDoc.

### Which emails come from your address

With an active sender domain, these come from your address:

* the sending of the offer to the recipient,
* the invitation to the next signer,
* the code email on acceptance,
* the confirmation of acceptance,
* the reminders from [automatic follow-ups](https://docs.hocdoc.com/en/guides/automatic-follow-ups.md).

Still coming from HocDoc are the notifications to you and your team, team invitations and the sign-in emails.

Sender name and reply address stay as you set them in the "Sender" tab. Only the address behind the name changes.

If an email cannot be sent through your domain, it goes out through HocDoc. If an email from your domain is rejected in the process, the card shows "On … an email from this domain was rejected and went out from HocDoc." Check the DNS records then and choose **Check again**.

### The statuses

| Status | Meaning |
| - | - |
| "Waiting for DNS" | "Add the records at your DNS provider. It can take a few hours until they are visible everywhere. Until then, emails come from HocDoc." |
| "Checking" | A check is running right now. |
| "Active" | Emails to recipients and signers come from your address. |
| "Error" | The reason is below the status (see below). |

If the status cannot be checked, the app reports "The status of the sender domain could not be checked" and shows the saved state. Try again in a few minutes.

### Which domains do not work

* Domains of HocDoc itself, of email and hosting providers and well-known free email domains are blocked. Then it says: "This domain cannot be used as a sender."
* IP addresses are not a domain: "This is not a valid domain."
* A domain already used by another workspace is taken: "This domain is already taken."
* A domain that was once active stays blocked for other workspaces for 30 days after removal. You yourself can enter it again right away.

Here you may enter the root domain, for example `deine-firma.de`, as with the offer pages. The DNS records sit on names of their own, and the app shows them to you.

### Reasons in the status "Error"

| Reason | What to do |
| - | - |
| "This domain is already set up at our email provider. Write to us if it belongs to you." | Write to us. |
| "The domain could not be fully set up at our email provider. We have been notified and are taking care of it. Until then, emails come from HocDoc." | Wait. |
| "The email provider rejected the domain. Check the spelling." | Check the spelling, remove, enter again. |
| "This domain cannot be used. Remove it and add a different one." | Remove and enter a different domain. |
| "Sender domains cannot be set up at the moment. We have been notified. Try again later with Check again." | Choose **Check again** later. |
| "The DNS records were not found for 72 hours. Check them and click Check again." | Check the records, then **Check again**. |
| "The DNS records can no longer be found. Emails come from HocDoc until the next successful check." | Set the records again, then **Check again**. |
| "The email provider rejected an email from this domain. It was sent from HocDoc instead. Check the DNS records and click Check again." | Check the records, then **Check again**. |
| "The domain could not be set up." | Remove and enter it once more. |

Other messages when entering: "This workspace already has a sender domain. Remove it first.", "Only owners and admins can manage the sender domain.", "Your account has reached the maximum number of sender domains.", "Too many attempts. Try again later." and "The setup service is not reachable right now. Try again later."

### Remove the sender domain

Choose **Remove** and confirm the question "Remove sender domain?" with **Remove**. Emails then come from `mail.hocdoc.com` again. Afterwards, also remove the DNS records for the domain at your DNS provider.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.