plunk
/plunk
Wysyła maile transakcyjne i marketingowe przez Plunk: wysyłki z aplikacji, automatyzacja maili i kampanie drip w prostej platformie open source.
- Autor
- TerminalSkills ↗
- Repozytorium
- skills ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 25.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 10
Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
Co robi i kiedy
Wysyła maile transakcyjne i marketingowe przez Plunk: wysyłki z aplikacji, automatyzacja maili i kampanie drip w prostej platformie open source.
Oryginalny opis (EN)
Send transactional and marketing emails with Plunk. Use when a user asks to send emails from an app, set up email automation, create drip campaigns, or use a simple open-source email platform.
Jak działa
- Overview
- Instructions
- Examples
- Guidelines
Podgląd SKILL.md
---
name: plunk
description: >-
Send transactional and marketing emails with Plunk. Use when a user asks to
send emails from an app, set up email automation, create drip campaigns, or
use a simple open-source email platform.
license: Apache-2.0
compatibility: 'Any platform via REST API'
metadata:
author: terminal-skills
version: 1.1.0
category: business
repository: https://github.com/useplunk/plunk
tags: "plunk, email, transactional, marketing, automation"
---
# Plunk
## Overview
Plunk is an open-source email platform built on Amazon SES. One API covers transactional email, event-triggered workflows (drip sequences), campaigns (newsletters) and inbound email. Use the hosted service at useplunk.com or self-host it with Docker. The hosted free tier allows 1,000 emails a month; beyond that it is $0.001 per email (attachments count double), per the billing docs.
The API base URL in the current documentation is `https://next-api.useplunk.com`. Older tutorials use `https://api.useplunk.com` and the `@plunk/node` package; follow the current docs for new code and use plain `fetch`.
## Instructions
### Step 1: Keys and sending domain
Each project has exactly two keys (Settings -> API Keys in the dashboard): a secret key (`sk_`) for every endpoint except tracking, and a public key (`pk_`) that can only call `POST /v1/track`. Rotating regenerates both at once and the old pair stops working immediately. Keep `sk_` on the server only.
Verify your sending domain first (dashboard, DNS records for SES). `from` must use a verified domain or the send is refused.
```bash
export PLUNK_SECRET_KEY="sk_..." # from Settings -> API Keys
```
### Step 2: Send a transactional email
`POST /v1/send` needs `to`, plus either `subject` and `body` (HTML) or a `template` ID. `from` is required unless the template sets one.
```typescript
// lib/email.ts
const PLUNK_URL = process.env.PLUNK_API_URL ?? 'https://next-api.useplunk.com'
export async function sendPasswordReset(email: string, resetCode: string) {
const res = await fetch(`${PLUNK_URL}/v1/send`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.PLUNK_SECRET_KEY}`,
'Idempotency-Key': `reset-${email}-${resetCode}`,
},
body: JSON.stringify({
to: email,
from: { name: 'Northwind Billing', email: 'billing@mail.northwind.dev' },
subject: 'Your password reset code',
body: `<p>Your code is <b>${resetCode}</b>. It expires in 15 minutes.</p>`,
}),
})
const json = await res.json()
if (!json.success) throw new Error(`${json.error.code}: ${json.error.message}`)
return json.data // { emails: [{ contact: { id, email }, email: <email record ID> }], timestamp }
}
```
Notes from the API reference:
- `to` may be a string, `{ name, email }`, or an array; arrays are processed one recipient at a time, not as a batch.
- Sending is always immediate. To schedule, use a campaign.
- `body` is HTML; Plunk generates the plain-text part itself (there is no text field).
- Send an `Idempotency-Key` header (1-255 printable ASCII chars, kept 24 hours): a repeated key gets `409` instead of a second email.
- Contacts are created or updated on every send. New contacts default to `subscribed: false` on `/v1/send`, so they are not pulled into marketing sends unless you pass `subscribed: true`.
- In `data`, values are saved on the contact and usable as template variables; use `{ "value": "482913", "persistent": false }` for one-shot secrets such as reset codes or magic links so they are not stored.
- Up to 10 attachments, 10 MB total by default.
### Step 3: Track events to trigger workflows
```typescript
await fetch('https://next-api.useplunk.com/v1/track', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.PLUNK_SECRET_KEY}`, // pk_ key is also accepted here
},
body: JSON.stringify({
event: 'user-signed-up',
email: 'maria.keller@northwind.dev',
data: { firstName: 'Maria', plan: 'free' },
}),
})
```
Then, in the dashboard, create a workflow with an `EVENT` trigger named `user-signed-up`: send the welcome email, wait 3 days, send onboarding tips. Workflows can also start on a schedule or manually (`POST /workflows/:id/executions`). Workflows are created disabled: switch `enabled` on or nothing fires. The trigger event name cannot be changed after the first execution. Event names matching `email.*`, `contact.subscribed`, `contact.unsubscribed` or `segment.<slug>.entry|exit` are reserved and rejected. New contacts from `/v1/track` default to subscribed.
Use the public key in browser code, because it can only track events:
```javascript
fetch('https://next-api.useplunk.com/v1/track', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + PLUNK_PUBLIC_KEY },
body: JSON.stringify({ event: 'pricing-viewed', email: currentUser.email }),
})
```
### Step 4: Contacts and verification
```bash
# Upsert a contact by email
curl -X POST https://next-api.useplunk.com/contacts \
-H "Authorization: Bearer $PLUNK_SECRET_KEY" -H "Content-Type: application/json" \
-d '{"email":"maria.keller@northwind.dev","subscribed":true,"data":{"firstName":"Maria","plan":"pro"}}'
```
`POST /v1/verify` checks an address for typos, disposable domains and MX records. List endpoints use cursor pagination (`limit` up to 100, `cursor`, `hasMore`). The full OpenAPI spec is at `https://docs.useplunk.com/openapi.json`, and every docs page is available as Markdown by appending `.md`.
### Step 5: Self-host (optional)
Download `docker-compose.yml` from a release tag (v0.17.0, 2026-10-21; `next` is a moving branch), set `.env` and run `docker compose up -d`:
```bash
curl -fsSLO https://raw.githubusercontent.com/useplunk/plunk/v0.17.0/docker-compose.yml
echo "8d2a7d31d854e72037fb3c395a96c2cd351b1322d157669c0978f974c83de0ac docker-compose.yml" | sha256sum -c - # hash of the v0.17.0 file
docker compose up -d
```
Required variables include `JWT_SECRET` (generate with `openssl rand -base64 32`), `DB_PASSWORD`, the `API_DOMAIN`, `DASHBOARD_DOMAIN`, `LANDING_DOMAIN`, `WIKI_DOMAIN` hostnames, and AWS SES credentials (`AWS_SES_REGION`, `AWS_SES_ACCESS_KEY_ID`, `AWS_SES_SECRET_ACCESS_KEY`, `SES_CONFIGURATION_SET`). The stack runs plunk, PostgreSQL 16, Redis 7, MinIO and ntfy; only port 80 (and 465/587 for SMTP) needs exposing. Health check: `GET /health` on the API domain. Point your client at your own API domain instead of `next-api.useplunk.com`.
## Examples
### Example 1: "Send a receipt after Stripe checkout"
Call `/v1/send` from the webhook handler with an idempotency key built from the Stripe event ID so webhook retries never send twice:
```bash
curl -X POST https://next-api.useplunk.com/v1/send \
-H "Authorization: Bearer $PLUNK_SECRET_KEY" \
-H "Idempotency-Key: stripe-evt_1QxK2LHn7" \
-H "Content-Type: application/json" \
-d '{"to":"maria.keller@northwind.dev","from":"billing@mail.northwind.dev","subject":"Receipt for order #4812","body":"<p>Thanks! Total: $49.00</p>"}'
```
Result: `{"success":true,"data":{"emails":[{"contact":{"id":"...","email":"maria.keller@northwind.dev"},"email":"..."}],"timestamp":"..."}}`. (`/v1/track` returns `data: { contact, event, timestamp }` with string IDs.) Replaying the same key returns `409`.
### Example 2: "Three-email onboarding sequence"
Track `user-signed-up` from the signup handler (Step 3), then build a workflow triggered by that event: Send email (welcome), Delay 3 days, Send email (tips), Delay 4 days, Send email (upgrade offer). Each contact runs through the workflow independently.
## Guidelines
- `sk_` keys never go in client bundles; use `pk_` with `/v1/track` only. A wrong-prefix key returns `401 INVALID_API_KEY`.
- Check `success` in the response body; errors carry `code`, `message`, `requestId` and a `suggestion`.
- Free-tier projects get a Plunk footer in marketing emails and 1,000 sends a month; inbound mail counts too. Set per-category caps in Settings -> Billing to stop a runaway campaign eating transactional capacity.
- Self-hosting means running SES, Postgres, Redis and DNS yourself; for a small app the hosted plan is simpler. For features Plunk lacks, consider Resend or Postmark.
Pliki w paczce (2)
- SKILL.md 8 KB
- _scores.json 2 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · TerminalSkills/skills | 100 | Apache-2.0 |
| felipefontoura/bento | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki d4a4271a2970 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100loops
Wysyła emaile marketingowe i transakcyjne przez Loops: kampanie drip, aktualizacje produktu i marketing emailowy dla SaaS jako nowoczesna alternatywa dla Mailchimp. - 100plunk-webhooks
Odbiera i uwierzytelnia webhooki Plunk z workflow, sprawdza nagłówek sekretu i obsługuje zdarzenia odbić oraz skarg. - 100email-sequences
Projektuje i pisze kampanie i sekwencje e-mail: onboarding, cykl życia, e-maile transakcyjne, newslettery, wysyłki masowe oraz premiery i ogłoszenia. - 100emails
Tworzy i optymalizuje sekwencje e-mail, kampanie drip, przepływy wyzwalane zdarzeniami i programy e-maili cyklu życia, w tym onboarding, nurture, lejki i rytm wysyłek. - 100emails
Tworzy i optymalizuje sekwencje e-mail, kampanie drip, przepływy wyzwalane zdarzeniami i programy e-maili cyklu życia, w tym onboarding, nurture, lejki i rytm wysyłek. - 100emails
Tworzy i optymalizuje sekwencje e-maili, kampanie drip i automatyczne przepływy cyklu życia klienta, w tym onboarding, powitania, reaktywację i wiadomości wyzwalane zdarzeniami.