Get started

Getting started

This guide takes you from nothing to your first message sent through Postmark, in about five minutes. If you only want to try postmarkd without a Postmark account, jump to Try it without Postmark.

#What you need

• A Linux host with systemd, or anywhere you can run a container.
• A Postmark account with a server API token (Postmark → Servers → your server → API Tokens).
• A verified sender: an address or domain you've confirmed in Postmark. Postmark only sends from verified senders.

#1. Install

Pick one. Packages are the easiest way to run postmarkd under systemd. Every release is on the releases page, for amd64 and arm64.

Debian, Ubuntu (.deb):

VERSION=0.1.0
ARCH=$(dpkg --print-architecture)   # amd64 or arm64
REL=https://github.com/rossedman/postmarkd/releases/download/v$VERSION
curl -fsSLO $REL/postmarkd_${VERSION}_linux_$ARCH.deb
sudo apt install ./postmarkd_${VERSION}_linux_$ARCH.deb

Fedora, RHEL, Rocky, Amazon Linux (.rpm):

VERSION=0.1.0
ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')
REL=https://github.com/rossedman/postmarkd/releases/download/v$VERSION
sudo dnf install $REL/postmarkd_${VERSION}_linux_$ARCH.rpm

Both packages install /usr/bin/postmarkd, the systemd units, a postmarkd system user and a commented config file at /etc/postmarkd/postmarkd.conf. They don't start the service; you do that in step 4 once a token is in place.

Just the binary, for example to use postmarkd send on a workstation or to run it without systemd:

VERSION=0.1.0
ARCH=amd64   # or arm64
REL=https://github.com/rossedman/postmarkd/releases/download/v$VERSION
curl -fsSL $REL/postmarkd_${VERSION}_linux_$ARCH.tar.gz | tar xz postmarkd
sudo install -m 0755 postmarkd /usr/local/bin/postmarkd

As a container:

docker pull ghcr.io/rossedman/postmarkd:0.1

Containers are configured entirely with environment variables. See Containers and sidecars; the rest of this guide uses systemd.

From source (Go 1.23 or newer), which installs the same files as the packages:

git clone https://github.com/rossedman/postmarkd && cd postmarkd
sudo make install

curl -fsSLO https://github.com/rossedman/postmarkd/releases/download/v$VERSION/checksums.txt
sha256sum --ignore-missing -c checksums.txt

#2. Add your Postmark token

Store the server token where only root can read it. systemd hands it to the daemon privately as a credential, so it never appears in a config file or the environment:

sudo install -m 0600 /dev/stdin /etc/postmarkd/server-token <<< 'your-server-token'

#3. Set a default sender

Open /etc/postmarkd/postmarkd.conf and set the address mail comes from when a message doesn't say:

POSTMARKD_DEFAULT_FROM=noreply@yourdomain.com

Every option is listed in Configuration. The defaults are sensible: the HTTP API listens on the unix socket /run/postmarkd/postmarkd.sock, and SMTP is off.

#4. Start the daemon

sudo systemctl enable --now postmarkd
systemctl status postmarkd

systemctl status shows Accepting mail on /run/postmarkd/postmarkd.sock once it's ready. If it isn't running, journalctl -u postmarkd says why, and postmarkd -config /etc/postmarkd/postmarkd.conf -check-config validates the configuration.

#5. Send your first message

The socket belongs to the postmarkd group. Add yourself (and any app user that will send mail), then log in again:

sudo usermod -aG postmarkd "$USER"

Now send:

echo "Hello from $(hostname)" | postmarkd send -to you@example.com -subject "It works"

It prints the Postmark MessageID. The same message over HTTP:

curl --unix-socket /run/postmarkd/postmarkd.sock http://localhost/email \
  -d '{"To": "you@example.com", "Subject": "It works", "TextBody": "Hello"}'

#6. Connect your software

Sending mail covers each of these in detail.

#7. Make your domain trusted

Before sending real volume, check that your domain's DKIM, Return-Path and DMARC records are in place, or your mail may land in spam:

postmarkd check-domain yourdomain.com

See Email authentication.

#Try it without Postmark

Blackhole mode accepts mail exactly as Postmark would, sends nothing, and keeps what was "sent" so you can look at it. No account or token needed:

docker run --rm -p 8025:8025 -p 2525:2525 -e POSTMARKD_BLACKHOLE=true ghcr.io/rossedman/postmarkd:0.1

In another terminal:

curl localhost:8025/email -d '{"From":"me@example.com","To":"you@example.com","Subject":"Hi","TextBody":"Hello"}'
curl localhost:8025/blackhole/messages

More in Testing.

#Next steps

• Sending mail: every way to send, streams and batches
• Containers and sidecars: Docker Compose, Kubernetes, CI
• Deployment and operations: hardening, scaling and monitoring