Self-host Keila for bulk email
Run Keila with PostgreSQL, create a provider sender, and deliver campaigns through its Bearer-token API without treating a queued response as delivery.
Reviewed
Keila is a self-hosted newsletter application with a visual editor, forms, segments, and a JSON API. Its distinguishing feature is the editor-oriented campaign workflow: people preparing editions can work in the same application your backend drives. Choose Keila when that interface matters and you can run PostgreSQL and a container. Choose listmonk instead when SQL-based audience rules and a single binary matter more; the listmonk vs Keila guide compares the two directly.
Keila manages campaigns and contacts. It does not deliver mail. You create a sender that points at SMTP or a supported provider, and that external service owns delivery, reputation, and feedback. This guide installs Keila, creates the transport boundary, and sends a controlled campaign through the API.
Prerequisites
- A container runtime. Keila is published as the
pentacent/keilaimage. - PostgreSQL 14 or newer, per the installation requirements.
- A reverse proxy that forwards WebSockets. Caddy and Traefik do this by default; nginx needs explicit configuration.
- SMTP credentials or an SES, SendGrid, Mailgun, or Postmark account.
- A verified sending domain and a test mailbox you control.
Configure the container
Keila reads its configuration from environment variables. The configuration reference lists every setting. A minimal Compose service looks like this:
services:
keila:
image: pentacent/keila:latest
ports:
- "4000:4000"
environment:
DB_URL: postgres://keila:replace-me@db:5432/keila
SECRET_KEY_BASE: replace-with-at-least-64-random-characters
URL_HOST: campaigns.example.com
URL_SCHEMA: https
USER_CONTENT_DIR: /data/uploads
MAILER_SMTP_FROM_EMAIL: system@your-sending-domain.example
MAILER_SMTP_HOST: smtp.your-provider.example
MAILER_SMTP_PORT: "587"
MAILER_SMTP_USER: replace-me
MAILER_SMTP_PASSWORD: replace-me
volumes:
- ./uploads:/data/uploads
SECRET_KEY_BASE must be a strong value of at least 64 characters; the documentation suggests head -c 48 /dev/urandom | base64. Add your PostgreSQL service to the same Compose file, or point DB_URL at an existing database. Set KEILA_USER and KEILA_PASSWORD on first boot if you do not want a random root password printed to the container log. Pin a release tag rather than latest for production.
The MAILER_* settings are for Keila’s own system mail, such as registration and password reset. They are separate from the sender used for campaigns. Configure both deliberately.
Create a sender before a campaign
Keila’s sender model makes transport selection explicit. Create an SMTP, SES, SendGrid, Mailgun, or Postmark sender, then select it when building the campaign. Self-hosted Keila does not bundle delivery; “Send with Keila” is a Cloud option.
Send one controlled message through the interface first. Confirm the envelope sender, the visible From address, DKIM alignment, and that a reply reaches a monitored mailbox. A campaign that renders correctly but sends from an unauthenticated domain is not ready.
Import contacts and define segments
Keila stores contacts and can build segments through a visual condition editor or a JSON query. Campaign templates use Liquid and expose contact fields, custom data, and an unsubscribe link. Test the template against a contact with missing optional fields; one successful render does not establish every recipient’s result.
Use double opt-in where subscribers add themselves. Keep the consent record outside the campaign tool as well, because removing a contact from Keila does not erase the evidence that they opted in. Treat an imported CSV as an eligibility question before it is an import job.
Create and deliver through the API
Create a private API key in the dashboard, then send it as a Bearer token. The authentication documentation shows the header form. Campaign creation uses the /api/v1/campaigns endpoint:
curl https://campaigns.example.com/api/v1/campaigns \
-H "Authorization: Bearer $KEILA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"data": {
"subject": "A controlled Keila test",
"sender_id": "ms_replace_me",
"segment_id": "sgm_replace_me",
"settings": { "type": "markdown" },
"text_body": "Hello {{ contact.first_name }}, this is a controlled test."
}
}'
The response includes the campaign ID. Scheduling and delivery are separate actions: POST /api/v1/campaigns/{id}/actions/schedule accepts a scheduled_for value, while POST /api/v1/campaigns/{id}/actions/send queues delivery.
The send action returns 202 Campaign delivery queued. Keila’s documentation explicitly warns that an invalid campaign, such as one missing a sender, or insufficient account credits can prevent delivery regardless of that response. Store the campaign ID and inspect its later state. Do not build a retry loop that treats 202 as proof that every recipient received the message.
Operate the campaign boundary
Keep campaign content, contact data, uploads, and the database in the backup plan. The database alone does not restore uploaded assets. Upgrade on a restored copy and recheck the sender configuration after a major release.
If you run behind a proxy, verify WebSocket forwarding before editors depend on live updates. Monitor the external provider’s bounce and complaint events separately from Keila’s campaign statistics; Keila’s own analytics do not replace the transport’s feedback contract.
Where MailKite fits
MailKite, which we build, is a hosted sending and receiving platform. It supports broadcasts and personalized batches but prohibits unsolicited bulk or commercial mail, sending without consent, and sending after opt-out. It does not provide Keila’s editor.
If you want to keep a campaign application but stop owning delivery, compare programmatic newsletters and the MailKite sending documentation. A move between transports is a new sending decision: recreate senders, verify domains, and recheck suppressions rather than swapping a key in place.
Next steps
- Read the listmonk vs Keila comparison for API and segmentation differences.
- Choose a language path: JavaScript or Python.
- See every tool in the open-source bulk email comparison.
Sources reviewed 2026-11-07: Keila installation, configuration, senders, API authentication, and campaign API.