Initial push of Plunk Next
This commit is contained in:
Dries Augustyns
@@ -0,0 +1,163 @@
|
||||
---
|
||||
title: Authentication
|
||||
description: Understanding API keys and authentication
|
||||
---
|
||||
|
||||
## Two types of API keys
|
||||
|
||||
Each project has two API keys for different purposes:
|
||||
|
||||
### Secret Key (sk_*)
|
||||
|
||||
**Use for:** All server-side API calls
|
||||
|
||||
- Required for `/v1/send` (sending emails)
|
||||
- Required for all dashboard API endpoints (contacts, campaigns, templates, etc.)
|
||||
- Can access and modify all project data
|
||||
- **Never expose in client-side code**
|
||||
|
||||
**Example:**
|
||||
```javascript
|
||||
// Server-side only
|
||||
fetch('{{API_URL}}/v1/send', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': 'Bearer sk_your_secret_key',
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
to: 'user@example.com',
|
||||
subject: 'Hello',
|
||||
body: '<p>Your order is ready!</p>'
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
### Public Key (pk_*)
|
||||
|
||||
**Use for:** Client-side event tracking only
|
||||
|
||||
- Works **only** with `/v1/track` endpoint
|
||||
- Cannot send emails or access any other endpoints
|
||||
- Safe to include in frontend JavaScript
|
||||
- Use for tracking user behavior from web browsers or mobile apps
|
||||
|
||||
**Example:**
|
||||
```javascript
|
||||
// Client-side safe
|
||||
fetch('{{API_URL}}/v1/track', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': 'Bearer pk_your_public_key',
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
email: 'user@example.com',
|
||||
event: 'button_clicked',
|
||||
data: { button: 'signup' }
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
## Finding your API keys
|
||||
|
||||
1. Log into [Plunk dashboard]({{DASHBOARD_URL}})
|
||||
2. Select your project
|
||||
3. Go to **Settings > API Keys**
|
||||
4. Copy the key you need
|
||||
|
||||
## Using API keys
|
||||
|
||||
All authenticated requests use the `Authorization` header with Bearer token format:
|
||||
|
||||
```bash
|
||||
Authorization: Bearer sk_your_secret_key
|
||||
```
|
||||
|
||||
### cURL example
|
||||
|
||||
```bash
|
||||
curl -X POST {{API_URL}}/v1/send \
|
||||
-H "Authorization: Bearer sk_your_secret_key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"to": "user@example.com", "subject": "Test", "body": "Hello"}'
|
||||
```
|
||||
|
||||
### Node.js example
|
||||
|
||||
```javascript
|
||||
const PLUNK_SECRET_KEY = process.env.PLUNK_SECRET_KEY;
|
||||
|
||||
const response = await fetch('{{API_URL}}/v1/send', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': `Bearer ${PLUNK_SECRET_KEY}`,
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
to: 'user@example.com',
|
||||
subject: 'Test',
|
||||
body: 'Hello'
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
### Python example
|
||||
|
||||
```python
|
||||
import os
|
||||
import requests
|
||||
|
||||
PLUNK_SECRET_KEY = os.environ.get('PLUNK_SECRET_KEY')
|
||||
|
||||
response = requests.post(
|
||||
'{{API_URL}}/v1/send',
|
||||
headers={
|
||||
'Authorization': f'Bearer {PLUNK_SECRET_KEY}',
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
json={
|
||||
'to': 'user@example.com',
|
||||
'subject': 'Test',
|
||||
'body': 'Hello'
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Security best practices
|
||||
|
||||
### Store secret keys securely
|
||||
|
||||
Never commit secret keys to version control. Use environment variables:
|
||||
|
||||
```bash
|
||||
# .env file (add to .gitignore)
|
||||
PLUNK_SECRET_KEY=sk_your_secret_key
|
||||
```
|
||||
|
||||
### Rotate compromised keys
|
||||
|
||||
If a secret key is exposed:
|
||||
|
||||
1. Go to **Settings > API Keys**
|
||||
2. Click **Regenerate Secret Key**
|
||||
3. Update your application with the new key
|
||||
4. The old key stops working immediately
|
||||
|
||||
### Use the right key for the job
|
||||
|
||||
- **Sending emails from your backend?** → Use secret key
|
||||
- **Tracking events from frontend?** → Use public key
|
||||
- **Managing contacts via API?** → Use secret key
|
||||
- **Building a workflow dashboard?** → Use secret key
|
||||
|
||||
When in doubt, if it's not `/v1/track`, you need the secret key.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you're authenticated, you can:
|
||||
|
||||
- [Send your first email](/getting-started/quick-start)
|
||||
- [Explore the API](/api-reference/overview)
|
||||
- [Manage contacts](/guides/contacts)
|
||||
- [Create campaigns](/guides/campaigns)
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Introduction
|
||||
description: Get started with Plunk
|
||||
---
|
||||
|
||||
## What is Plunk?
|
||||
|
||||
Plunk is an open-source email platform built on AWS SES. It provides a complete solution for transactional emails, marketing campaigns, and automated workflows—everything you need to manage email communications at scale.
|
||||
|
||||
## What you can build
|
||||
|
||||
### Send transactional emails
|
||||
Send password resets, order confirmations, and notifications via API with template support and variable substitution.
|
||||
|
||||
```javascript
|
||||
await fetch('{{API_URL}}/v1/send', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': 'Bearer sk_your_secret_key',
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
to: 'user@example.com',
|
||||
subject: 'Welcome {{name}}!',
|
||||
body: '<h1>Hello {{name}}</h1><p>Thanks for signing up.</p>',
|
||||
data: { name: 'John' }
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
### Run marketing campaigns
|
||||
Send newsletters and product updates to segments of your audience. Schedule sends or deliver immediately.
|
||||
|
||||
### Automate email sequences
|
||||
Build drip campaigns, onboarding flows, and behavior-triggered emails with the visual workflow builder.
|
||||
|
||||
## Core concepts
|
||||
|
||||
**Contacts** — People in your audience. Each has an email, subscription status, and custom data fields.
|
||||
|
||||
**Templates** — Reusable email designs. Marketing templates respect subscription status; transactional templates always send.
|
||||
|
||||
**Segments** — Dynamic groups based on contact data. Update automatically as data changes.
|
||||
|
||||
**Campaigns** — One-time email broadcasts to all contacts, a segment, or filtered audience.
|
||||
|
||||
**Workflows** — Automated sequences with delays, conditions, and event triggers.
|
||||
|
||||
**Events** — Track user actions (signups, purchases) to trigger workflows and build segments.
|
||||
|
||||
## Authentication
|
||||
|
||||
Each project has two API keys:
|
||||
|
||||
- **Secret Key (sk_*)** — Server-side only. Required for all endpoints except event tracking.
|
||||
- **Public Key (pk_*)** — Client-side safe. Only works with `/v1/track` for event tracking.
|
||||
|
||||
Never expose secret keys in frontend code.
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Quick Start](/getting-started/quick-start) — Send your first email in 5 minutes
|
||||
- [Authentication](/getting-started/authentication) — Understand API keys
|
||||
- [API Reference](/api-reference/overview) — Explore all endpoints
|
||||
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"title": "Getting Started",
|
||||
"pages": ["introduction", "authentication", "quick-start"]
|
||||
}
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
title: Quick Start
|
||||
description: Send your first email in 5 minutes
|
||||
---
|
||||
|
||||
## Send your first email
|
||||
|
||||
### 1. Get your API key
|
||||
|
||||
1. Sign up at [Plunk dashboard]({{DASHBOARD_URL}})
|
||||
2. Create or select a project
|
||||
3. Go to **Settings > API Keys**
|
||||
4. Copy your **Secret Key** (starts with `sk_`)
|
||||
|
||||
### 2. Send an email
|
||||
|
||||
```bash
|
||||
curl -X POST {{API_URL}}/v1/send \
|
||||
-H "Authorization: Bearer sk_your_secret_key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"to": "recipient@example.com",
|
||||
"subject": "Hello from Plunk",
|
||||
"body": "<h1>It works!</h1><p>Your first email via Plunk.</p>"
|
||||
}'
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"emails": [{
|
||||
"contact": {
|
||||
"id": "contact_abc123",
|
||||
"email": "recipient@example.com"
|
||||
},
|
||||
"email": "email_xyz789"
|
||||
}],
|
||||
"timestamp": "2024-03-15T10:30:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
The email is queued and delivers within seconds.
|
||||
|
||||
## Use variables
|
||||
|
||||
Make emails dynamic with template variables:
|
||||
|
||||
```bash
|
||||
curl -X POST {{API_URL}}/v1/send \
|
||||
-H "Authorization: Bearer sk_your_secret_key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"to": "user@example.com",
|
||||
"subject": "Welcome {{firstName}}!",
|
||||
"body": "<h1>Hello {{firstName}}</h1><p>Welcome to {{companyName}}.</p>",
|
||||
"data": {
|
||||
"firstName": "Sarah",
|
||||
"companyName": "Acme Inc"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Variables use `{{variableName}}` syntax and pull from the `data` object.
|
||||
|
||||
## Send to multiple recipients
|
||||
|
||||
Pass an array to send the same email to multiple people:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"to": ["user1@example.com", "user2@example.com", "user3@example.com"],
|
||||
"subject": "Team update",
|
||||
"body": "<p>Check out our new features!</p>"
|
||||
}
|
||||
```
|
||||
|
||||
Each recipient gets their own email with personalized data if provided.
|
||||
|
||||
## Use saved templates
|
||||
|
||||
Create reusable templates in the dashboard, then reference them by ID:
|
||||
|
||||
```bash
|
||||
curl -X POST {{API_URL}}/v1/send \
|
||||
-H "Authorization: Bearer sk_your_secret_key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"to": "user@example.com",
|
||||
"template": "welcome-email-template-id",
|
||||
"data": {
|
||||
"firstName": "Sarah",
|
||||
"verificationUrl": "https://example.com/verify/abc123"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
The template's subject, body, and sender settings are used automatically. Your `data` fills in the template variables.
|
||||
|
||||
## Track events
|
||||
|
||||
Track user actions to trigger workflows and build segments:
|
||||
|
||||
```bash
|
||||
curl -X POST {{API_URL}}/v1/track \
|
||||
-H "Authorization: Bearer pk_your_public_key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"email": "user@example.com",
|
||||
"event": "signed_up",
|
||||
"data": {
|
||||
"plan": "pro",
|
||||
"source": "landing_page"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
This creates or updates the contact and tracks the event. Use events to trigger automated workflows.
|
||||
|
||||
## What's next
|
||||
|
||||
**Set up workflows** — Build automated email sequences with [workflows](/guides/workflows)
|
||||
|
||||
**Manage contacts** — Import and segment your audience with [contacts](/guides/contacts)
|
||||
|
||||
**Send campaigns** — Broadcast to your entire list with [campaigns](/guides/campaigns)
|
||||
|
||||
**Track engagement** — Monitor opens and clicks with [analytics](/guides/analytics)
|
||||
Reference in New Issue
Block a user