mailpelican

Mail Pelican 📨

The open-source, self-hostable, agent-native email marketing platform.

Mail Pelican is an AGPL-3.0 Mailchimp alternative designed from the ground up for self-hosters and for AI agents as first-class operators. It is currently at milestone M1: the first safe send. The /v1 API covers contacts, lists, consent (including double opt-in: public subscribe → confirmation email → single-use confirm), suppressions, relays (SES v2, Resend, SMTP), sender identities, templates, campaigns (lint → preview → prepare → confirmation token → send), provider webhook inbox, RFC 8058 one-click unsubscribe, open/click tracking (pixel + redirect links, per-contact opt-out), stats, and audit events. The worker runs the outbox-backed send pipeline with per-dispatch consent rechecks and bounce/complaint auto-pause.

Quickstart

Prerequisites: Node 24 (>= 22 works locally), pnpm 10, Docker.

# Start PostgreSQL and Redis
docker compose -f docker/docker-compose.yml up -d postgres redis

# Configure the environment (see packages/config for the full schema)
export APP_URL=http://localhost:3000 \
       PUBLIC_URL=http://localhost:3000 \
       TRACKING_URL=http://localhost:3000 \
       DATABASE_URL=postgres://dispatch:dispatch@localhost:5432/dispatch \
       REDIS_URL=redis://localhost:6379 \
       CREDENTIAL_ENCRYPTION_KEY=$(openssl rand -hex 32) \
       SESSION_SECRET=$(openssl rand -hex 32)

pnpm install
pnpm build
pnpm --filter @mailpelican/db migrate   # apply database migrations
pnpm --filter @mailpelican/api bootstrap "My Workspace" "My Org Inc" "1 Main St"
pnpm dev                             # api on :3000, web on :5173, worker

The bootstrap command prints the owner API key exactly once; store it. All /v1 calls authenticate with Authorization: Bearer dk_....

Tests run without Docker (PGlite in-process PostgreSQL). The Testcontainers-based suite runs additionally when a Docker daemon is present and MAILPELICAN_DOCKER_TESTS=1 is set.

A full all-in-one container (API + worker + web static bundle) is available via docker compose -f docker/docker-compose.yml up --build app. The image runs pnpm build internally, so no local build artifacts are required.

Repository layout

apps/
  api/        Hono REST API under /v1, OpenAPI, API-key auth, public routes
  mcp/        MCP server (stdio) exposing the /v1 surface to agents
  web/        Vite + React 19 control surface (stub)
  worker/     BullMQ worker: send pipeline, webhook normalization, scheduler
packages/
  config/     Zod-validated environment configuration, fail-fast
  db/         Drizzle ORM schema, migrations, repositories (PostgreSQL 16)
  domain/     State machines, consent decisions, tokens, merge tags, retry
  contracts/  API conventions: RFC 9457 problem details, cursor pagination
  relays/     RelayProvider contract + SES v2 / Resend / SMTP drivers
  render/     React Email design documents → HTML/text artifacts (ADR-0002)
  queue/      Job contracts, outbox dispatcher, rate limiters
  testkit/    Fake relay, controlled clock
docker/       docker-compose for local dev and the all-in-one image
docs/adr/     Architecture decision records

Use with AI agents

Mail Pelican is being built agent-native: every operation the UI exposes is also reachable by automation. A first-class MCP server (apps/mcp) exposes the /v1 surface — reads, lists, and campaign draft authoring — over stdio:

{
  "mcpServers": {
    "mailpelican": {
      "command": "node",
      "args": ["apps/mcp/dist/index.js"],
      "env": { "MAILPELICAN_API_URL": "http://localhost:3000", "MAILPELICAN_API_KEY": "dk_..." }
    }
  }
}

Sending is deliberately not an MCP tool: an agent drafts and previews, the confirmed send stays behind the single-use confirmation flow.

Documentation

• Architecture decision records
• Contributing
• Security policy

License

AGPL-3.0. See THIRD_PARTY_NOTICES.md.