Setup

The setup process for Broadcast is straightforward and involves a few simple steps.

Step 1: Create your admin account

When you first access your Broadcast installation, you’ll be greeted with a split-screen onboarding page. Fill in your name, email address, and password to create the admin account.

This first account is the administrator. You can add more users later, see Users & Permissions.

Step 2: Create your first channel

Channels are like mailing lists: they help you organize subscribers and send targeted campaigns. Give your first channel a descriptive name like “Newsletter” or “Product Updates”.

Step 3: Confirm your domain

Broadcast will auto-detect your server’s IP address and domain. Confirm that the domain shown matches the URL where you installed Broadcast.

Step 3: Confirm your installation domain

Step 4: Configure sender details

After completing the onboarding wizard, you’ll land on the dashboard. A card in the bottom-right corner tells you how many setup steps are still missing before you can send emails.

The card starts collapsed so it never covers the page. Click it to expand the checklist: it remembers that choice, and interacting with the page again closes it. Once every step is done, the card stops appearing.

Dashboard showing the setup checklist with remaining tasks

Navigate to Settings → Sender Details to configure:

Sender name: The display name recipients see (e.g., “John from Acme”)
Sender email: The “From” email address (e.g., john@acme.com)
Physical address: Recommended for CAN-SPAM and GDPR compliance
Email footer: Added to every broadcast and sequence email (includes an unsubscribe link by default). It is on the Email Footer tab of Sender Details

Sender Settings, Details tab, with the sender name, sender email, and physical address filled in

Step 5: Add an email server

Navigate to Settings → Email Servers and click Add email server. You’ll see three options:

Add Email Server dialog showing Guided Setup, Manual Setup, and Test Server options

Guided Setup (Recommended)

The easiest option. Select your email provider (Postmark, AWS SES, SendGrid, or Mailgun), paste your API key, and Broadcast will automatically configure domains, senders, and webhooks.

Provider picker showing Postmark, AWS SES, SendGrid, and Mailgun

Manual Setup

For advanced users or providers not supported by Guided Setup (Resend, SMTP.com, Inboxroad, or custom SMTP). You’ll configure SMTP or API settings manually.

Test Server

Requires a license key. Lets you try sending without emailing real people.

The test server captures every email in your private test inbox and never delivers it, so a message it accepts will not arrive in anyone’s mailbox, even your own. Broadcast marks it delivered because the test server accepted it.

To read what you sent, open the email server in Settings > Email Servers and click View Test Inbox. Captured mail is kept for 7 days.

2.49+

Broadcast also shows where captured mail went:

When you send a broadcast and every server it uses is a test server, the notice says the mail was captured in the test inbox, with a View test inbox link.
A broadcast or transactional email sent through the test server has a Captured, not delivered badge next to its status, on its page, in its list and on the dashboard. When the test inbox is available, the badge links to it. A broadcast that went partly through a real server reads N captured, not delivered instead.
In a broadcast’s Recent Activity, a captured recipient always has the status Captured, not delivered, and a Captured filter lists them. See Recent Activity.

The badge is recorded when the mail is sent, so it stays correct after you delete the test server or add a real one. Mail sent through a test server before 2.49 gets the badge too, if that server is still a test server.

When you are ready to send to real people, set up a real email server. As soon as a real server is active in a channel, Broadcast switches that channel’s test server off, so no real subscriber’s email ends up in the test inbox. You can turn it back on in Settings > Email Servers if you want to test again; while a real server is active, sends set to use any email server still skip it, and it is only used by broadcasts that select it by name.

The test server stays on in two cases. One is when an unsent broadcast, a sequence or a pending transactional email is set to use it specifically (selected by name, not “use any email server”). The other is when it is the only server in the channel for broadcasts, sequences or transactional emails, for example because your real server isn’t enabled for transactional emails. Once nothing needs it, switch it off yourself in Settings > Email Servers.

Email Server Delivery Methods

Broadcast supports two delivery methods:

SMTP Delivery

Traditional SMTP delivery works with all email service providers. You’ll need:

SMTP server address and port
SMTP username and password
Authentication type (Plain, Login, or CRAM-MD5)

API Delivery

For improved performance and better error handling. Supported for:

AWS SES: Uses AWS SDK for direct API sending
Postmark: Uses Postmark’s REST API with message stream support
SendGrid: Uses SendGrid’s v3 API with domain authentication
Mailgun: Uses Mailgun’s API with per-domain webhook tracking

API delivery provides faster sending, better error messages, and reduced infrastructure requirements (no SMTP ports needed).

Troubleshooting

“Domain configuration missing” in step 3

The onboarding page shows Domain configuration missing, and confirming shows Domain configuration is missing. Please set up the domain file on your server.

Cause: step 3 reads the domain from the TLS_DOMAIN variable in /opt/broadcast/app/.env, and that variable is empty or missing. The automatic installer writes it from the domain you entered.

Fix: connect to the server and open /opt/broadcast/app/.env. Only the broadcast user and root can read this file, so use sudo to open it.

If it has no TLS_DOMAIN= line, run ./broadcast.sh fix from /opt/broadcast. It adds the line from the installer’s domain file, /opt/broadcast/.domain. If that file is missing too, fix reports TLS_DOMAIN missing and .domain not found — cannot derive the domain; add the line yourself.
If the line is there but empty, set it to your domain, for example TLS_DOMAIN=mail.example.com.

Then run ./broadcast.sh restart and refresh the page. On a manual installation, set TLS_DOMAIN in your environment file and restart the app.

The domain in step 3 is wrong

Cause: the server was installed with a different domain than the one in your browser.

Fix: point the correct domain’s DNS at the server first. Then run this on the server and answer the prompts:

Shell

cd /opt/broadcast
./broadcast.sh change_installation_domain

It updates the domain configuration, restarts the services and requests a new SSL certificate. See the CLI Reference.

“A license key is required to use the test server”

2.49+

A license key is required to use the test server. Add LICENSE_KEY to the .env file in your app folder, then recreate the containers: run ./broadcast.sh restart on an automatic install, or docker compose -f docker-compose.manual.yml up -d on a manual install. See https://sendbroadcast.net/docs/setup?v=2.49#a-license-key-is-required-to-use-the-test-server.

Cause: the test server signs in with your license key, and Broadcast found none. Broadcast reads the key from the LICENSE_KEY (or BROADCAST_LICENSE_KEY) environment variable.

Fix: the automatic installer writes LICENSE_KEY to /opt/broadcast/app/.env. On a manual installation, add LICENSE_KEY to the app .env file with the key from your customer dashboard. Then recreate the containers so they read the file: run ./broadcast.sh restart on an automatic installation, or docker compose -f docker-compose.manual.yml up -d on a manual installation. A plain docker compose restart does not read the .env file again. Click Test Server again. See Getting a License.

“Cannot configure webhooks: no public domain configured”

Guided Setup for Postmark, SendGrid or Mailgun can stop with:

Cannot configure webhooks: no public domain configured. Set TLS_DOMAIN or configure a hosted domain in Installation settings.

Cause: the provider needs a public URL to send delivery events to, and Broadcast has no domain to build it from.

Fix: finish step 3, or set TLS_DOMAIN as described above. Broadcast skips localhost and 127.0.0.1, so an installation that only answers on localhost cannot set up webhooks. Then run Guided Setup again.

Next Steps

Once your channel is configured with sender details and at least one email server, you’re ready to: