Correct developer and feature pages against the Postal 3.3.7 source

content/2.getting-started/2.installation.md

@@ -65,3 +65,14 @@ docker run -d \
 Once this has started, Caddy will issue an SSL certificate for your domain and you'll be able to immediately access the Postal web interface and login with the user you created in one of the previous steps.
 
 ![Image](/screenshots/Screen-Shot-2021-07-29-23-26-18.23-Qwv2DD40v4jMEoaHtE.png)
+
+## Next steps
+
+Once you can log in:
+
+1. Create an organization and a mail server.
+2. Add the domain you want to send from and follow the [Sending domains](/features/sending-domains) page to verify it and publish its SPF, DKIM and return path records.
+3. Create an **SMTP** or **API** [credential](/features/smtp-authentication) and send a test message.
+4. Point the `smtp` section of `postal.yml` at your new mail server so that Postal can send its own notification e-mails, then `postal restart`.
+
+The full set of commands provided by the `postal` helper is documented on [The postal command](/getting-started/postal-command) page.

content/2.getting-started/4.dns-configuration.md

@@ -99,7 +99,7 @@ You may wish to replace <code>~all</code> with <code>-all</code> to make the SPF
 
 ## Return Path
 
-The return path domain is the default domain that is used as the `MAIL FROM` for all messages sent through a mail server. You should add DNS records as below.
+The return path domain is the default domain that is used as the `MAIL FROM` for all messages sent through a mail server, so bounces and auto-responses are delivered here. It is also the domain Postal signs messages with (using your `signing.key`) whenever a sending domain does not yet have a working DKIM record of its own. You should add DNS records as below.
 
 <table>
   <thead>
@@ -133,15 +133,15 @@ The return path domain is the default domain that is used as the `MAIL FROM` for
     <tr>
       <td>postal._domainkey.rp.postal.example.com</td>
       <td>TXT</td>
-      <td>Value from <code>postal default-dkim-record</code></td>
+      <td>Value from <code>postal default-dkim-record</code> (the <code>postal</code> selector is the value of <code>dns.dkim_identifier</code>)</td>
     </tr>
   </tbody>
 </table>
 
 
 ## Route domain
 
-If you wish to receive incoming e-mail by forwarding messages directly to routes in Postal, you'll need to configure a domain for this just to point to your server using an MX record.
+If you wish to receive incoming e-mail by forwarding messages directly to routes in Postal (each route has a unique `{token}@routes.postal.example.com` address - see [Routing incoming e-mail](/features/routing-incoming-email)), you'll need to configure a domain for this just to point to your server using an MX record.
 
 <table>
   <thead>
@@ -186,6 +186,10 @@ If you would like to make use of Click and Open Tracking then you should set up
   </tbody>
 </table>
 
+## Records for each sending domain
+
+The records above are for the Postal installation itself. Each domain you send mail *from* additionally needs its own SPF, DKIM and (optionally) return path and MX records, which Postal generates for you and checks automatically. These are described on the [Sending domains](/features/sending-domains) page.
+
 ## Example Postal Configuration
 
 In your `postal.yml` you should have something that looks like the below to cover the key DNS records.

content/2.getting-started/8.postal-command.md

@@ -0,0 +1,83 @@
+---
+title: The postal command
+description: 'Reference for the postal helper command installed from the postalserver/install repository.'
+category: Installation
+---
+
+The `postal` command used throughout these docs is a small Bash script from the [installation helper repository](https://github.com/postalserver/install), which the [pre-requisites](/getting-started/prerequisites) page has you clone to `/opt/postal/install` and symlink to `/usr/bin/postal`. It wraps Docker Compose so that you don't need to remember the container commands.
+
+All commands operate on a `docker-compose.yml` in `/opt/postal/install`, which is generated for you from a template (`templates/docker-compose.v3.yml`) the first time you run `bootstrap`, `upgrade` or any command that needs it. Docker Compose is run with the project name `postal`, so the containers are named `postal-web-1`, `postal-smtp-1`, `postal-worker-1` and so on.
+
+## Running Postal
+
+| Command | Description |
+|---|---|
+| `postal start` | Start all services in the background (`docker compose up -d`). Extra arguments are passed through, e.g. `postal start web`. |
+| `postal stop` | Stop and remove the containers (`docker compose down`). |
+| `postal restart` | Restart all containers. Required after changing `postal.yml`. |
+| `postal status` | Show the running containers (`docker compose ps`). |
+| `postal logs [service]` | Show logs for all services or one of `web`, `smtp`, `worker`. Extra arguments are passed through, e.g. `postal logs -f worker`. |
+| `postal bash [service]` | Open a shell inside a running service container. |
+| `postal dc [args]` | Run any other `docker compose` command against the Postal project, e.g. `postal dc pull`. |
+
+## Setup and upgrade
+
+| Command | Description |
+|---|---|
+| `postal bootstrap hostname [path]` | Create initial configuration in `path` (default `/opt/postal/config`): `postal.yml` from the example file with your hostname and a random `rails.secret_key` filled in, a `Caddyfile`, and a 1024-bit RSA `signing.key`. Existing files are never overwritten. Also generates `docker-compose.yml` for the latest release. |
+| `postal initialize` | Pull the image and run `postal initialize` inside a temporary container to create the main database and load the schema. |
+| `postal upgrade [version]` | Upgrade to the given version (or the latest release). See [Upgrading](/getting-started/upgrading). |
+| `postal upgrade-db` | Run database migrations only, without pulling a new image or restarting. Useful after restoring a database from another installation. |
+| `postal set-version x.x.x` | Regenerate `docker-compose.yml` for a specific version without pulling or restarting anything. |
+
+## Other tools
+
+These run the corresponding command from the [container image](/other/containers#other-commands) in a temporary `runner` container.
+
+| Command | Description |
+|---|---|
+| `postal make-user` | Interactively create a global administrator user (prompts for e-mail address, first name, last name and password). |
+| `postal default-dkim-record` | Print the DKIM TXT record to publish at `postal._domainkey.{return path domain}`. |
+| `postal test-app-smtp address` | Send a test e-mail using the `smtp` section of your configuration. |
+| `postal console` | Open a Rails console against your installation. |
+| `postal version` | Print the version of Postal in the configured image. |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--version x.x.x` | With `bootstrap` or `upgrade`, use this version instead of looking up the latest release on GitHub. |
+| `--no-git-pull` | With `upgrade`, skip updating the helper repository first. |
+| `--dev` | Print the commands that would be run instead of running them. |
+
+Looking up the latest release requires `curl` and `jq` and makes an unauthenticated request to the GitHub API, which is rate limited. If you hit the limit, pass an explicit version.
+
+## Customising the installation
+
+### Number of workers
+
+To run more than one worker container, add a `docker-compose.override.yml` (see below) that sets the number of replicas for the `worker` service. This survives upgrades, whereas `postal start --scale worker=3` is reset to one worker the next time `postal upgrade` runs.
+
+```yaml
+services:
+  worker:
+    deploy:
+      replicas: 3
+```
+
+### Overriding the compose file
+
+Docker Compose automatically merges `docker-compose.override.yml` from the same directory. Use this for changes such as [log drivers](/features/logging#redirecting-logs-to-the-host-syslog), extra environment variables or resource limits, so that they survive upgrades (the generated `docker-compose.yml` is replaced on every upgrade).
+
+### Hooks
+
+If a `hooks` directory exists in `/opt/postal/install`, the Bash script with the matching name in it is run at various points. Available hook names are `pre-start`, `post-start`, `pre-stop`, `post-stop`, `pre-restart`, `post-restart`, `pre-initialize-pull`, `pre-initialize`, `post-initialize`, `pre-upgrade-pull`, `post-upgrade-pull`, `pre-upgrade-db`, `post-upgrade-db`, `post-upgrade`, `pre-bootstrap`, `post-bootstrap` and `set-postal-version`.
+
+## The generated compose file
+
+For reference, the v3 template starts the following services, all using host networking and mounting `/opt/postal/config` at `/config`:
+
+* `web` - `postal web-server`
+* `smtp` - `postal smtp-server` with the `NET_BIND_SERVICE` capability
+* `worker` - `postal worker`
+* `runner` - a `tools` profile service used by the helper for one-off commands; it is not started by `postal start`

content/3.features/click-and-open-tracking.md

@@ -1,29 +1,42 @@
 ---
 title: Click & Open Tracking
-description: ''
+description: 'Track when recipients open your e-mails and click links within them.'
 category: Features
 ---
 
 Postal supports tracking opens and clicks from e-mails. This allows you to see when people open messages or they click links within them.
 
 <img src="/screenshots/tracked-message.png" width="1280" alt=""/>
 
-
 ## How it works
 
-Once enabled, Postal will automatically scan your outgoing messages and replace any links and images with new URLs that go via your Postal web server. When the link is clicked, Postal will log the click and redirect to the user to the original URL automatically. The links that are included in the e-mail should be on the same domain as the sender and therefore you need to configure a subdomain like `click.yourdomain.com` and point it to your Postal server.
+Once enabled, Postal will automatically scan your outgoing messages and replace any links with new URLs that go via your Postal web server, and insert a tracking image into HTML messages. When the link is clicked, Postal will log the click and redirect the user to the original URL automatically. The links that are included in the e-mail should be on the same domain as the sender and therefore you need to configure a subdomain like `click.yourdomain.com` and point it to your Postal server.
+
+For a message to be rewritten, all of the following must be true:
+
+* The message is an outgoing message with an authenticated sending domain.
+* The server has a **tracking domain** attached to that sending domain (e.g. `click.yourdomain.com` for messages from `yourdomain.com`).
+* The tracking domain's DNS check has passed - its status must be **OK**. Postal checks for a CNAME record at the tracking domain pointing at the value of `dns.track_domain` in your configuration (`track.postal.example.com` in the [DNS configuration](/getting-started/dns-configuration) examples). Tracking domains are re-checked automatically every hour.
+* The message does not have an `X-AMP: skip` header.
+
+Tracking domains have three options which are all enabled by default:
+
+* **SSL** - rewritten URLs use `https://`. You must have a valid certificate for the tracking domain on your web proxy. It is **highly** recommended to leave this enabled as anything else is likely to cause problems with reputation and user experience.
+* **Track loads** - a 1&times;1 pixel image is inserted before the closing `</body>` tag of HTML parts. When loaded, a `MessageLoaded` webhook is sent.
+* **Track clicks** - `http://` and `https://` URLs in plain text parts and `href` attributes in HTML parts are replaced with tracking URLs. When clicked, a `MessageLinkClicked` webhook is sent.
 
 ## Configuring your web server
 
-To avoid messages being marked as spam, it's important that the subdomain that Postal uses in the re-written URLs is on the same domain as that sending the message. This means if you are sending mail from `yourdomain.com`, you'll need to setup `click.yourdomain.com` (or whatever you choose) to point to your Postal server.
+To avoid messages being marked as spam, it's important that the subdomain that Postal uses in the re-written URLs is on the same domain as that sending the message. This means if you are sending mail from `yourdomain.com`, you'll need to set up `click.yourdomain.com` (or whatever you choose) to point to your Postal server.
 
-There are two ways how to achive that traffic to `click.yourdomain.com` will reach Postal:
-1. Adding CNAME record for `click.yourdomain.com` to previously configured `track.postal.example.com` followed by Caddy additional configuration.
-2. Configuring custom proxy for `click.yourdomain.com` on your webserver.
+There are two parts to this:
+
+1. Add a CNAME record for `click.yourdomain.com` pointing to your configured `dns.track_domain` (e.g. `track.postal.example.com`). This is what Postal's DNS check looks for.
+2. Configure your web proxy to send requests for `click.yourdomain.com` to the Postal web server with the `X-Postal-Track-Host: 1` header added. Postal uses this header (and nothing else - the `Host` header is not checked) to decide that a request is a tracking request.
 
 ### Additional Caddy configuration
 
-If you used Caddy as proxy for overall Postal traffic it easy to add additional proxy its config `/opt/postal/config/Caddyfile`:
+If you used Caddy as the proxy for overall Postal traffic it is easy to add an additional proxy to its config `/opt/postal/config/Caddyfile`:
 
 ```
 # ... previous content
@@ -48,23 +61,33 @@ Once you have configured this, you should be able to visit your chosen domain in
 ### Setting up tracking domain
 
 If you're happy things are working, you can enable tracking as follows:
-1. Find the web server you wish to enable tracking on in the Postal web interface
+1. Find the mail server you wish to enable tracking on in the Postal web interface
 2. Go to the **Domains** item
 3. Select **Tracking Domains**
 4. Click **Add a tracking domain**
-5. Enter the domain that you have configured and choose the configuration you want to use. It is **highly** recommended that you use SSL for these connections. Anything else is likely to cause problems with reputation and user experience.
+5. Enter the subdomain (a single label such as `click`) and select the sending domain it belongs to, then choose the options you want to use.
+
+Postal will check the CNAME record immediately. You can re-run the check with the **Check DNS** button; tracking is only applied to messages once the status is **OK**.
+
+## Requests served by the tracking host
+
+| Path | Behaviour |
+|---|---|
+| `/img/{server-token}/{message-token}` | Records an open (once per request) and returns the 1&times;1 PNG. |
+| `/{server-token}/{link-token}` | Records the click and responds with a `307` redirect to the original URL. Returns `404 Link not found` for an unknown token. |
+| Anything else (including `/`) | Returns `200 Hello.` - useful for checking your proxy configuration. |
 
 ## Disabling tracking on a per e-mail basis
 
-If you don't wish to track anything in an email you can add a header to your e-mails before sending it.
+If you don't wish to track anything in an email you can add a header to your e-mails before sending it. No links or images will be rewritten.
 
 ```text
 X-AMP: skip
 ```
 
 ## Disabling tracking for certain link domains
 
-If there are certain domains you don't wish to track links from, you can define these on the tracking domain settings page. For example, if you list `yourdomain.com` no links to this domain will be tracked.
+If there are certain domains you don't wish to track links from, you can define these on the tracking domain settings page (one per line). The host of each link is compared exactly against this list, so `yourdomain.com` excludes links to `https://yourdomain.com/...` but not `https://www.yourdomain.com/...` - list each host separately.
 
 ## Disabling tracking on a per link basis