Configuration

Where configuration lives

• The .env file in the installation folder, copied from .env.example. It holds the address of the instance, the database, the system mail server and switches for optional parts. Docker Compose mounts it read-only into the containers.
• The panel. Mailboxes, SMS providers, AI providers, payments, integrations, API keys and list settings are made in the NetSendo interface and stored in the database.

The containers read .env when they start and the app caches its configuration at start-up, so recreate them after every change:

docker compose up -d --force-recreate

Environment variables you change

The defaults below are those of .env.example and docker-compose.yml. Everything else in .env.example can stay as it is for a Docker installation.

Mailboxes

Campaigns, autoresponders and system emails are sent through mailboxes, set up under Settings → Mailboxes. NetSendo has no sending limit of its own; the volume depends on the provider behind the mailbox.

• Each mailbox is allowed to send any mix of three message types: broadcasts, autoresponders and system emails. A list can have its own default mailbox; a campaign can name one explicitly.
• A list's system emails (signup confirmation, unsubscribe confirmation) go through the list's mailbox. Without one, NetSendo uses the MAIL_* server from .env, and if that is not usable (no host, or localhost), the first active SMTP mailbox allowed to send system emails.
• “Forgot password” on the sign-in page does not depend on any of these: NetSendo emails a new password through its password relay service, so it works even before SMTP is set up.
• Bounces reach NetSendo by reading a bounce mailbox or through provider webhooks at /webhooks/bounce/{provider}/{mailbox} for SendGrid, Mailgun, Postmark or a generic sender. Each request is authenticated: SendGrid and Mailgun with their own signatures, Postmark and generic senders with the per-mailbox token shown in the mailbox settings.

SMS providers

Add SMS gateways under Settings → SMS Providers: Twilio, SMSAPI (smsapi.pl), SMSAPI (smsapi.com), Vonage, MessageBird and Plivo. Each provider has a sender name and an optional daily limit, and a list can name its default provider. Without provider_id, the SMS API uses the default provider, or else the first active one that has not reached its daily limit.

Services, queue worker and scheduler

docker compose up -d starts these services. Emails, SMS, webhooks and imports are processed in the background, so queue and scheduler must run for anything to be sent.

The four NetSendo containers run the same entrypoint. Since 2.7.0 it prepares the database under a MySQL lock (GET_LOCK), so only one container migrates and seeds at a time, and docker-compose.yml leaves that work to app (see start-up variables). With a compose file from an older release the containers take the lock in turn: the first one migrates, the others find nothing left to do. Watch the migrations with:

docker compose logs -f app   # migrations run here; scheduler, queue and reverb wait for them

What the scheduler runs

The scheduler also processes bounce and reply mailboxes, CRM follow-ups, calendar sync, funnels, NMI warming and blacklist checks, and log cleanup. Jobs of GOLD features (Campaign Auditor, Deliverability Shield DNS checks, NMI warming, blacklist checks and DKIM rotation, the autonomous Brain cron and knowledge indexing) run only while the licence includes them.

  queue:
    command: php artisan queue:work --queue=default,notifications --sleep=3 --tries=3 --max-time=3600

HTTPS and a reverse proxy

The web server listens on 127.0.0.1:5029 only, so a public instance needs a reverse proxy such as nginx or Caddy in front of it, with HTTPS. Forward /app/ to Reverb on port 8085 for WebSockets.

server {
    listen 443 ssl http2;
    server_name netsendo.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:5029;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # WebSocket proxy for Reverb
    location /app/ {
        proxy_pass http://127.0.0.1:8085;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;
    }
}

Point the browser at the proxy: with VITE_REVERB_PORT=443 it opens wss:// on the HTTPS port, which the /app/ location forwards to Reverb.

APP_URL=https://netsendo.example.com
VITE_REVERB_HOST=netsendo.example.com
VITE_REVERB_PORT=443
VITE_REVERB_SCHEME=https

Then recreate the containers; the panel hands the browser the new WebSocket address when a page loads (NetSendo 2.7.1 or newer):

docker compose up -d --force-recreate

Email sending options

These variables are not in .env.example, but NetSendo reads them (config/netsendo.php). The defaults suit most installations; add a line to .env only to change one.

Start-up, telemetry and hosting variables

The container entrypoint reads these two from the container environment, not from .env. Change them under environment of a service in docker-compose.yml, then run docker compose up -d.

These are read by the application and go in .env; none of them is in .env.example. What the telemetry report contains is described in Telemetry.

NetSendo Mail Infrastructure (NMI)

NMI is an optional mail transfer agent (Haraka) for sending from your own dedicated IP addresses, with IP warming, DKIM and blacklist monitoring. Enable it in .env and start the stack with the nmi profile, then manage it in the panel under Settings → Mail Infrastructure. Adding pools and IPs, warming, DKIM keys and blacklist checks need a GOLD licence; sending through an NMI set up earlier keeps working without it.

# .env
NMI_ENABLED=true
NMI_MTA_HOST=netsendo-mta
NMI_MTA_PORT=25

# start the stack with the MTA
docker compose --profile nmi up -d

The MTA keeps its queue, logs, DKIM keys and TLS certificates in the nmi-queue, nmi-logs, nmi-dkim and nmi-tls volumes.

Frequently asked questions