Send bulk campaigns with Plunk
Self-host or use hosted Plunk, verify a domain, separate secret and public keys, and send campaigns while tracking delivery beyond the API response.
Reviewed
Plunk combines transactional sending, campaigns, segments, and workflows in one application. Its delivery path is Amazon SES, whether you use hosted Plunk or run the self-hosted Compose stack. Choose it when you want app-triggered messages and newsletter editions under one API and can accept AWS as the transport dependency.
This guide covers the campaign and bulk path. Hosted domain setup, transactional sends, and workflow webhooks have separate Plunk server guides.
Prerequisites
- A verified sending domain. A campaign’s From address must be on a verified domain.
- A secret
sk_API key for server-side sends and campaign management. - For self-hosting: Docker Compose, PostgreSQL, Redis, MinIO, and ntfy, plus the documented AWS SES integration.
- SES IAM credentials and a configuration set if you operate the self-hosted path.
- A test mailbox you control and a suppression process for bounces and complaints.
The Plunk repository and API overview are the current references. The application is AGPLv3; SES usage is a separate AWS cost.
Hosted or self-hosted
Hosted Plunk removes the container stack and leaves domain verification, keys, and API behavior. Self-hosting adds PostgreSQL, Redis, MinIO, ntfy, nginx, and SES configuration. The self-hosting Compose guide lists the services and the minimal environment:
JWT_SECRET=...
DB_PASSWORD=...
API_DOMAIN=api.yourdomain.com
DASHBOARD_DOMAIN=app.yourdomain.com
LANDING_DOMAIN=www.yourdomain.com
WIKI_DOMAIN=docs.yourdomain.com
USE_HTTPS=true
AWS_SES_REGION=us-east-1
AWS_SES_ACCESS_KEY_ID=...
AWS_SES_SECRET_ACCESS_KEY=...
SES_CONFIGURATION_SET=plunk-tracking
Run the health check after startup:
curl https://api.yourdomain.com/health
A 200 response proves the API process is serving, not that SES can deliver. Send a controlled message before importing an audience.
Keep the two key types separate
The secret sk_ key authorizes sending and campaign management. The public pk_ key only works with /v1/track for client-side event tracking. A public tracking key is not a send capability; putting it in frontend code is expected, and putting an sk_ key there is a credential leak.
Public /v1/send and /v1/track responses use a success/data envelope. Dashboard resources such as contacts, templates, campaigns, and segments return the resource directly. Do not apply one response parser to every endpoint. The API overview documents both shapes.
Prepare the campaign audience
Create or import contacts, then build a segment. A campaign stays in DRAFT after creation; its From address must be on a verified domain. Send a test to one address before scheduling:
curl -X POST https://next-api.useplunk.com/campaigns/CAMPAIGN_ID/test \
-H "Authorization: Bearer $PLUNK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"test-plunk@mailkite.dev"}'
Then send or schedule it:
curl -X POST https://next-api.useplunk.com/campaigns/CAMPAIGN_ID/send \
-H "Authorization: Bearer $PLUNK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"scheduledFor":"2026-11-08T15:00:00Z"}'
Omit scheduledFor for an immediate send. The API supports cancel for a SCHEDULED or SENDING campaign, and a stats endpoint for send, open, click, and bounce counts. Deleting a campaign with active executions returns 409; cancel or let them finish first.
Treat acceptance and delivery as different states
A queued send is not a delivered audience. Read campaign stats and the activity feed, and connect bounce and complaint events to your suppression state. Plunk documents webhooks as a workflow capability: a system event such as email.bounce or email.delivery triggers a workflow, and a Webhook step forwards the payload. That is not an account-wide subscription API identical to another provider’s.
Authenticate the webhook target, persist events before acknowledging them, and process duplicates idempotently. Keep system delivery events separate from user-supplied tracking events; a public track request claiming email.delivery must not be treated as a provider outcome.
Rate limits matter in bulk work: Plunk documents 1,000 API requests per minute per project, throttled email sending, and automatic queueing for bulk operations. A 429 is a signal to back off, not to increase concurrency.
Where MailKite fits
MailKite, which we build, is a hosted sending and receiving API. It does not provide Plunk’s campaign editor or workflow canvas. It supports broadcasts and personalized batches but prohibits unsolicited bulk or commercial mail, sending without consent, and sending after opt-out.
If you already own campaign state and need a different transport, read MailKite sending and the bulk email guide. Moving from Plunk is not a key swap: re-verify domains, recreate templates and suppressions, and keep one delivery path per message.
Next steps
- Use the hosted transactional guide for the single-send contract.
- Configure workflow webhooks for delivery feedback.
- Compare every option in the open-source bulk email comparison.
Sources reviewed 2026-11-07: Plunk API overview, Docker deployment, project repository, and the AGPLv3 license.