Docs Get key
All guides
Bulk email

Run event-driven email with Dittofeed

Self-host Dittofeed with PostgreSQL, ClickHouse, and Temporal, ingest Segment-style events, and send broadcasts or journeys through SMTP or a provider.

Reviewed

Dittofeed is an event-driven messaging platform. Choose it when email decisions should follow product behavior: signup, activation, plan change, abandonment, or a completed task. It accepts Segment-compatible events, builds segments and journeys from them, and sends through a provider integration or SMTP. It is not a newsletter editor, and it brings a larger data stack than a campaign tool.

This guide covers the self-hosted path and the boundary between event ingestion and email delivery. The Dittofeed documentation is the primary reference.

What you operate

The “lite” Compose manifest still includes PostgreSQL, ClickHouse, and Temporal, plus supporting services. That is the important planning fact: lite is not one process. You need:

  • PostgreSQL for application state.
  • ClickHouse for event data.
  • Temporal for durable workflow execution.
  • Object storage or the services included in the manifest.
  • A provider integration or SMTP credentials for email.

Plan for event retention and workflow-service health as well as ordinary application and database backups. The self-hosting guide explains the Compose path.

Start from a reviewed environment

Clone the repository and use the documented docker-compose.lite.yaml. Override the default credentials before first boot:

git clone https://github.com/dittofeed/dittofeed.git
cd dittofeed
touch .env

The documentation lists variables for the database, ClickHouse, application password, and secret key. Generate a new SECRET_KEY rather than shipping the example. Set DASHBOARD_URL and DASHBOARD_API_BASE before exposing the service on a real domain, because they generate dashboard and unsubscribe links.

docker compose -f docker-compose.lite.yaml up -d

If a port conflicts with another service, change the published port and update DASHBOARD_API_BASE to match. A restart with --force-recreate applies the change. Confirm the dashboard loads, the API responds, and Temporal reports healthy workers before importing real events.

Ingest events with a write key

Dittofeed exposes Segment-compatible endpoints for identify, track, page, and screen under /api/public/apps/. Authenticate with a workspace write key as an HTTP Basic header. The documentation explicitly allows this write key in a client payload, which makes it a tracking credential, not a send credential.

curl -H 'Content-Type: application/json' \
  -H "Authorization: Basic $DITTOFEED_WRITE_KEY" \
  -X POST \
  -d '{"userId":"user_123","messageId":"msg_123","traits":{"email":"test-dittofeed@mailkite.dev"}}' \
  https://dittofeed.example.com/api/public/apps/identify

Treat messageId as your deduplication identity. Generate it once per intended event and persist it before the request; treating every replay as a new event can enroll the contact again or send another message.

Validate that the email trait is an address you are allowed to mail. Event ingestion is not consent. An identify call that adds an address to a segment does not establish that the person opted in.

Separate journeys from broadcasts

Dittofeed’s public core includes broadcasts, automated journeys, templates, and channels beyond email. Use a broadcast for a prepared edition to a segment, and a journey for stateful sequences with delays and exits. For email, configure a provider integration or SMTP in the workspace; event ingestion and delivery credentials are different interfaces.

Before enabling a journey, test:

  • Entry and exit conditions, including an exit that arrives before the delay ends.
  • Duplicate events with the same message ID and with a new message ID.
  • A contact with a missing optional trait.
  • A failed send and the retry or suppression behavior that follows.

ClickHouse event volume grows with product activity, not only with email volume. Set retention deliberately and monitor ingestion lag. A healthy dashboard with a stalled Temporal worker can look fine while nothing sends.

License boundary

Broadcasts and journeys belong to the MIT-licensed core. Multi-tenancy, embedding, and white-labeling are part of a separately licensed closed-source offering described in the project README. If you need to embed a campaign builder in your own product, the MIT license alone does not supply that feature set.

Where MailKite fits

MailKite, which we build, is a hosted sending and receiving API. It does not provide Dittofeed’s event store or journey engine. It supports broadcasts and personalized batches but prohibits unsolicited bulk or commercial mail, sending without consent, and sending after opt-out.

If your application already owns event state and needs a transport, read programmatic email and MailKite sending. Do not treat event ingestion as consent, and do not run the same journey through two senders without a shared suppression and deduplication boundary.

Next steps

Sources reviewed 2026-11-07: Dittofeed self-hosting, API source, email channel, and the license.