# Addresses and domains

A newsletter always answers at its number, as in `https://app.example.com/834206594`. It can also answer at a handle and at a domain of its own.

Paste this into your agent:

> Put my Mailpiece newsletter on a domain of its own. Read mailpiece.dev/docs/domains.md first.

## A handle

Set on Settings › Handle, as in `https://app.example.com/my-news`. 3 to 40 lowercase letters, numbers and hyphens, starting with a letter; words the app uses are taken.

Changing it breaks links already mailed with the old one. The number keeps working.

## A domain of its own

Set or cleared on Settings › Domain, such as `news.example.com`; the app's own host is refused. `BASE_URL` must be set.

Point the DNS at the server. With Kamal, add the domain to the proxy hosts and deploy. With Docker, append it to `TLS_DOMAIN`, as in `app.example.com,news.example.com`, and restart. A CDN or proxy in front must keep the `Host` header.

```sh
# config/deploy.production.yml
proxy:
  ssl: true
  hosts:
    - app.example.com
    - news.example.com

bin/kamal deploy -d production
```

## What a domain serves

Only reader pages: the post list at `/`, posts, feed, sitemap, subscription page, confirm and unsubscribe links, tracked links, ratings and post files. The newsletter's mail links there.

Sign-in and admin screens answer only at `BASE_URL` and are a 404 on a domain, which sets no cookie.

Changing or clearing a domain breaks links in mail already sent.

Still need help? Ask on [GitHub](https://github.com/mailpiece/mailpiece).