Invoice attached.
", + "attachments": [ + { + "filename": "invoice.pdf", + "content": "JVBERi0xLjQK...", + "contentType": "application/pdf" + } + ] +} +``` + +## Attachment fields + +| Field | Description | +|-------|-------------| +| `filename` | Display name (max 255 chars) | +| `content` | Base64-encoded file content | +| `contentType` | MIME type (e.g., `application/pdf`) | + +## Base64 encoding + +```javascript +import fs from 'fs'; + +const fileBuffer = fs.readFileSync('invoice.pdf'); +const base64Content = fileBuffer.toString('base64'); +``` + diff --git a/apps/wiki/content/docs/concepts/campaigns-vs-workflows.mdx b/apps/wiki/content/docs/concepts/campaigns-vs-workflows.mdx index 39c46c5..8cce205 100644 --- a/apps/wiki/content/docs/concepts/campaigns-vs-workflows.mdx +++ b/apps/wiki/content/docs/concepts/campaigns-vs-workflows.mdx @@ -1,37 +1,26 @@ --- title: Campaigns vs Workflows -description: Choose the right tool for sending emails +description: Choose the right sending method icon: GitCompare --- -## When to use each +## Quick comparison -**Transactional API** (`/v1/send`) — Immediate one-off emails from your code -- Password resets, confirmations, receipts -- Triggered directly by user actions -- Instant delivery - -**Campaigns** — One-time broadcasts to many contacts -- Newsletters, announcements, promotions -- Created in dashboard, send now or schedule -- No code required - -**Workflows** — Automated multi-email sequences -- Onboarding series, abandoned cart, trial reminders -- Triggered by events, segment changes, or schedules -- Delays, conditions, multiple emails +| Need | Use | +|------|-----| +| Password reset now | **API** `/v1/send` | +| Monthly newsletter | **Campaign** | +| Welcome series over 3 days | **Workflow** | +| Order confirmation | **API** `/v1/send` | +| Abandoned cart recovery | **Workflow** | ## Transactional API -Send emails directly from your application code. +Immediate one-off emails from your code. ```javascript -await fetch('{{API_URL}}/v1/send', { +await fetch('/v1/send', { method: 'POST', - headers: { - 'Authorization': `Bearer ${PLUNK_SECRET_KEY}`, - 'Content-Type': 'application/json' - }, body: JSON.stringify({ to: user.email, subject: 'Reset your password', @@ -40,90 +29,19 @@ await fetch('{{API_URL}}/v1/send', { }); ``` -**Use for:** -- Emails that must send immediately -- One-to-one triggered emails -- Context-specific data (reset tokens, order IDs) - ## Campaigns -Create and send broadcasts in the dashboard. +One-time broadcasts to many contacts. Created in dashboard. -1. Create campaign -2. Write email content -3. Select audience (all contacts, segment, or filter) -4. Send now or schedule - -**Use for:** -- One-time sends to many people -- Scheduled announcements -- Manual email sends - -**Can't do:** -- Automation or triggers -- Multi-step sequences -- Delays between emails +- Send now or schedule +- Target all contacts, segments, or filters +- No code required ## Workflows -Build automated sequences with the visual workflow builder. +Automated multi-email sequences. -**Example workflow:** -``` -[Trigger: user_signed_up] - ↓ -[Send Email: Welcome] - ↓ -[Delay: 24 hours] - ↓ -[Send Email: Feature tour] - ↓ -[Delay: 48 hours] - ↓ -[Send Email: Help offer] -``` - -**Use for:** -- Multi-email sequences -- Time-delayed follow-ups -- Event-triggered automation +- Triggered by events or segment changes +- Delays between emails - Conditional logic (if/then) - -**Setup required:** -- Track events from your app via `/v1/track` -- Create workflow in dashboard -- Enable workflow - -## Decision matrix - -| Need | Use | -|------|-----| -| Send password reset now | Transactional API | -| Send monthly newsletter | Campaign | -| Send welcome series over 3 days | Workflow | -| Send order confirmation | Transactional API | -| Send announcement to all users | Campaign | -| Send trial reminder 3 days before expiration | Workflow | -| Send receipt after payment | Transactional API | -| Send seasonal promotion | Campaign | -| Send abandoned cart recovery (1hr + 24hr) | Workflow | - -## Using them together - -Most apps use all three: - -**SaaS example:** -- **Transactional**: Password resets, email verification -- **Campaigns**: Monthly product updates -- **Workflows**: Trial onboarding, churn prevention - -**E-commerce example:** -- **Transactional**: Order confirmations, shipping updates -- **Campaigns**: Weekly deals newsletter -- **Workflows**: Abandoned cart, review requests - -## Next steps - -- [Send a transactional email](/tutorials/first-transactional-email) -- [Create your first workflow](/tutorials/welcome-series-workflow) -- [Build a campaign](/tutorials/newsletter-campaign) +- Re-entry control diff --git a/apps/wiki/content/docs/concepts/contacts-and-data.mdx b/apps/wiki/content/docs/concepts/contacts-and-data.mdx index 26a4160..a002436 100644 --- a/apps/wiki/content/docs/concepts/contacts-and-data.mdx +++ b/apps/wiki/content/docs/concepts/contacts-and-data.mdx @@ -1,18 +1,10 @@ --- -title: Contacts and Data +title: Contacts description: Store and manage your audience icon: Users --- -## What are contacts - -Contacts are people in your email list. Each contact has: - -- **Email** — Unique identifier -- **Subscription status** — Subscribed or unsubscribed -- **Custom data** — Any fields you need - -## Data structure +## Structure ```json { @@ -27,188 +19,42 @@ Contacts are people in your email list. Each contact has: } ``` -The `data` field stores custom information as key-value pairs. +## Adding contacts -## Data types +- **Dashboard:** Contacts → Add Contact +- **CSV import:** Contacts → Import +- **API:** `POST /contacts` +- **Events:** Auto-created when tracking events -**Strings:** -```json -{ "firstName": "Sarah", "company": "Acme Inc" } +## Contact data + +The `data` field stores custom key-value pairs. + +**Best practices:** +- Use consistent naming (camelCase or snake_case) +- Store dates as ISO strings: `"2024-03-15T10:30:00Z"` +- Use numbers for numeric values (enables comparisons) + +## Template variables + +Use `{{fieldName}}` in emails: + +```html +Hello {{firstName}}!
``` -**Numbers:** -```json -{ "mrr": 99, "loginCount": 15 } -``` +**Fallback:** `{{firstName ?? 'there'}}` -Store as numbers for `greaterThan`/`lessThan` comparisons. +**Reserved:** `{{email}}`, `{{id}}` -**Booleans:** -```json -{ "verified": true, "newsletter": false } -``` +## Temporary data -**Dates:** -```json -{ "signupDate": "2024-03-15T10:30:00Z" } -``` +Data that won't save to contact: -Use ISO 8601 format. - -**Arrays:** -```json -{ "tags": ["vip", "enterprise"] } -``` - -**Objects:** -```json -{ - "address": { - "city": "San Francisco", - "country": "US" - } +```javascript +data: { + resetCode: { value: 'ABC123', persistent: false } } ``` -Access nested fields: `address.country` - -## Creating contacts - -### Via API - -```bash -curl -X POST {{API_URL}}/contacts \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "email": "user@example.com", - "subscribed": true, - "data": { - "firstName": "Sarah", - "plan": "pro" - } - }' -``` - -### Automatic upsert - -If email exists, updates instead of creating duplicate. - -```javascript -// First call -POST /contacts { email: "user@example.com", data: { plan: "free" } } - -// Second call - updates same contact -POST /contacts { email: "user@example.com", data: { mrr: 99 } } - -// Result: { plan: "free", mrr: 99 } -``` - -Data merges automatically. - -### Via event tracking - -```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" - } - }' -``` - -Creates contact if doesn't exist, updates if does. - -## Updating contacts - -```bash -curl -X PATCH {{API_URL}}/contacts/contact_id \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "data": { - "plan": "premium", - "mrr": 199 - } - }' -``` - -New fields added, existing fields overwritten, unmentioned fields preserved. - -### Remove fields - -Set to `null`: - -```json -{ "data": { "temporaryToken": null } } -``` - -## Subscription status - -**Subscribed (true):** -- Receives marketing emails -- Receives transactional emails - -**Unsubscribed (false):** -- Does NOT receive marketing emails -- Still receives transactional emails - -Template type controls this behavior. See [Template Types](/concepts/templates-types). - -## Using contact data - -### In templates - -```html -Your {{plan}} plan renews on {{renewalDate}}.
-``` - -### In segments - -Filter by data fields: -- `plan equals "premium"` -- `mrr greaterThan 100` -- `loginCount lessThan 5` - -### In workflows - -``` -[Condition: plan equals "enterprise"] - ├─ True → [Send: Enterprise content] - └─ False → [Send: Standard content] -``` - -## Best practices - -**Consistent naming** — Use camelCase or snake_case, not both. - -**Correct types** — Use `99` not `"99"` for numbers. - -**ISO dates** — `"2024-03-15T10:30:00Z"` for date fields. - -**Sync critical fields only** — Don't mirror entire database. Only fields used in emails, segments, or workflows. - -**Update in real-time** — When user data changes, update contact immediately. - -**Respect unsubscribes** — Never re-subscribe automatically. - -## Deleting contacts - -```bash -curl -X DELETE {{API_URL}}/contacts/contact_id \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Permanent deletion. Consider unsubscribing instead to preserve history. - -## Next steps - -- [Create segments](/concepts/segments-and-filters) -- [Track events](/concepts/events-and-triggers) -- [Use templates](/concepts/templates-types) +Use for: one-time codes, tokens, session data. diff --git a/apps/wiki/content/docs/concepts/custom-domains.mdx b/apps/wiki/content/docs/concepts/custom-domains.mdx new file mode 100644 index 0000000..8c23261 --- /dev/null +++ b/apps/wiki/content/docs/concepts/custom-domains.mdx @@ -0,0 +1,43 @@ +--- +title: Custom Domains +description: Send from your own domain +icon: Globe +--- + +## Why use custom domains + +- Better deliverability +- Brand consistency +- Builds sender reputation + +## Setup + +1. Go to **Settings → Domains** +2. Click **Add Domain** +3. Enter your domain +4. Add the provided DNS records (DKIM, MX, TXT) +5. Wait for verification (usually 10-30 minutes, up to 48 hours) + +## Using your domain + +Specify in the `from` field when sending: + +```json +{ + "to": "customer@example.com", + "from": "orders@yourdomain.com", + "subject": "Order confirmed", + "body": "Your order has been confirmed.
" +} +``` + +## Troubleshooting + +**Domain won't verify:** +- Check DNS records are correct +- Wait for DNS propagation (up to 48 hours) +- Remove conflicting DKIM records from other services + +**Emails going to spam:** +- Warm up new domains with small volumes first +- Monitor bounce and complaint rates diff --git a/apps/wiki/content/docs/concepts/events-and-triggers.mdx b/apps/wiki/content/docs/concepts/events-and-triggers.mdx index 4076b69..3ae1a29 100644 --- a/apps/wiki/content/docs/concepts/events-and-triggers.mdx +++ b/apps/wiki/content/docs/concepts/events-and-triggers.mdx @@ -1,180 +1,53 @@ --- -title: Events and Triggers -description: Track behavior and trigger workflows +title: Events +description: Track actions and trigger workflows icon: Activity --- -## What are events +## Overview -Events track user actions from your application. Use them to update contact data, trigger workflows, and build segments. +Events track user actions. Use them to trigger workflows and update contact data. -## Tracking events - -### Basic event +## Tracking ```javascript -await fetch('{{API_URL}}/v1/track', { +await fetch('/v1/track', { method: 'POST', headers: { - 'Authorization': `Bearer ${PLUNK_PUBLIC_KEY}`, - 'Content-Type': 'application/json' + 'Authorization': 'Bearer pk_your_public_key' }, body: JSON.stringify({ event: 'signed_up', - email: user.email - }) -}); -``` - -Creates or updates contact. Event is recorded. - -### Event with data - -```javascript -await fetch('{{API_URL}}/v1/track', { - method: 'POST', - headers: { - 'Authorization': `Bearer ${PLUNK_PUBLIC_KEY}`, - 'Content-Type': 'application/json' - }, - body: JSON.stringify({ - event: 'purchase_completed', email: user.email, - data: { - plan: 'premium', - mrr: 99 - } + data: { plan: 'pro' } }) }); ``` -Updates contact data fields. Data persists on contact record. +Creates/updates contact and records the event. -## Public vs Secret keys +## Keys -### Public Key (pk_*) +- **Public key (pk_*):** Safe for client-side, only works with `/v1/track` +- **Secret key (sk_*):** Server-side only, full API access -- Safe for client-side code -- Only works with `/v1/track` -- Use in browser/mobile apps +## Event data -### Secret Key (sk_*) - -- Server-side only -- Works with all endpoints -- Full API access - -## Event naming - -Use clear, past-tense verbs with underscores: - -✅ `signed_up`, `purchase_completed`, `feature_activated` -❌ `signup`, `buy`, `feature` - -## Workflow triggers - -### Event trigger - -Workflow starts when event is tracked. - -``` -Trigger: event = "signed_up" -``` - -Track event: +**Persistent (default):** Saved to contact ```javascript -track('signed_up', 'user@example.com'); +data: { plan: 'premium' } ``` -Workflow starts for that contact. - -### Wait for event - -Workflow pauses until event occurs. - -``` -[Wait for Event: purchase_completed, timeout: 7 days] - ├─ Event occurred → [Send: Thank you] - └─ Timeout → [Send: Discount offer] -``` - -## Common patterns - -### User lifecycle - +**Non-persistent:** Available only to workflow ```javascript -// Signup -track('signed_up', email, { source: 'landing' }); - -// First login -track('first_login', email, { lastLoginAt: new Date().toISOString() }); - -// Subscription -track('subscription_created', email, { plan: 'premium', mrr: 99 }); +data: { + orderId: { value: 'order-123', persistent: false } +} ``` -### E-commerce +## Automatic events -```javascript -// Cart abandonment -track('cart_abandoned', email, { - cartTotal: 149.99, - cartUrl: `https://store.com/cart/${cartId}` -}); - -// Purchase -track('purchase_completed', email, { - orderId: order.id, - orderTotal: order.total -}); -``` - -## Event-based segments - -Track events to update contact data, then segment on that data. - -1. Track login: -```javascript -track('login', email, { - lastLoginAt: new Date().toISOString() -}); -``` - -2. Create segment: -``` -Field: lastLoginAt -Operator: greaterThan -Value: {{7_days_ago}} -``` - -Contacts auto-join segment when they log in. - -## Testing events - -**Dashboard:** Contacts → Search email → Events tab - -Shows all events for that contact. - -**Workflows:** Check executions after tracking event to verify workflow triggered. - -## Rate limits - -- Public key: 100 requests/minute -- Secret key: 1000 requests/minute - -## Common issues - -**Workflow not triggering:** -- Workflow is enabled -- Event name matches exactly (case-sensitive) -- Contact email is correct - -**Contact data not updating:** -- Field names are case-sensitive -- Values are correct type (number vs string) - -## Next steps - -- [Build event-triggered workflows](/tutorials/welcome-series-workflow) -- [Create event-based segments](/concepts/segments-and-filters) -- [Track events from your app](/tutorials/event-tracking-integration) +Plunk tracks these automatically: +- `email.sent`, `email.opened`, `email.clicked` +- `email.bounced`, `email.complained` +- `segment.entered`, `segment.exited` diff --git a/apps/wiki/content/docs/concepts/index.mdx b/apps/wiki/content/docs/concepts/index.mdx deleted file mode 100644 index 068c32d..0000000 --- a/apps/wiki/content/docs/concepts/index.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Core Concepts -description: Understand how Plunk works -icon: Lightbulb ---- - -## Email methods - -Click: {{resetLink}}
" - }' -``` - -Type: `MARKETING` or `TRANSACTIONAL` - -## Changing type - -Update anytime: - -```bash -curl -X PATCH {{API_URL}}/templates/template_id \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{"type": "MARKETING"}' -``` - -**Warning:** Changing transactional → marketing stops sending to unsubscribed contacts. - -## Unsubscribe links - -Marketing templates auto-include unsubscribe link in footer. - -Custom placement: -```html -Unsubscribe -``` - -Transactional templates don't need unsubscribe links. - -## Choosing the right type +## Choosing Ask: "Would user be frustrated if they didn't receive this after unsubscribing?" -**If yes → Transactional** -- Password resets -- Order confirmations -- Account alerts +- **Yes → Transactional** (password resets, order confirmations) +- **No → Marketing** (newsletters, promotions) -**If no → Marketing** -- Newsletters -- Product announcements -- Promotions +## Variables -## Best practices +```html +Your {{plan}} plan renews on {{renewalDate}}.
+``` -**Default to marketing** — Only use transactional for truly necessary emails. - -**Don't abuse transactional** — Sending marketing content via transactional templates violates regulations and damages reputation. - -**Test both states** — Verify behavior with subscribed and unsubscribed contacts. - -## Next steps - -- [Create templates](/guides/templates) -- [Manage subscriptions](/concepts/contacts-and-data) -- [Send emails](/tutorials/first-transactional-email) +**Fallback:** `{{firstName ?? 'there'}}` diff --git a/apps/wiki/content/docs/concepts/troubleshooting.mdx b/apps/wiki/content/docs/concepts/troubleshooting.mdx new file mode 100644 index 0000000..fca3be9 --- /dev/null +++ b/apps/wiki/content/docs/concepts/troubleshooting.mdx @@ -0,0 +1,44 @@ +--- +title: Troubleshooting +description: Common issues and solutions +icon: Bug +--- + +## Authentication + +**Invalid API key:** +- Secret keys start with `sk_`, public keys with `pk_` +- Use `Authorization: Bearer sk_your_secret_key` + +**Wrong key type:** +- Public keys (`pk_`) only work with `/v1/track` +- All other endpoints require secret keys (`sk_`) + +## Emails not sending + +1. **Billing limit reached** — Check Settings → Billing +2. **Template not found** — Verify template ID exists +3. **Contact unsubscribed** — Marketing templates skip unsubscribed contacts + +## Emails going to spam + +1. Set up a custom domain +2. Clean your list (remove bounces) +3. Warm up new domains gradually + +## Workflows not triggering + +1. **Workflow not enabled** — Check toggle is ON +2. **Wrong event name** — Names are case-sensitive +3. **Already entered** — If re-entry disabled, contact can only enter once + +## Rate limiting (429) + +- Wait and retry +- Batch multiple recipients in one request +- Spread requests over time + +## Request IDs + +Every API response includes `X-Request-ID` header. Include this when contacting support. + diff --git a/apps/wiki/content/docs/concepts/webhooks.mdx b/apps/wiki/content/docs/concepts/webhooks.mdx new file mode 100644 index 0000000..f0b38fa --- /dev/null +++ b/apps/wiki/content/docs/concepts/webhooks.mdx @@ -0,0 +1,47 @@ +--- +title: Webhooks +description: Send HTTP requests from workflows +icon: Webhook +--- + +## Overview + +Webhooks send HTTP requests to external services from within workflows. + +## Adding a webhook step + +1. Edit a workflow +2. Add a **Webhook** step +3. Configure URL, method, headers, and body + +## Configuration + +```json +{ + "url": "https://your-api.com/webhook", + "method": "POST", + "headers": { + "Authorization": "Bearer your_api_token" + }, + "body": { + "email": "{{email}}", + "firstName": "{{data.firstName}}" + } +} +``` + +**Methods:** POST, PUT, PATCH, GET, DELETE + +## Variables + +- `{{email}}`, `{{id}}` — Contact fields +- `{{data.fieldName}}` — Custom data +- `{{workflowName}}`, `{{now}}` — Workflow context + +## Error handling + +- Failed webhooks don't block the workflow +- Errors logged in execution details +- 30 second timeout +- No automatic retries + diff --git a/apps/wiki/content/docs/guides/analytics.mdx b/apps/wiki/content/docs/guides/analytics.mdx deleted file mode 100644 index 4ea20a3..0000000 --- a/apps/wiki/content/docs/guides/analytics.mdx +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: Analytics -description: Track and analyze email performance ---- - -## What you can track - -Plunk tracks comprehensive email metrics across all campaigns, workflows, and transactional emails: - -**Delivery metrics:** -- Sent, delivered, bounced - -**Engagement metrics:** -- Opens, clicks, unsubscribes - -**Quality metrics:** -- Open rate, click rate, bounce rate - -## Campaign analytics - -View detailed performance for specific campaigns: - -```bash -curl -X GET {{API_URL}}/campaigns/campaign_id/stats \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Response: - -```json -{ - "totalRecipients": 5000, - "sentCount": 5000, - "deliveredCount": 4980, - "openedCount": 2100, - "clickedCount": 450, - "bouncedCount": 20, - "unsubscribedCount": 8, - "openRate": 0.422, - "clickRate": 0.090, - "bounceRate": 0.004 -} -``` - -**Metrics update in real-time** as recipients engage. - -View detailed analytics in your dashboard to: -- Monitor daily performance trends -- Identify engagement patterns -- Spot deliverability issues -- Compare time periods - -## Understanding metrics - -### Open rate - -**Formula:** (Unique opens / Delivered) × 100 - -**Industry benchmarks:** -- B2B: 15-25% -- B2C: 20-30% -- E-commerce: 15-20% - -**What affects it:** -- Subject line quality -- Sender reputation -- Send timing -- Audience engagement - -### Click rate - -**Formula:** (Unique clicks / Delivered) × 100 - -**Industry benchmarks:** -- B2B: 2-5% -- B2C: 3-7% -- E-commerce: 2-4% - -**What affects it:** -- Content relevance -- Call-to-action clarity -- Email design -- Link placement - -### Bounce rate - -**Formula:** (Bounces / Sent) × 100 - -**Target:** < 2% - -**Types:** -- **Hard bounce** — Invalid email, never retry -- **Soft bounce** — Temporary issue, retry later - -**High bounce rate causes:** -- Outdated email list -- Invalid addresses -- Domain issues - -### Unsubscribe rate - -**Formula:** (Unsubscribes / Delivered) × 100 - -**Target:** < 0.5% - -**High unsubscribe causes:** -- Too frequent emails -- Irrelevant content -- Misleading subject lines -- No segmentation - -## Improving performance - -### Boost open rates - -**Write compelling subject lines:** -- Keep under 50 characters -- Create urgency or curiosity -- Personalize with `{{firstName}}` -- Test different approaches - -**Optimize send timing:** -- Test different days/times -- Segment by timezone -- Avoid weekends (for B2B) -- Consider user behavior - -**Build sender reputation:** -- Use custom domain -- Maintain consistent volume -- Keep bounce rate low -- Avoid spam triggers - -### Increase click rates - -**Clear call-to-action:** -- One primary CTA -- Use buttons, not just links -- Action-oriented text ("Get Started" not "Click Here") -- Make it prominent - -**Relevant content:** -- Segment audience -- Personalize messaging -- Match subject line promise -- Keep it focused - -**Mobile-responsive:** -- Test on mobile devices -- Use large tap targets -- Single column layout -- Readable font sizes - -### Reduce bounce rate - -**Clean your list:** -```javascript -// Remove hard bounces immediately -const bounced = await fetch('{{API_URL}}/events?name=email.bounced&limit=1000'); - -for (const event of bounced.data.events) { - if (event.data.bounceType === 'hard') { - await fetch(`{{API_URL}}/contacts/${event.contactId}`, { - method: 'DELETE', - headers: { 'Authorization': `Bearer ${apiKey}` } - }); - } -} -``` - -**Verify emails:** -- Use email verification service -- Double opt-in for signups -- Remove invalid formats -- Re-engage inactive users before removing - -## Next Steps - -- [Set up custom domains](/guides/custom-domains) for better deliverability -- [Build segments](/guides/segments) for targeted campaigns -- [Scale your email](/guides/scaling-email) with best practices diff --git a/apps/wiki/content/docs/guides/billing-limits.mdx b/apps/wiki/content/docs/guides/billing-limits.mdx deleted file mode 100644 index 3b120fc..0000000 --- a/apps/wiki/content/docs/guides/billing-limits.mdx +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Billing & Usage Limits -description: Control monthly email usage and costs ---- - -## What are billing limits - -Billing limits let you cap monthly email sends by category to control costs. Set maximum emails per month for transactional, campaigns, and workflows separately. - -## Email categories - -Plunk tracks usage across three categories: - -**Transactional** — Emails sent via `/v1/send` API -- Order confirmations, password resets -- Account notifications -- Any direct API sends - -**Campaigns** — One-time broadcast emails -- Newsletters, announcements -- Promotional campaigns -- Marketing blasts - -**Workflows** — Automated sequence emails -- Onboarding flows -- Drip campaigns -- Behavior-triggered emails - -**Note:** The category is determined by how you send (API, campaign, or workflow), not the template type. - -## How limits work - -### Monthly reset - -Usage resets on the 1st of each month (UTC). Starts fresh at 0. - -### Enforcement - -When sending emails: - -- **Under 80%** — Sends normally -- **80-99%** — Sends with warning flag -- **100%+** — Blocked with 429 error - -### Unlimited - -Set limit to unlimited for any category (default for all categories). - -## Manage limits - -You can view and update your billing limits in the dashboard: - -1. Go to **Settings** → **Billing** -2. View current usage for each category -3. Update limits as needed (requires Admin or Owner role) - -## When limit is reached - -### API error - -```json -{ - "code": 429, - "error": "Too Many Requests", - "message": "Monthly limit exceeded for campaigns (50000/50000). Resets on 2025-12-01." -} -``` - -### Handle in code - -```javascript -try { - const response = await fetch('{{API_URL}}/v1/send', { - method: 'POST', - headers: { - 'Authorization': `Bearer ${apiKey}`, - 'Content-Type': 'application/json' - }, - body: JSON.stringify(emailData) - }); - - if (response.status === 429) { - const error = await response.json(); - - // Option 1: Notify admin - await notifyAdmin(`Limit reached: ${error.message}`); - - // Option 2: Increase limit - await increaseBillingLimit('transactional', 200000); - - // Option 3: Queue for next month - await queueForNextMonth(emailData); - } -} catch (error) { - console.error('Send failed:', error); -} -``` - -## Best practices - -**Monitor usage regularly** — Check dashboard weekly to avoid surprises. - -**Set alerts** — Configure notifications at 80% usage. - -**Plan for growth** — Increase limits before campaigns, not during. - -**Use categories wisely** — Critical transactional emails might need higher limits. - -**Review monthly** — Adjust limits based on actual usage patterns. - -## Next Steps - -- [Track usage analytics](/guides/analytics) -- [Scale email delivery](/guides/scaling-email) -- [Troubleshooting limits](/guides/troubleshooting) diff --git a/apps/wiki/content/docs/guides/campaigns.mdx b/apps/wiki/content/docs/guides/campaigns.mdx deleted file mode 100644 index 4eaf316..0000000 --- a/apps/wiki/content/docs/guides/campaigns.mdx +++ /dev/null @@ -1,247 +0,0 @@ ---- -title: Campaigns -description: Send one-time email broadcasts ---- - -## What are campaigns - -Campaigns are one-time email broadcasts sent to your audience. Use them for: -- Product announcements -- Newsletter distributions -- Seasonal promotions -- Feature launches - -Unlike workflows (automated sequences), campaigns send once to a snapshot of your audience. - -## Creating campaigns - -### In the dashboard - -1. Go to **Campaigns** -2. Click **Create Campaign** -3. Name your campaign -4. Choose your audience -5. Select a template or compose inline -6. Preview and test -7. Send or schedule - -### Via API - -```bash -curl -X POST {{API_URL}}/campaigns \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "March Newsletter", - "subject": "New features this month", - "body": "Check out our latest updates...
", - "from": "newsletter@example.com", - "fromName": "Acme Inc", - "audienceType": "ALL", - "status": "DRAFT" - }' -``` - -## Choosing your audience - -### All contacts - -Sends to everyone in your project: - -```json -{ - "audienceType": "ALL" -} -``` - -### Specific segment - -Sends to contacts in a saved segment: - -```json -{ - "audienceType": "SEGMENT", - "segmentId": "premium-users" -} -``` - -### Custom filters - -Sends to contacts matching conditions: - -```json -{ - "audienceType": "FILTERED", - "audienceFilter": { - "operator": "AND", - "conditions": [ - { "field": "data.plan", "operator": "equals", "value": "pro" }, - { "field": "data.lastLoginAt", "operator": "greaterThan", "value": "2024-01-01" } - ] - } -} -``` - -## Subscription handling - -Campaign delivery respects your **template type**: - -**Marketing templates** (default) -- Only sends to subscribed contacts -- Unsubscribed contacts are skipped automatically -- Includes unsubscribe link - -**Transactional templates** -- Sends to all contacts, even if unsubscribed -- Use only for critical business emails -- No unsubscribe link - -Choose template type based on content, not audience size. - -## Campaign states - -**DRAFT** — Being created, can edit freely - -**SCHEDULED** — Queued for future send, can cancel - -**SENDING** — Currently delivering, cannot stop - -**SENT** — Completed successfully - -**CANCELLED** — Scheduled campaign was cancelled - -## Sending campaigns - -### Send immediately - -```bash -curl -X POST {{API_URL}}/campaigns/campaign_id/send \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Status changes to SENDING, emails deliver within minutes. - -### Schedule for later - -```bash -curl -X POST {{API_URL}}/campaigns/campaign_id/send \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "scheduledAt": "2024-03-20T10:00:00Z" - }' -``` - -Status changes to SCHEDULED. Campaign sends at the specified time. - -### Cancel scheduled campaign - -```bash -curl -X POST {{API_URL}}/campaigns/campaign_id/cancel \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Only works if status is SCHEDULED. - -## Testing campaigns - -Send a test email before broadcasting: - -```bash -curl -X POST {{API_URL}}/campaigns/campaign_id/test \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "email": "test@example.com" - }' -``` - -This sends to the test email without affecting campaign status. - -## Campaign analytics - -View campaign performance: - -```bash -curl -X GET {{API_URL}}/campaigns/campaign_id/stats \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Returns: - -```json -{ - "totalRecipients": 5000, - "sentCount": 5000, - "deliveredCount": 4980, - "openedCount": 2100, - "clickedCount": 450, - "bouncedCount": 20, - "openRate": 0.42, - "clickRate": 0.09 -} -``` - -Metrics update in real-time as recipients engage. - -## Managing campaigns - -### List campaigns - -```bash -curl -X GET {{API_URL}}/campaigns \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Filter by status: - -```bash -curl -X GET "{{API_URL}}/campaigns?status=SENT" \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -### Get campaign details - -```bash -curl -X GET {{API_URL}}/campaigns/campaign_id \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -### Update draft campaign - -```bash -curl -X PATCH {{API_URL}}/campaigns/campaign_id \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Updated name", - "subject": "New subject line" - }' -``` - -Only works for DRAFT campaigns. - -### Duplicate campaign - -```bash -curl -X POST {{API_URL}}/campaigns/campaign_id/duplicate \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Creates a new draft campaign with the same content. - -### Delete campaign - -```bash -curl -X DELETE {{API_URL}}/campaigns/campaign_id \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Can only delete DRAFT or CANCELLED campaigns. - -## Next Steps - -- [Build automated workflows](/guides/workflows) -- [Create dynamic segments](/guides/segments) -- [Track campaign analytics](/guides/analytics) -- [Set up custom domains](/guides/custom-domains) diff --git a/apps/wiki/content/docs/guides/contact-data.mdx b/apps/wiki/content/docs/guides/contact-data.mdx deleted file mode 100644 index 3ed4615..0000000 --- a/apps/wiki/content/docs/guides/contact-data.mdx +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: Working with Contact Data -description: Use persistent and temporary contact data for personalized emails ---- - -## Contact Data Basics - -Every contact has: -- **email**: Required, unique identifier -- **subscribed**: Boolean for subscription status -- **data**: JSON object for custom fields - -```javascript -{ - "email": "user@example.com", - "subscribed": true, - "data": { - "firstName": "Jane", - "plan": "professional", - "signupDate": "2024-03-15" - } -} -``` - -## Persistent vs. Temporary Data - -When sending emails, you can pass data that either saves to the contact or is used only for that email. - -### Persistent Data (Default) - -```javascript -fetch('/v1/send', { - method: 'POST', - body: JSON.stringify({ - to: 'user@example.com', - subject: 'Welcome', - body: 'Hi {'{{firstName}}'}!
', - data: { - firstName: 'John' // Saved to contact.data.firstName - } - }) -}); -``` - -### Temporary Data (Non-Persistent) - -```javascript -fetch('/v1/send', { - method: 'POST', - body: JSON.stringify({ - to: 'user@example.com', - subject: 'Password Reset', - body: 'Your code: {'{{resetCode}}'}
', - data: { - resetCode: { - value: 'ABC123', - persistent: false // NOT saved to contact - } - } - }) -}); -``` - -**Use temporary data for**: -- Password reset codes -- One-time verification tokens -- Session-specific information -- Temporary discount codes - -## Template Variables - -Use `{'{{fieldName}}'}` to insert contact data into emails. - -### Basic Variables - -```html -Hello {'{{firstName}}'}!
-Your plan: {'{{plan}}'}
-``` - -### Fallback Values - -Provide defaults when data might be missing: - -```html -Hello {'{{firstName ?? \'there\'}}'}!
-Plan: {'{{plan ?? \'Free\'}}'}
-``` - -### Reserved Fields - -Two fields are always available: - -```html -Contact ID: {'{{plunk_id}}'}
-Email: {'{{plunk_email}}'}
-``` - -## Data Merging - -Updates merge with existing data: - -```javascript -// Contact has: { firstName: 'John', plan: 'free' } - -// Update with: -{ data: { lastName: 'Doe', plan: 'pro' } } - -// Result: { firstName: 'John', lastName: 'Doe', plan: 'pro' } -``` - -## Best Practices - -### Keep Data Flat - -```javascript -// Good -{ - "firstName": "Jane", - "plan": "pro", - "mrr": 99 -} - -// Avoid nesting (harder to use in templates) -{ - "user": { - "profile": { - "name": "Jane" - } - } -} -``` - -### Use Consistent Naming - -Pick a style and stick to it: - -```javascript -// camelCase (recommended) -{ "firstName": "Jane", "lastLogin": "2024-03-15" } - -// or snake_case -{ "first_name": "Jane", "last_login": "2024-03-15" } -``` - -### Store Dates as ISO Strings - -```javascript -// Good (filterable, sortable) -{ "signupDate": "2024-03-15T10:30:00Z" } - -// Avoid -{ "signupDate": "March 15, 2024" } -``` - -## Discovering Available Fields - -Get all fields across your contacts: - -```bash -curl -X GET "{{API_URL}}/contacts/fields" \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Response: -```json -{ - "success": true, - "data": { - "fields": [ - "email", - "subscribed", - "firstName", - "plan", - "signupDate" - ], - "count": 5 - } -} -``` - -Get unique values for a field: - -```bash -curl -X GET "{{API_URL}}/contacts/fields/data.plan/values" \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Response: -```json -{ - "success": true, - "data": { - "field": "data.plan", - "values": ["free", "professional", "enterprise"], - "count": 3 - } -} -``` - -## Next Steps - -- [Send personalized emails](/guides/templates) -- [Create segments](/guides/segments) based on contact data -- [Track events](/guides/events) to enrich contact profiles diff --git a/apps/wiki/content/docs/guides/contacts.mdx b/apps/wiki/content/docs/guides/contacts.mdx deleted file mode 100644 index 13dee79..0000000 --- a/apps/wiki/content/docs/guides/contacts.mdx +++ /dev/null @@ -1,436 +0,0 @@ ---- -title: Contacts -description: Manage your audience at scale ---- - -## What are contacts - -Contacts are people in your audience. Each contact has an email address, subscription status, and custom data fields you define. Use contacts to personalize emails, build segments, and track engagement. - -## Creating contacts - -### Add a single contact - -```bash -curl -X POST {{API_URL}}/contacts \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "email": "user@example.com", - "subscribed": true, - "data": { - "firstName": "Sarah", - "plan": "pro", - "signupDate": "2024-03-15" - } - }' -``` - -### Automatic upsert - -If the email already exists, the contact is updated instead of creating a duplicate: - -```javascript -// First call - creates contact -POST /contacts { email: 'user@example.com', data: { plan: 'free' } } - -// Second call - updates same contact -POST /contacts { email: 'user@example.com', data: { plan: 'pro' } } - -// Result: One contact with plan: 'pro' -``` - -This is useful when syncing user data from your application. - -## Contact data fields - -Store custom data in the `data` field. Use it for: - -- User profile (name, company, role) -- Subscription info (plan, MRR, renewal date) -- Behavior tracking (last login, feature usage) -- Preferences (newsletter, notifications) - -**Example:** - -```json -{ - "email": "user@example.com", - "subscribed": true, - "data": { - "firstName": "Sarah", - "lastName": "Chen", - "company": "Acme Inc", - "plan": "premium", - "mrr": 99, - "lastLoginAt": "2024-03-15T10:30:00Z", - "preferences": { - "newsletter": true, - "productUpdates": false - } - } -} -``` - -### Best practices - -**Use consistent naming** — Pick camelCase or snake_case and stick with it. - -**Store dates as ISO strings** — `"2024-03-15T10:30:00Z"` enables date range filtering in segments. - -**Keep it relatively flat** — Nested objects work, but flat structures are easier to query in segments. - -**Use numbers for numeric data** — Store `99` not `"99"` to enable greater than/less than comparisons. - -## Using contact data in emails - -### Template variables - -Access contact data in email templates using `{{variableName}}` syntax: - -```html -Your {{plan}} plan renews on {{renewalDate}}.
-Total: ${{mrr}}
-``` - -When sending, contact data automatically populates 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": "Renewal reminder", - "body": "Hi {{firstName}}, your {{plan}} plan renews soon.
" - }' -``` - -The `firstName` and `plan` values come from the contact's `data` field. - -### Fallback values - -Provide defaults when data might be missing: - -```html -Hello {{firstName ?? 'there'}}!
-Plan: {{plan ?? 'Free'}}
-``` - -If `firstName` is not set, displays "Hello there!" instead of blank. - -### Passing additional data - -Send extra data for a specific email without saving it to the contact: - -```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": "Your verification code", - "body": "Your code: {{verificationCode}}
", - "data": { - "verificationCode": "ABC123" - } - }' -``` - -The `verificationCode` is used in the email but not saved to the contact. This is useful for: -- One-time codes (password reset, verification) -- Session-specific data -- Temporary discount codes -- Order-specific details - -### Reserved variables - -These are always available in templates: - -- `{{email}}` — Contact email address -- `{{id}}` — Contact ID - -Example: -```html -Your account: {{email}}
- -``` - -## Listing contacts - -### Get all contacts - -```bash -curl -X GET "{{API_URL}}/contacts?limit=50" \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Returns: - -```json -{ - "success": true, - "data": { - "items": [...], - "nextCursor": "abc123", - "hasMore": true, - "total": 10000 - } -} -``` - -### Pagination - -For large lists, use cursor-based pagination: - -```javascript -let allContacts = []; -let cursor = null; - -do { - const params = new URLSearchParams({ limit: 100 }); - if (cursor) params.append('cursor', cursor); - - const response = await fetch(`{{API_URL}}/contacts?${params}`, { - headers: { 'Authorization': `Bearer ${PLUNK_SECRET_KEY}` } - }); - - const { data } = await response.json(); - allContacts.push(...data.items); - cursor = data.nextCursor; -} while (cursor); -``` - -### Filter by subscription - -```bash -# Only subscribed -curl -X GET "{{API_URL}}/contacts?subscribed=true" \ - -H "Authorization: Bearer sk_your_secret_key" - -# Only unsubscribed -curl -X GET "{{API_URL}}/contacts?subscribed=false" \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -### Search by email - -```bash -curl -X GET "{{API_URL}}/contacts?search=sarah" \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Searches for emails containing "sarah". - -## Getting a contact - -### By ID - -```bash -curl -X GET {{API_URL}}/contacts/contact_id \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -## Updating contacts - -### Update contact data - -```bash -curl -X PATCH {{API_URL}}/contacts/contact_id \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "subscribed": true, - "data": { - "plan": "premium", - "mrr": 99 - } - }' -``` - -### Data merging - -Updates merge with existing data: - -```javascript -// Current contact data -{ "firstName": "Sarah", "company": "Acme" } - -// Update with -{ "lastName": "Chen", "plan": "pro" } - -// Result -{ "firstName": "Sarah", "company": "Acme", "lastName": "Chen", "plan": "pro" } -``` - -To remove a field, set it to `null`. - -### Change subscription status - -```bash -curl -X PATCH {{API_URL}}/contacts/contact_id \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{"subscribed": false}' -``` - -**Marketing templates** only send to subscribed contacts. **Transactional templates** send to everyone, regardless of subscription status. - -## Deleting contacts - -```bash -curl -X DELETE {{API_URL}}/contacts/contact_id \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -**Warning:** Deletion is permanent. Consider unsubscribing instead of deleting. - -## Bulk operations - -### Import from CSV - -Prepare a CSV file: - -```csv -email,firstName,lastName,plan -sarah@example.com,Sarah,Chen,pro -john@example.com,John,Doe,free -``` - -Upload via dashboard: -1. Go to **Contacts** -2. Click **Import CSV** -3. Upload file -4. Map columns -5. Set default subscription status -6. Import - -The import runs in the background. You'll receive a summary when complete. - -## Available fields - -### Get all custom fields - -See what data fields your contacts have: - -```bash -curl -X GET {{API_URL}}/contacts/fields \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Returns unique field names across all contacts: - -```json -{ - "fields": [ - "firstName", - "lastName", - "company", - "plan", - "mrr", - "signupDate" - ] -} -``` - -### Get field values - -See all unique values for a specific field: - -```bash -curl -X GET {{API_URL}}/contacts/fields/plan/values \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Returns: - -```json -{ - "values": ["free", "pro", "premium", "enterprise"] -} -``` - -Useful for building segment filters and understanding your data. - -## Syncing with your app - -Keep contacts in sync with your user database: - -```javascript -// When user signs up -async function onUserSignup(user) { - await fetch('{{API_URL}}/contacts', { - method: 'POST', - headers: { - 'Authorization': `Bearer ${PLUNK_SECRET_KEY}`, - 'Content-Type': 'application/json' - }, - body: JSON.stringify({ - email: user.email, - subscribed: true, - data: { - firstName: user.firstName, - lastName: user.lastName, - signupDate: new Date().toISOString() - } - }) - }); -} - -// When user updates profile -async function onUserUpdate(user) { - await fetch(`{{API_URL}}/contacts/${user.contactId}`, { - method: 'PATCH', - headers: { - 'Authorization': `Bearer ${PLUNK_SECRET_KEY}`, - 'Content-Type': 'application/json' - }, - body: JSON.stringify({ - data: { - firstName: user.firstName, - lastName: user.lastName, - company: user.company - } - }) - }); -} - -// When user subscribes to plan -async function onSubscriptionChange(user, plan, mrr) { - await fetch(`{{API_URL}}/contacts/${user.contactId}`, { - method: 'PATCH', - headers: { - 'Authorization': `Bearer ${PLUNK_SECRET_KEY}`, - 'Content-Type': 'application/json' - }, - body: JSON.stringify({ - data: { - plan, - mrr, - subscriptionDate: new Date().toISOString() - } - }) - }); -} -``` - -## Best practices - -**Sync critical data only** — Don't sync every field. Focus on data used in segments, workflows, and personalization. - -**Use webhooks for real-time sync** — Update contacts immediately when user data changes. - -**Track subscription separately** — Use the `subscribed` field for email preferences, not app subscription status. - -**Clean your list regularly** — Remove or unsubscribe bounced and inactive contacts. - -**Respect opt-outs** — When users unsubscribe, update immediately. Don't re-subscribe them automatically. - -**Test with real emails** — Use your own email addresses to test the contact experience. - -## Next Steps - -- [Build segments](/guides/segments) to group contacts -- [Send campaigns](/guides/campaigns) to your contacts -- [Track events](/guides/events) to update contact data automatically diff --git a/apps/wiki/content/docs/guides/custom-domains.mdx b/apps/wiki/content/docs/guides/custom-domains.mdx deleted file mode 100644 index 06d5692..0000000 --- a/apps/wiki/content/docs/guides/custom-domains.mdx +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: Custom Domains -description: Send emails from your own domain ---- - -## Why use custom domains - -Sending from your own domain (e.g., `hello@yourdomain.com`) instead of a shared domain: - -- **Better deliverability** — Email providers trust emails from verified domains -- **Brand consistency** — Recipients see your brand, not Plunk -- **Higher trust** — Your domain builds its own sender reputation -- **Professional appearance** — Custom addresses look more legitimate - -## Requirements - -- **Domain ownership** — You own or control the domain -- **DNS access** — Ability to add DNS records -- **Verification** — Add DKIM records to prove ownership - -## Adding a domain - -1. Go to **Settings > Domains** -2. Click **Add Domain** -3. Enter your domain (e.g., `yourdomain.com`) -4. Copy the provided DNS records - -## DNS configuration - -After adding your domain, you'll receive 3 DKIM tokens. Add them as CNAME records to your DNS. - -### Common DNS providers - -#### Cloudflare - -1. Log into Cloudflare -2. Select your domain -3. Go to **DNS > Records** -4. Click **Add record** -5. Select **CNAME** type -6. Paste name and value from Plunk -7. Click **Save** -8. Repeat for all 3 records - -#### Namecheap - -1. Log into Namecheap -2. Go to **Domain List** -3. Click **Manage** next to your domain -4. Select **Advanced DNS** -5. Click **Add New Record** -6. Choose **CNAME Record** -7. Enter host and value -8. Repeat for all 3 records - -#### GoDaddy - -1. Log into GoDaddy -2. Go to **My Products** -3. Click **DNS** next to your domain -4. Click **Add** under Records -5. Select **CNAME** type -6. Enter name and value -7. Repeat for all 3 records - -#### Route 53 (AWS) - -1. Open Route 53 console -2. Select your hosted zone -3. Click **Create record** -4. Enter record name -5. Select **CNAME** type -6. Paste value -7. Create record -8. Repeat for all 3 records - -## Verification - -### Automatic verification - -Plunk checks DNS records every 5 minutes automatically. Verification typically completes within 10-30 minutes after adding DNS records. - -**Note:** DNS propagation can take up to 48 hours, though it's usually much faster. - -Check verification status in your dashboard at **Settings > Domains**. - -## Using your domain - -Once verified, specify your domain in the `from` field: - -### In transactional emails - -```bash -curl -X POST {{API_URL}}/v1/send \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "to": "customer@example.com", - "from": "orders@yourdomain.com", - "fromName": "Your Company", - "subject": "Order confirmed", - "body": "Your order has been confirmed.
" - }' -``` - -### In templates - -Set default from address in template: - -```bash -curl -X POST {{API_URL}}/templates \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Order Confirmation", - "subject": "Order #{{orderNumber}} confirmed", - "body": "...", - "from": "orders@yourdomain.com", - "fromName": "Your Company", - "type": "TRANSACTIONAL" - }' -``` - -### In campaigns - -Campaigns use the template's from address, or you can override: - -```bash -curl -X POST {{API_URL}}/campaigns \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Newsletter", - "templateId": "template_id", - "from": "newsletter@yourdomain.com", - "audienceType": "ALL" - }' -``` - -## Managing domains - -### Remove domain - -Go to **Settings > Domains**, select the domain, and click **Remove**. - -**Warning:** Emails using this domain will fail to send after removal. - -## Troubleshooting - -### Domain won't verify - -**1. Check DNS records are correct** - -Verify records are added exactly as provided - -**2. Wait for propagation** - -DNS changes can take up to 48 hours to propagate globally. Check periodically. - -**3. Remove conflicting records** - -If you previously used another email service, remove their DKIM records to avoid conflicts. - -**4. Check for typos** - -Ensure record names and values match exactly. Common issues: -- Extra spaces in values -- Missing dots in record names -- Wrong subdomain - -### Emails not sending from domain - -**1. Verify domain is verified** - Check status in **Settings > Domains**. - -**2. Use correct email format** - -Must be `username@yourdomain.com`, not `@subdomain.yourdomain.com`. - -**3. Check sender reputation** - -New domains have no reputation. Start with small volumes and gradually increase. - -### Emails going to spam - -After adding custom domain: - -**1. Warm up your domain** — See [Scaling Email](/guides/scaling-email) - -**2. Monitor deliverability** — Check [Analytics](/guides/analytics) for bounce/complaint rates - -**3. Clean your list** — Remove bounced addresses immediately - -## Best practices - -**Start small** — Send to engaged users first to build reputation. - -**Monitor metrics** — Watch bounce and complaint rates closely. - -**Use subdomains** — Consider `mail.yourdomain.com` for email to separate from main domain reputation. - -**Keep DNS records** — Don't remove DKIM records even if verification is complete. - -**Test thoroughly** — Send test emails to various providers (Gmail, Outlook, Yahoo). - -## Next Steps - -- [Scale email delivery](/guides/scaling-email) with your custom domain -- [Monitor analytics](/guides/analytics) for domain performance -- [Troubleshoot issues](/guides/troubleshooting) if problems arise diff --git a/apps/wiki/content/docs/guides/email-attachments.mdx b/apps/wiki/content/docs/guides/email-attachments.mdx deleted file mode 100644 index 6b6e61d..0000000 --- a/apps/wiki/content/docs/guides/email-attachments.mdx +++ /dev/null @@ -1,385 +0,0 @@ ---- -title: Email Attachments -description: Send emails with file attachments via API or SMTP ---- - -## Overview - -Plunk supports sending emails with file attachments through both the HTTP API and SMTP relay. You can attach documents, images, PDFs, and other files to your transactional emails. - -## Limits - -- **Maximum attachments**: 10 per email -- **Total size limit**: 10MB (combined size of all attachments) -- **Supported formats**: Any file type (PDF, images, documents, etc.) - -## API Usage - -### Basic Example - -Send an email with a single PDF attachment: - -```bash -curl -X POST https://api.useplunk.com/v1/send \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "to": "user@example.com", - "subject": "Your Invoice", - "body": "Please find your invoice attached.
", - "attachments": [ - { - "filename": "invoice.pdf", - "content": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL...", - "contentType": "application/pdf" - } - ] - }' -``` - -### Multiple Attachments - -Send multiple files in a single email: - -```json -{ - "to": "user@example.com", - "subject": "Monthly Reports", - "body": "Please find this month's reports attached.
", - "attachments": [ - { - "filename": "sales-report.pdf", - "content": "JVBERi0xLjQK...", - "contentType": "application/pdf" - }, - { - "filename": "logo.png", - "content": "iVBORw0KGgo...", - "contentType": "image/png" - }, - { - "filename": "data.csv", - "content": "TmFtZSxFbWFp...", - "contentType": "text/csv" - } - ] -} -``` - -## Attachment Format - -Each attachment object requires three fields: - -### filename - -- **Type**: String -- **Max length**: 255 characters -- **Description**: The name of the file as it will appear to recipients -- **Example**: `"invoice-2024.pdf"` - -### content - -- **Type**: String (Base64 encoded) -- **Description**: The file content encoded in Base64 format -- **Example**: `"JVBERi0xLjQKJeLjz9MK..."` - -### contentType - -- **Type**: String (MIME type) -- **Max length**: 255 characters -- **Description**: The MIME type of the file -- **Examples**: - - PDF: `application/pdf` - - PNG image: `image/png` - - JPEG image: `image/jpeg` - - Word document: `application/vnd.openxmlformats-officedocument.wordprocessingml.document` - - Excel: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` - - CSV: `text/csv` - - ZIP: `application/zip` - -## Base64 Encoding - -Attachments must be Base64 encoded before sending. Here are examples in different languages: - -### JavaScript/Node.js - -```javascript -import fs from 'fs'; - -// Read file and convert to Base64 -const fileBuffer = fs.readFileSync('invoice.pdf'); -const base64Content = fileBuffer.toString('base64'); - -// Send email with attachment -await fetch('https://api.useplunk.com/v1/send', { - method: 'POST', - headers: { - 'Authorization': 'Bearer sk_your_secret_key', - 'Content-Type': 'application/json' - }, - body: JSON.stringify({ - to: 'user@example.com', - subject: 'Invoice', - body: 'Your invoice is attached.
', - attachments: [{ - filename: 'invoice.pdf', - content: base64Content, - contentType: 'application/pdf' - }] - }) -}); -``` - -### Python - -```python -import base64 -import requests - -# Read and encode file -with open('invoice.pdf', 'rb') as file: - base64_content = base64.b64encode(file.read()).decode('utf-8') - -# Send email -response = requests.post( - 'https://api.useplunk.com/v1/send', - headers={ - 'Authorization': 'Bearer sk_your_secret_key', - 'Content-Type': 'application/json' - }, - json={ - 'to': 'user@example.com', - 'subject': 'Invoice', - 'body': 'Your invoice is attached.
', - 'attachments': [{ - 'filename': 'invoice.pdf', - 'content': base64_content, - 'contentType': 'application/pdf' - }] - } -) -``` - -### PHP - -```php - 'user@example.com', - 'subject' => 'Invoice', - 'body' => 'Your invoice is attached.
', - 'attachments' => [[ - 'filename' => 'invoice.pdf', - 'content' => $base64Content, - 'contentType' => 'application/pdf' - ]] -])); - -$response = curl_exec($ch); -curl_close($ch); -``` - -## SMTP Usage - -When using the SMTP relay, attachments are automatically parsed from the MIME multipart message and forwarded to the API. - -### Standard Email Clients - -Configure your email client with Plunk SMTP settings and attach files normally: - -- **SMTP Server**: `smtp.yourdomain.com` -- **Port**: 587 (STARTTLS) or 465 (SSL/TLS) -- **Username**: `plunk` -- **Password**: Your Plunk API secret key - -Attachments added through your email client will be automatically included. - -### Programmatic SMTP - -Using nodemailer (Node.js): - -```javascript -import nodemailer from 'nodemailer'; - -const transporter = nodemailer.createTransport({ - host: 'smtp.yourdomain.com', - port: 587, - secure: false, // Use STARTTLS - auth: { - user: 'plunk', - pass: 'sk_your_secret_key' - } -}); - -await transporter.sendMail({ - from: 'sender@yourdomain.com', - to: 'recipient@example.com', - subject: 'Invoice', - html: 'Your invoice is attached.
', - attachments: [ - { - filename: 'invoice.pdf', - path: '/path/to/invoice.pdf' - } - ] -}); -``` - -## Common MIME Types - -| File Type | MIME Type | -|-----------|-----------| -| PDF | `application/pdf` | -| PNG | `image/png` | -| JPEG | `image/jpeg` | -| GIF | `image/gif` | -| Word (.docx) | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | -| Word (.doc) | `application/msword` | -| Excel (.xlsx) | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | -| Excel (.xls) | `application/vnd.ms-excel` | -| CSV | `text/csv` | -| Plain text | `text/plain` | -| HTML | `text/html` | -| ZIP | `application/zip` | -| JSON | `application/json` | -| XML | `application/xml` | - -## Best Practices - -### Size Optimization - -- **Compress files**: Use ZIP compression for large files -- **Optimize images**: Reduce image dimensions and quality before attaching -- **Use links for large files**: For files >5MB, consider uploading to cloud storage and sending a download link instead - -### Security - -- **Scan for malware**: Ensure files are virus-free before sending -- **Avoid executable files**: Don't attach .exe, .bat, .sh files (often blocked by email providers) -- **Use password protection**: For sensitive documents, password-protect files and send password separately - -### Deliverability - -- **Mind the size**: Smaller emails have better deliverability -- **Avoid spam triggers**: Don't attach executable files or suspicious content -- **Test first**: Send test emails to verify attachments arrive correctly - -## Troubleshooting - -### Attachment Too Large - -**Error**: `Total attachment size must not exceed 10MB` - -**Solution**: -- Reduce file sizes -- Compress files -- Split into multiple emails -- Use cloud storage links instead - -### Invalid Base64 - -**Error**: `Invalid attachment content - must be base64 encoded` - -**Solution**: -- Ensure file is properly base64 encoded -- Don't include line breaks in base64 string (or use standard base64 encoding) -- Verify encoding matches content (binary files need binary encoding) - -### Wrong Content Type - -**Issue**: Attachments don't open correctly - -**Solution**: -- Use correct MIME type for file format -- Verify file extension matches content type -- Test with common email clients - -### Missing Attachment - -**Issue**: Email sends but attachment missing - -**Solution**: -- Check attachment array is properly formatted -- Verify all required fields (filename, content, contentType) -- Check email provider limits (some block certain types) -- Review AWS SES sending logs - -## Examples by Use Case - -### Invoice Email - -```json -{ - "to": "customer@example.com", - "subject": "Invoice #12345", - "body": "Your invoice is attached.
", - "attachments": [{ - "filename": "invoice-12345.pdf", - "content": "JVBERi0xLjQK...", - "contentType": "application/pdf" - }] -} -``` - -### Report with Charts - -```json -{ - "to": "manager@company.com", - "subject": "Weekly Analytics Report", - "body": "See attached for details.
", - "attachments": [ - { - "filename": "analytics-report.pdf", - "content": "JVBERi0xLjQK...", - "contentType": "application/pdf" - }, - { - "filename": "sales-chart.png", - "content": "iVBORw0KGgo...", - "contentType": "image/png" - } - ] -} -``` - -### Welcome Kit - -```json -{ - "to": "newuser@example.com", - "subject": "Welcome to Our Service!", - "body": "Here's everything you need to get started.
", - "attachments": [ - { - "filename": "getting-started-guide.pdf", - "content": "JVBERi0xLjQK...", - "contentType": "application/pdf" - }, - { - "filename": "sample-data.csv", - "content": "TmFtZSxFbWFp...", - "contentType": "text/csv" - } - ] -} -``` - -## Next Steps - -- [Send your first email](/getting-started/quick-start) -- [SMTP relay setup](/self-hosting/introduction) -- [Email templates](/guides/templates) diff --git a/apps/wiki/content/docs/guides/events.mdx b/apps/wiki/content/docs/guides/events.mdx deleted file mode 100644 index 8e3480e..0000000 --- a/apps/wiki/content/docs/guides/events.mdx +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: Events -description: Track user actions and behavior ---- - -## What are events - -Events track user actions in your application. Use them to: -- Trigger automated workflows -- Build behavior-based segments -- Analyze user engagement -- Track conversion funnels - -Common events: signups, purchases, logins, feature usage, page views. - -## Tracking events - -Use your **public key** for event tracking: - -```javascript -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', - page: '/pricing' - } - }) -}); -``` - -This creates or updates the contact and tracks the event. - -### Persistent vs. Non-Persistent Data - -Event data can be either **persistent** (saved to contact) or **non-persistent** (available only to workflows): - -**Simple values are persistent** — Saved to contact profile: -```javascript -{ - email: 'user@example.com', - event: 'subscription_created', - data: { - plan: 'premium', // Saved to contact.data.plan - mrr: 99.00 // Saved to contact.data.mrr - } -} -``` - -**Non-persistent values** — Available only to triggered workflows: -```javascript -{ - email: 'user@example.com', - event: 'order_placed', - data: { - totalSpent: 299.99, // Persistent - saved to contact - orderId: {value: 'order-12345', persistent: false}, // Non-persistent - workflows only - receiptUrl: {value: 'https://...', persistent: false} // Non-persistent - workflows only - } -} -``` - -**Why use non-persistent data?** -- Temporary tokens/codes (password reset, verification) -- One-time URLs or session data -- Data that shouldn't pollute contact profiles -- Information needed only for a specific workflow - -Non-persistent data is available throughout the entire workflow execution but never stored on the contact record. - -## Event structure - -Each event stores: - -```json -{ - "id": "evt_abc123", - "name": "purchase", - "contactId": "contact_xyz", - "data": { - "product": "Premium Plan", - "amount": 99.00 - }, - "createdAt": "2024-03-15T10:30:00Z" -} -``` - -## Using events -You can use events to trigger workflows, create segments, and analyze user behavior. - -## Common event patterns - -### Lifecycle events - -```javascript -// User signs up -track({ email, event: 'signed_up', data: { source: 'homepage' } }); - -// User activates account -track({ email, event: 'account_activated' }); - -// User completes onboarding -track({ email, event: 'onboarding_completed', data: { steps: 5 } }); -``` - -### Commerce events - -```javascript -// Add to cart -track({ email, event: 'cart_added', data: { productId: '123', price: 49 } }); - -// Purchase -track({ email, event: 'purchase', data: { orderId: '456', total: 99 } }); - -// Subscription created -track({ email, event: 'subscription_created', data: { plan: 'pro', mrr: 29 } }); -``` - -### Engagement events - -```javascript -// Feature used -track({ email, event: 'feature_used', data: { feature: 'export' } }); - -// Page viewed -track({ email, event: 'page_view', data: { path: '/dashboard' } }); - -// Login -track({ email, event: 'logged_in' }); -``` - -### Automatic events - -Plunk sends these automatically: - -**Email events:** -- `email.sent` — Email delivered to inbox -- `email.opened` — Email opened (first time) -- `email.clicked` — Link clicked in email -- `email.bounced` — Email bounced -- `email.complained` — Spam complaint - -**Segment events** (if membership tracking enabled): -- `segment.entered` — Contact joined segment -- `segment.exited` — Contact left segment - -## Event naming conventions - -**Use lowercase with underscores:** -``` -✓ user_signed_up -✓ purchase_completed -✗ UserSignedUp -✗ purchaseCompleted -``` - -**Be specific but concise:** -``` -✓ trial_started -✓ subscription_cancelled -✗ user_started_a_trial -✗ sub_cancel -``` - -**Group related events:** -``` -user_signed_up -user_logged_in -user_deleted_account - -subscription_created -subscription_renewed -subscription_cancelled -``` - -## Managing events - -### List events - -```bash -curl -X GET "{{API_URL}}/events?limit=100" \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -### List unique event names - -```bash -curl -X GET {{API_URL}}/events/names \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Returns all event names tracked in your project. - -### Get events for a contact - -```bash -curl -X GET {{API_URL}}/events?contactId=contact_id \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -## Best practices - -**Track meaningful actions** — Focus on events that indicate intent or value (signups, purchases, key features). - -**Include context** — Add relevant data to understand the event better (product, amount, source). - -**Be consistent** — Use the same event names and data structure across your application. - -**Don't over-track** — Tracking every click creates noise. Focus on conversion events and key milestones. - -**Test your tracking** — Verify events appear in dashboard before building workflows around them. - -## What's next - -- [Build workflows](/guides/workflows) triggered by events -- [Create segments](/guides/segments) based on event data -- [Analyze events](/guides/analytics) to understand user behavior diff --git a/apps/wiki/content/docs/guides/meta.json b/apps/wiki/content/docs/guides/meta.json deleted file mode 100644 index cd43e7a..0000000 --- a/apps/wiki/content/docs/guides/meta.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "title": "Guides", - "pages": [ - "contacts", - "templates", - "campaigns", - "segments", - "workflows", - "events", - "webhooks", - "analytics", - "custom-domains", - "billing-limits", - "scaling-email", - "troubleshooting" - ] -} diff --git a/apps/wiki/content/docs/guides/request-ids.mdx b/apps/wiki/content/docs/guides/request-ids.mdx deleted file mode 100644 index 72e9e3a..0000000 --- a/apps/wiki/content/docs/guides/request-ids.mdx +++ /dev/null @@ -1,307 +0,0 @@ ---- -title: Request IDs & Debugging -description: How to use request IDs for debugging and tracing API requests ---- - -## Overview - -Every API request to Plunk receives a unique request ID that follows the request through the entire system. Request IDs are essential for debugging, support, and monitoring. - -## What are Request IDs? - -A request ID is a UUID (e.g., `f47ac10b-58cc-4372-a567-0e02b2c3d479`) that: -- Is generated for every API request -- Appears in all related log entries -- Is included in both success and error responses -- Can be used to trace requests across services - -## Where to Find Request IDs - -### In API Responses - -**Error responses** (in the `error.requestId` field): -```json -{ - "success": false, - "error": { - "code": "VALIDATION_ERROR", - "message": "Request validation failed", - "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", - ... - } -} -``` - -**Response headers** (always present, even on success): -```bash -X-Request-ID: f47ac10b-58cc-4372-a567-0e02b2c3d479 -``` - -### In Your Application - -You can capture and log request IDs for correlation: - -```javascript -const response = await fetch('https://api.useplunk.com/v1/send', { - method: 'POST', - headers: { - 'Authorization': `Bearer ${apiKey}`, - 'Content-Type': 'application/json' - }, - body: JSON.stringify({ to, subject, body }) -}); - -// Get request ID from response header -const requestId = response.headers.get('X-Request-ID'); - -// Log it for correlation -console.log(`[${requestId}] Email send request initiated`); - -const data = await response.json(); -if (!data.success) { - // Request ID is also in error response - console.error(`[${data.error.requestId}] Error:`, data.error.message); -} -``` - -## Database Request Logging - -In addition to console/file logs, Plunk stores all API requests in the database with their request IDs. This provides: - -- **Historical audit trail** - See all API calls made to your project -- **Analytics** - Analyze API usage patterns, error rates, popular endpoints -- **User-facing logs** - Display API request history in your dashboard -- **Long-term debugging** - Investigate issues that occurred days or weeks ago -- **Compliance** - Meet audit requirements for API access logs - -### Database Schema - -Each request is stored with: -- Request ID (primary key) -- HTTP method and path -- Status code and response time -- Project ID and user ID (if authenticated) -- IP address and user agent -- Error code and message (if failed) -- Request/response sizes -- Timestamp - -### Retention Policy - -API request logs are retained for **30 days** by default. A background job runs daily at 3 AM to delete older logs. This prevents unbounded table growth while maintaining recent history for debugging. - -You can query your request logs via SQL if self-hosting: - -```sql --- Find all failed requests in the last 24 hours -SELECT * FROM api_requests -WHERE "statusCode" >= 400 -AND "createdAt" > NOW() - INTERVAL '24 hours' -ORDER BY "createdAt" DESC; - --- Find all requests for a specific project -SELECT * FROM api_requests -WHERE "projectId" = 'prj_abc123' -ORDER BY "createdAt" DESC -LIMIT 100; - --- Analyze error rates by endpoint -SELECT - path, - COUNT(*) as total_requests, - COUNT(*) FILTER (WHERE "statusCode" >= 400) as errors, - ROUND(100.0 * COUNT(*) FILTER (WHERE "statusCode" >= 400) / COUNT(*), 2) as error_rate_pct -FROM api_requests -WHERE "createdAt" > NOW() - INTERVAL '7 days' -GROUP BY path -ORDER BY error_rate_pct DESC; -``` - -## How Request IDs Help with Debugging - -### Example Scenario - -You send an email via the API and receive an error. Here's how request IDs help: - -**1. Your application receives an error:** -```json -{ - "success": false, - "error": { - "code": "TEMPLATE_NOT_FOUND", - "message": "Template with ID \"tpl_abc123\" was not found", - "requestId": "a1b2c3d4-e5f6-7890-gh12-i34567890jkl", - ... - } -} -``` - -**2. You contact support with the request ID** - -**3. We search our logs for that request ID and see:** - -``` -[a1b2c3d4-e5f6-7890-gh12-i34567890jkl] POST /v1/send → Request received - └─ authType: apiKey - └─ projectId: prj_xyz789 - └─ ip: 192.168.1.1 - -[a1b2c3d4-e5f6-7890-gh12-i34567890jkl] Looking up template: tpl_abc123 - └─ projectId: prj_xyz789 - -[a1b2c3d4-e5f6-7890-gh12-i34567890jkl] Template not found - └─ errorCode: TEMPLATE_NOT_FOUND - └─ statusCode: 404 - -[a1b2c3d4-e5f6-7890-gh12-i34567890jkl] POST /v1/send → 404 (45ms) -``` - -From this, we can immediately see: -- You're authenticated correctly (authType: apiKey) -- The template ID doesn't exist in your project -- The request took 45ms to process -- No database errors or system issues - -**Result:** We can quickly tell you "That template doesn't exist in your project" without back-and-forth debugging. - -## Using Request IDs in Self-Hosted Deployments - -If you're self-hosting Plunk, you can use request IDs to debug issues in your own logs. - -### Searching Logs - -**With Docker logs:** -```bash -# Find all logs for a specific request -docker logs plunk-api 2>&1 | grep "a1b2c3d4-e5f6-7890-gh12-i34567890jkl" -``` - -**With standard logs:** -```bash -# Search application logs -grep "a1b2c3d4-e5f6-7890-gh12-i34567890jkl" /var/log/plunk/api.log - -# Search with context (10 lines before and after) -grep -C 10 "a1b2c3d4-e5f6-7890-gh12-i34567890jkl" /var/log/plunk/api.log -``` - -### Log Structure - -Every log entry includes the request ID in brackets: - -``` -[f47ac10b-58cc-4372-a567-0e02b2c3d479] POST /v1/track → Request received -[f47ac10b-58cc-4372-a567-0e02b2c3d479] Contact created: cnt_abc123 -[f47ac10b-58cc-4372-a567-0e02b2c3d479] Event tracked: evt_xyz789 -[f47ac10b-58cc-4372-a567-0e02b2c3d479] POST /v1/track → 200 (127ms) -``` - -This makes it easy to trace a single request from start to finish. - -## Providing Request IDs with Load Balancers - -If you use a load balancer or API gateway, you can pass your own request IDs: - -```bash -curl -X POST https://api.useplunk.com/v1/send \ - -H "X-Request-ID: your-custom-request-id" \ - -H "Authorization: Bearer sk_..." \ - -H "Content-Type: application/json" \ - -d '...' -``` - -Plunk will use your provided request ID instead of generating a new one. This allows you to: -- Correlate requests across your entire system -- Trace requests from your frontend → your backend → Plunk → email delivery -- Maintain consistent request IDs in your monitoring tools - -## Best Practices - -### 1. Always Log Request IDs - -```javascript -// ✅ Good: Log request ID for correlation -const response = await plunk.send(email); -const requestId = response.headers.get('X-Request-ID'); -logger.info(`Email sent to ${email.to}`, { requestId }); -``` - -```javascript -// ❌ Bad: Discard request ID -await plunk.send(email); -// No way to correlate this with Plunk's logs -``` - -### 2. Include in Error Reporting - -```javascript -// ✅ Good: Include request ID in error reports -try { - await plunk.send(email); -} catch (error) { - Sentry.captureException(error, { - extra: { - requestId: error.requestId, - emailTo: email.to - } - }); -} -``` - -### 3. Store for Audit Trails - -```javascript -// ✅ Good: Store request ID in your database -await db.emailLog.create({ - to: email.to, - subject: email.subject, - plunkRequestId: requestId, - sentAt: new Date() -}); -``` - -### 4. Return to End Users (Optional) - -For customer-facing applications, you can show request IDs to users: - -``` -❌ Error sending email. Please try again. -``` - -``` -❌ Error sending email. Please contact support and provide this reference: a1b2c3d4-e5f6 -``` - -## Monitoring and Observability - -Request IDs are essential for: - -- **Distributed tracing** - Follow requests across services -- **Error correlation** - Link errors to specific API calls -- **Performance monitoring** - Identify slow requests -- **Debugging production** - Reproduce issues without PII -- **Rate limit tracking** - Monitor usage patterns per project - -## FAQ - -### Do request IDs expire? - -No, request IDs are logged indefinitely (subject to your log retention policy). - -### Can I reuse request IDs? - -No, each request should have a unique ID. If you send the same request ID twice, logs will be mixed. - -### Are request IDs sequential? - -No, they are random UUIDs. This prevents information leakage about request volume. - -### Can I search by request ID in the dashboard? - -This feature is planned but not yet available. For now, contact support with the request ID. - -## Related Documentation - -- [Error Codes](/api-reference/errors) - Understanding API errors -- [API Reference](/api-reference/overview) - Complete API documentation -- [Troubleshooting](/guides/troubleshooting) - Common issues and solutions diff --git a/apps/wiki/content/docs/guides/scaling-email.mdx b/apps/wiki/content/docs/guides/scaling-email.mdx deleted file mode 100644 index f93c452..0000000 --- a/apps/wiki/content/docs/guides/scaling-email.mdx +++ /dev/null @@ -1,277 +0,0 @@ ---- -title: Scaling Email Delivery -description: Best practices for high-volume email sending ---- - -## Email delivery at scale - -Plunk is built on AWS SES and handles millions of emails. Follow these practices to maintain high deliverability and performance at scale. - -## Deliverability best practices - -### Use custom domains - -Emails from custom domains have higher trust and better deliverability than shared domains. - -**Setup:** -1. Go to **Settings > Domains** -2. Add your domain -3. Configure DNS records (DKIM, SPF) -4. Wait for verification - -[Learn more about custom domains →](/guides/custom-domains) - -### Warm up new domains - -Start small and gradually increase volume. - -This builds sender reputation with email providers. - -### Clean your list regularly - -Remove bounced and inactive contacts: - -```javascript -// Get bounced contacts -const bounced = await fetch('{{API_URL}}/events?name=email.bounced&limit=1000', { - headers: { 'Authorization': `Bearer ${apiKey}` } -}); - -// Unsubscribe them -for (const event of bounced.data.events) { - await fetch(`{{API_URL}}/contacts/${event.contactId}`, { - method: 'PATCH', - headers: { - 'Authorization': `Bearer ${apiKey}`, - 'Content-Type': 'application/json' - }, - body: JSON.stringify({ subscribed: false }) - }); -} -``` - -**When to clean:** -- Hard bounces: Immediately unsubscribe -- Soft bounces: After 3 attempts -- No engagement: After 6-12 months - -### Segment your audience - -Send relevant content to engaged users: - -```javascript -// Create engaged users segment -{ - "name": "Engaged Users", - "filters": { - "operator": "OR", - "conditions": [ - { "field": "data.lastOpenedAt", "operator": "greaterThan", "value": "{{90 days ago}}" }, - { "field": "data.lastClickedAt", "operator": "greaterThan", "value": "{{90 days ago}}" } - ] - } -} -``` - -Send campaigns to engaged segments for better rates. - -## Tracking control - -You can disable tracking in your project settings for privacy-focused audiences or to reduce email size. - -**When tracking is disabled:** -- No tracking pixel (no open tracking) -- Links not rewritten (no click tracking) -- Smaller email size -- May improve deliverability for privacy-conscious audiences - -**When to disable:** -- Regulated industries (healthcare, finance) -- Privacy-focused users -- Transactional emails where tracking isn't needed -- High-volume sends where analytics aren't critical - -## Rate limits - -### AWS SES limits - -Plunk automatically queues emails to stay within limits. Large sends process in background. - -### Increase limits - -For higher throughput: -1. Maintain good sender reputation -2. Consistent sending volume -3. Low bounce/complaint rates -4. Request limit increase from AWS - -### Batch operations - -For bulk operations, use appropriate endpoints: - -```javascript -// ✓ Good: Single request for multiple recipients -fetch('{{API_URL}}/v1/send', { - method: 'POST', - body: JSON.stringify({ - to: ['user1@example.com', 'user2@example.com', 'user3@example.com'], - subject: 'Update', - body: 'Message' - }) -}); - -// ✗ Avoid: Multiple requests -for (const email of emails) { - await fetch('{{API_URL}}/v1/send', {...}); // Sequential, slow -} -``` - -## Campaign targeting - -### Dynamic filtering - -Target audiences without creating segments: - -```javascript -{ - "name": "Premium Launch", - "audienceType": "FILTERED", - "audienceFilter": { - "operator": "AND", - "conditions": [ - { "field": "data.plan", "operator": "equals", "value": "premium" }, - { "field": "data.signupDate", "operator": "greaterThan", "value": "2025-01-01" }, - { "field": "subscribed", "operator": "equals", "value": true } - ] - }, - "templateId": "template_id" -} -``` - -**Use FILTERED for:** -- One-time sends -- Testing targeting -- Very specific criteria - -**Use SEGMENT for:** -- Repeated targeting -- Workflow triggers -- Segment analytics - -## Segment membership tracking - -For segments used in workflows, enable membership tracking: - -```bash -curl -X POST {{API_URL}}/segments \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Active Premium Users", - "filters": {...}, - "trackMembership": true - }' -``` - -**Enable for:** -- Workflow trigger segments -- Lifecycle stage tracking -- Cohort analysis - -**Disable for:** -- Large segments (100k+ contacts) -- Campaign-only segments -- Frequently changing segments - -Membership updates run every 5 minutes in background. - -## Performance optimization - -### Cache contact data - -For high-volume API sends, cache contact lookups: - -```javascript -// Cache contact IDs locally -const contactCache = new Map(); - -async function getContactId(email) { - if (contactCache.has(email)) { - return contactCache.get(email); - } - - const contact = await fetch(`{{API_URL}}/contacts?search=${email}`); - contactCache.set(email, contact.id); - return contact.id; -} -``` - -### Use webhooks for async processing - -Instead of waiting for email sends: - -```javascript -// Workflow with webhook for confirmation -{ - "steps": [ - { "type": "SEND_EMAIL", "config": {...} }, - { - "type": "WEBHOOK", - "config": { - "url": "https://your-api.com/email-sent", - "method": "POST", - "body": { - "contactId": "{{id}}", - "emailId": "{{emailId}}" - } - } - } - ] -} -``` - -### Batch workflow triggers - -Trigger workflows in batches instead of one at a time: - -```javascript -// Batch event tracking -const events = users.map(user => ({ - email: user.email, - event: 'welcome_campaign', - data: { userId: user.id } -})); - -// Send in parallel (respecting rate limits) -await Promise.all( - events.map(event => - fetch('{{API_URL}}/v1/track', { - method: 'POST', - headers: { - 'Authorization': `Bearer ${apiKey}`, - 'Content-Type': 'application/json' - }, - body: JSON.stringify(event) - }) - ) -); -``` - -## Monitoring - -### Track key metrics - -Monitor these regularly: - -- **Bounce rate** — Should be < 2% -- **Complaint rate** — Should be < 0.1% -- **Open rate** — Industry average 15-25% -- **Click rate** — Industry average 2-5% - -Monitor these metrics in your dashboard analytics page to track deliverability and engagement over time. - -## Next Steps - -- [Set billing limits](/guides/billing-limits) to control costs -- [Monitor analytics](/guides/analytics) for deliverability -- [Troubleshoot issues](/guides/troubleshooting) if problems arise diff --git a/apps/wiki/content/docs/guides/segments.mdx b/apps/wiki/content/docs/guides/segments.mdx deleted file mode 100644 index 8b4f37e..0000000 --- a/apps/wiki/content/docs/guides/segments.mdx +++ /dev/null @@ -1,342 +0,0 @@ ---- -title: Segments -description: Create dynamic audience groups with filters ---- - -## What are segments - -Segments are dynamic groups of contacts based on filter conditions. Unlike static lists, segments automatically update as contact data changes. - -Use segments to: -- Target specific audiences in campaigns -- Trigger workflows when contacts enter/exit -- Analyze cohorts and user behavior -- Personalize communications - -## Creating segments - -### In the dashboard - -1. Go to **Segments** -2. Click **Create Segment** -3. Name your segment -4. Add filter conditions -5. Enable membership tracking (optional) -6. Save - -### Via API - -```bash -curl -X POST {{API_URL}}/segments \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Active Premium Users", - "filters": { - "operator": "AND", - "conditions": [ - { - "field": "data.plan", - "operator": "equals", - "value": "premium" - }, - { - "field": "subscribed", - "operator": "equals", - "value": true - } - ] - } - }' -``` - -## Filter conditions - -Combine conditions with `AND` or `OR` operators to build precise segments. - -### Available operators - -**Equality** -- `equals` — Exact match -- `notEquals` — Does not match - -**Text** -- `contains` — String includes value -- `notContains` — String excludes value - -**Numeric/Date** -- `greaterThan` — Larger than value -- `lessThan` — Smaller than value -- `greaterThanOrEquals` — At least value -- `lessThanOrEquals` — At most value - -**Arrays** -- `in` — Value in array -- `notIn` — Value not in array - -**Existence** -- `exists` — Field has a value -- `notExists` — Field is missing or null - -### Field paths - -Access contact fields with dot notation: - -- `email` — Contact email address -- `subscribed` — Subscription status -- `createdAt` — When contact was created -- `data.firstName` — Custom field -- `data.preferences.newsletter` — Nested field -- `data.lastPurchaseDate` — Custom date field - -## Example segments - -### Premium subscribers - -All contacts on premium plan who are subscribed: - -```json -{ - "operator": "AND", - "conditions": [ - { "field": "data.plan", "operator": "equals", "value": "premium" }, - { "field": "subscribed", "operator": "equals", "value": true } - ] -} -``` - -### Recent signups - -Contacts who joined in the last 7 days: - -```json -{ - "operator": "AND", - "conditions": [ - { - "field": "createdAt", - "operator": "greaterThan", - "value": "{{now - 7 days}}" - } - ] -} -``` - -### Inactive users - -Users who haven't logged in for 30+ days: - -```json -{ - "operator": "AND", - "conditions": [ - { - "field": "data.lastLoginAt", - "operator": "lessThan", - "value": "{{now - 30 days}}" - }, - { - "field": "data.lastLoginAt", - "operator": "exists", - "value": true - } - ] -} -``` - -### High-value customers - -Total spending over $1000: - -```json -{ - "operator": "AND", - "conditions": [ - { - "field": "data.totalSpent", - "operator": "greaterThanOrEquals", - "value": 1000 - }, - { - "field": "subscribed", - "operator": "equals", - "value": true - } - ] -} -``` - -### Free tier churned users - -Users who downgraded from paid to free: - -```json -{ - "operator": "AND", - "conditions": [ - { "field": "data.plan", "operator": "equals", "value": "free" }, - { "field": "data.previousPlan", "operator": "in", "value": ["pro", "premium"] }, - { "field": "data.downgradedAt", "operator": "exists", "value": true } - ] -} -``` - -## Membership tracking - -When you enable `trackMembership`: - -**What happens:** -- Plunk computes and stores segment membership -- When contacts enter, sends `segment.entered` event -- When contacts exit, sends `segment.exited` event -- Provides historical membership data - -**Use when:** -- You want to trigger workflows on entry/exit -- You need to track cohort changes over time -- Segment is relatively stable (not millions of changes per day) - -**Disable when:** -- Segment changes very frequently -- You only need current membership (not history) -- You have millions of contacts and want to save storage - -### Using entry/exit events - -With membership tracking enabled, use segment events to trigger workflows: - -```json -{ - "triggerType": "SEGMENT_ENTRY", - "triggerConfig": { - "segmentId": "high-value-customers" - } -} -``` - -Or use the generic event trigger: - -```json -{ - "triggerType": "EVENT", - "triggerConfig": { - "eventName": "segment.entered" - } -} -``` - -Event data includes: -```json -{ - "segmentId": "seg_abc123", - "segmentName": "High Value Customers" -} -``` - -## Using segments - -### In campaigns - -Send a campaign to a segment: - -```bash -curl -X POST {{API_URL}}/campaigns \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Premium Feature Announcement", - "audienceType": "SEGMENT", - "segmentId": "premium-users", - "templateId": "feature-announcement" - }' -``` - -### In workflows - -Trigger workflows when contacts enter a segment: - -```bash -curl -X POST {{API_URL}}/workflows \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "VIP Welcome", - "triggerType": "SEGMENT_ENTRY", - "triggerConfig": { - "segmentId": "high-value-customers" - } - }' -``` - -## Managing segments - -### Get segment with count - -```bash -curl -X GET {{API_URL}}/segments/segment_id \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Returns member count: - -```json -{ - "id": "segment_id", - "name": "Premium Users", - "memberCount": 1542, - "filters": {...} -} -``` - -### List segment members - -```bash -curl -X GET "{{API_URL}}/segments/segment_id/contacts?limit=50" \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -### Update segment - -```bash -curl -X PATCH {{API_URL}}/segments/segment_id \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Updated name", - "filters": { - "operator": "AND", - "conditions": [...] - } - }' -``` - -When you update filters, membership is recomputed automatically. - -### Delete segment - -```bash -curl -X DELETE {{API_URL}}/segments/segment_id \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Active campaigns and workflows using this segment will stop working. - -## Best practices - -**Start broad, then narrow** — Create general segments first, then add specific conditions. - -**Test your filters** — Preview segment size before using in campaigns to avoid sending to wrong audience. - -**Name clearly** — Use descriptive names: "Q4 2024 Premium Signups" not "Segment 3". - -**Avoid overlapping segments** — If using in workflows, ensure segments don't overlap to prevent duplicate emails. - -**Use for analysis** — Create segments to understand user cohorts, even if not used in campaigns. - -**Combine with events** — Track events and use them in segment conditions for behavior-based targeting. - -## What's next - -- [Build campaigns](/guides/campaigns) to send to segments -- [Create workflows](/guides/workflows) triggered by segment entry -- [Track events](/guides/events) to use in segment filters diff --git a/apps/wiki/content/docs/guides/templates.mdx b/apps/wiki/content/docs/guides/templates.mdx deleted file mode 100644 index 39aa5e5..0000000 --- a/apps/wiki/content/docs/guides/templates.mdx +++ /dev/null @@ -1,287 +0,0 @@ ---- -title: Templates -description: Create reusable email templates ---- - -## Why use templates - -Templates let you design emails once and reuse them across: -- Transactional API sends (`/v1/send`) -- Automated workflows - -Benefits: -- Update design in one place, applies everywhere -- Maintain consistent branding -- Separate content from code - -## Template types - -### Marketing templates - -**Use for:** Newsletters, promotions, announcements - -- Only sends to subscribed contacts -- Automatically includes unsubscribe link -- Respects subscription preferences - -### Transactional templates - -**Use for:** Order confirmations, password resets, receipts - -- Sends to all contacts, even if unsubscribed -- No unsubscribe link required -- Critical business communications - -Choose the right type based on content, not delivery method. You can use both types in campaigns, workflows, and API calls. The type determines subscription enforcement. - -## Creating templates - -### In the dashboard - -1. Go to **Templates** -2. Click **Create Template** -3. Choose type (Marketing or Transactional) -4. Set subject, from address, and body -5. Add variables using `{{variableName}}` -6. Save - -### Via API - -```bash -curl -X POST {{API_URL}}/templates \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "order-confirmation", - "subject": "Order #{{orderNumber}} confirmed", - "body": "Order #{{orderNumber}} will arrive by {{deliveryDate}}.
", - "from": "orders@example.com", - "fromName": "Acme Store", - "type": "TRANSACTIONAL" - }' -``` - -## Using variables - -Variables let you personalize each email. Use `{{variableName}}` syntax: - -```html -Your {{plan}} subscription renews on {{renewalDate}}.
-Total: ${{amount}}
-``` - -When sending, provide values in the `data` object: - -```json -{ - "template": "subscription-renewal", - "data": { - "firstName": "Sarah", - "plan": "Pro", - "renewalDate": "April 15, 2024", - "amount": "29.00" - } -} -``` - -## Persistent vs. Temporary Data - -Template variables can come from **persistent contact data** or **temporary non-persistent data**: - -**Persistent data** — Saved to contact profile: -```json -{ - "to": "user@example.com", - "subject": "Welcome {{firstName}}!", - "body": "Your {{plan}} subscription is active.
", - "data": { - "firstName": "John", // Saved to contact - "plan": "Pro" // Saved to contact - } -} -``` - -**Non-persistent data** — Used only for this email: -```json -{ - "to": "user@example.com", - "subject": "Password Reset", - "body": "Reset code: {{resetCode}}
Hello {{firstName}}!
", - "data": { - "firstName": "John", // Saved to contact - "resetCode": {value: "ABC123", persistent: false} // NOT saved to contact - } -} -``` - -**When to use non-persistent data:** -- One-time verification codes or tokens -- Temporary URLs (password reset, magic links) -- Session-specific information -- Data that shouldn't pollute contact profiles - -**In workflows:** -Non-persistent data from events is available throughout the entire workflow execution via the execution context, allowing you to use tokens/URLs across multiple workflow steps. - -### Fallback values - -Provide defaults for missing data: - -```html -{{user.email}}
-{{order.items.0.name}}
-{{preferences.newsletter}}
-``` - -## Sending with templates - -### Transactional emails - -Use the `template` field with the **template ID** (not the template name): - -```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": "clx123abc456", - "data": { - "orderNumber": "12345", - "deliveryDate": "March 20" - } - }' -``` - -**Finding your template ID:** -- In the dashboard: Go to Templates → Click on your template → Copy the ID from the URL or template details -- Via API: Use `GET /templates` to list all templates with their IDs - -When using a template: -- **Subject, body, from, and reply-to** are automatically taken from the template -- **Template variables** (e.g., `{{orderNumber}}`) are populated from the `data` field -- You can **override** any template value by explicitly providing it in the request (see example below) - -### Overriding template values - -```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": "clx123abc456", - "subject": "Custom Subject (overrides template)", - "from": { - "name": "Custom Sender", - "email": "custom@example.com" - }, - "data": { - "orderNumber": "12345" - } - }' -``` - -### In workflows - -When creating a **Send Email** workflow step, select the template from the dropdown. Variables are automatically filled from contact data and workflow context. - -### In campaigns - -When creating a campaign, choose a template instead of composing inline. All campaign recipients get the same template with personalized variables. - -## When to use inline vs templates - -**Use templates when:** -- Sending the same email repeatedly -- Multiple workflows/campaigns use same design -- Design may change over time -- Want to centralize branding - -**Use inline content when:** -- One-off transactional emails -- Unique per-user content -- Testing or prototyping -- Content is generated dynamically - -Example inline send: - -```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": "Your verification code", - "body": "Your code: {{code}}
", - "data": {"code": "ABC123"} - }' -``` - -## Managing templates - -### List templates - -```bash -curl -X GET {{API_URL}}/templates \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Filter by type: - -```bash -curl -X GET "{{API_URL}}/templates?type=MARKETING" \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -### Update template - -```bash -curl -X PATCH {{API_URL}}/templates/template_id \ - -H "Authorization: Bearer sk_your_secret_key" \ - -H "Content-Type: application/json" \ - -d '{ - "subject": "New subject line", - "body": "Updated content
" - }' -``` - -Changes apply to all future sends using this template. - -### Delete template - -```bash -curl -X DELETE {{API_URL}}/templates/template_id \ - -H "Authorization: Bearer sk_your_secret_key" -``` - -Templates used in active workflows are not deleted—you'll need to update workflows first. - -## Best practices - -**Keep templates simple** — Focus on content, avoid complex layouts that break in email clients. - -**Test across clients** — Email rendering varies. Preview in Gmail, Outlook, Apple Mail, and mobile devices. - -**Use semantic HTML** — Use ``, `` instead of styled ` Hi {'{{firstName}}'}! Order #{'{{orderNumber}}'}: ${'{{orderTotal}}'} Delivery: {'{{deliveryDate}}'} Order #{{orderNumber}} confirmed! Total: ${{orderTotal}} Tracking: View shipment Click here to reset: Reset Password Your first email! Click here: Reset Password Click here: Reset Password Hi {{name}}, click here: Reset Hi {{name}}, Click here to reset your password: This link expires in 1 hour. Click here: Reset Password Hi {{firstName ?? 'there'}}, We've been busy this month. Here's what's new: Invite team members and collaborate in real-time. Everything is now 2x faster. Better insights into your data. Thanks,
- You're receiving this because you subscribed to updates.
- Unsubscribe
- Hi {{firstName ?? 'there'}},Hi {{firstName}}!
-What's new in March
-
-🚀 New Feature: Team Collaboration
-⚡ Improved Performance
-📊 New Analytics Dashboard
-
The Team