Docs · Reference
Environment variables
The settings a self-hosted copy reads from its environment, with their defaults. Set them in your compose file, or in a .env file when running from source. Magpie Cloud needs none of this. To get started, see Self-hosting.
Core and sign-in
| Variable | Required | What it does |
|---|---|---|
NODE_ENV | Yes, in production | Set to production. The app then refuses to sign or encrypt anything until TRACKING_SECRET or CREDENTIALS_SECRET is set, instead of using a development key. |
AUTH_EMAIL | Yes | The first login's email. Add more people in Settings, then Team and login. |
AUTH_PASSWORD | Yes | The first login's password. Changing it resets that login's password on the next restart, for when it's forgotten. |
Secrets
Generate each with openssl rand -hex 32. Secrets can't be changed in the app.
| Variable | Required | What it does |
|---|---|---|
TRACKING_SECRET | Yes, in production | Signs tracking and unsubscribe links, and encrypts the credentials saved in Settings. Set it once: rotating it makes saved credentials unreadable. |
CREDENTIALS_SECRET | No | A separate key for credentials saved in Settings: sending provider keys, the SocialFetch key, the verification secret and proxy passwords, and copilot API keys. Defaults to TRACKING_SECRET. Also set once. |
SUPPRESSION_SECRET | Recommended | Keys the hashes behind opt-outs, unsubscribes and bounces. Defaults to TRACKING_SECRET. Never rotate it: people who opted out would reappear. |
URLs
| Variable | Required | What it does |
|---|---|---|
PUBLIC_URL | Recommended | This app's public origin, such as https://crm.example.com. Used for links others open: tracking and unsubscribe links, images in emails, survey links, webhook addresses. Unset: the host of the incoming request. |
PUBLIC_SITE_URL | No | Your website. The unsubscribe page shows a link back to it. Unset: no link. |
SUBSCRIBE_ALLOWED_ORIGINS | No | Comma-separated origins whose pages may call POST /api/subscribe from the browser, such as https://example.com. Unset: none. |
Prospect data
| Variable | Required | What it does |
|---|---|---|
SOCIALFETCH_API_KEY | No | Your SocialFetch key (sfk_…). A key saved in Settings, then Data source takes priority. |
SOCIALFETCH_BASE_URL | No | The SocialFetch API address. Default https://api.socialfetch.dev. |
SOCIALFETCH_BALANCE | No | hidden hides the SocialFetch credit balance; the sidebar shows this month's prospects instead. |
Email verification
Connect your email verifier in Settings, then Email verification, with its server URL and secret. See Email verification.
Sending
A provider saved in Settings, then Sending takes priority. Its saved values win field by field, and these variables fill any field left empty. See Sending and deliverability.
| Variable | Required | What it does |
|---|---|---|
EMAIL_PROVIDER | No | The provider to use when none is saved in Settings, then Sending: smtp, ses, cloudflare, resend, postmark, sendgrid, mailgun, brevo or mailchimp. Unset: ses if the SES keys are set, else cloudflare if its token and account ID are set, else smtp. Only SMTP, SES and Cloudflare take credentials from variables; the rest are set up in Settings. |
SMTP_HOST | No | SMTP server host. |
SMTP_PORT | No | SMTP port. Default 465. |
SMTP_USER | No | SMTP username. |
SMTP_PASS | No | SMTP password. |
SMTP_SENDER | No | A sender such as "Jane Smith" <jane@example.com>, added to Sender addresses on start and used as the default sender when none is set. |
SES_REGION | No | Amazon SES region. Default us-east-1. |
SES_ACCESS_KEY_ID | No | Amazon SES access key ID. |
SES_SECRET_ACCESS_KEY | No | Amazon SES secret access key. |
SES_CONFIGURATION_SET | No | SES configuration set, needed for SES to publish bounce and complaint events. |
SES_MESSAGE_TAGS | No | name=value,… tags added to every email SES sends, and returned on its events. |
CLOUDFLARE_ACCOUNT_ID | No | Cloudflare account ID. |
CLOUDFLARE_API_TOKEN | No | Cloudflare API token with Email Sending: Send, plus Analytics: Read for bounces. |
CLOUDFLARE_ZONE_ID | No | Cloudflare zone ID. Turns on bounce polling. |
Webhooks and bounces
| Variable | Required | What it does |
|---|---|---|
WEBHOOK_SECRET | For bounce tracking | Turns on the bounce and complaint webhooks, which refuse every request until it's set. Providers send it as ?s= or a Bearer token. |
For plain SMTP, the Cloudflare Email Worker in the repository's cloudflare-worker/ folder takes two variables of its own, set in Cloudflare: BOUNCE_WEBHOOK_URL (such as https://crm.example.com/api/webhooks/bounce) and the same WEBHOOK_SECRET.
AI copilot
| Variable | Required | What it does |
|---|---|---|
ANTHROPIC_API_KEY | No | Your Anthropic API key for the copilot. A key saved in Settings, then Copilot is used first. |
OPENAI_API_KEY | No | Your OpenAI API key for the copilot. A key saved in Settings, then Copilot is used first. |
COPILOT_CHROMIUM_PATH | No | Path to a Chrome or Chromium the copilot uses to render email previews. The Docker image already includes one. |
Web push
Generate a key pair with:
Terminal
npx web-push generate-vapid-keys| Variable | Required | What it does |
|---|---|---|
VAPID_PUBLIC_KEY | For push | Web push public key. Push is off unless both keys are set. |
VAPID_PRIVATE_KEY | For push | Web push private key. |
VAPID_SUBJECT | No | Contact for push services. Default mailto: plus AUTH_EMAIL. |
Server
| Variable | Required | What it does |
|---|---|---|
PORT | No | Port to listen on. Default 3000. |
HOST | No | Address to listen on. Default 0.0.0.0. |
DATABASE_PATH | No | Where the JSON data file lives. Uploaded images go in uploads/ next to it. Default local_db.json in the working directory; in Docker, put it on the volume, such as /data/db.json. |
HOME | In Docker | Set to the volume's mount path, such as /data. The container gives its user ownership of $HOME at start, which makes the volume writable. |
The README on GitHub has a commented sample .env file.
Something wrong or missing? Email pele@magpiecrm.com or open an issue.