Plunk

https://docs.useplunk.com/
Admin
Plunk is an open-source email platform for AWS that enables users to set up email automations, send...
Tokens:55,992
Snippets:594
Trust Score:8.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### GET /projects/:id/setup-state

Source: https://docs.useplunk.com/api-reference/overview.md

Retrieves the onboarding setup state for a specific project.

```APIDOC
## GET /projects/:id/setup-state

### Description
Onboarding setup state.

### Method
GET

### Endpoint
/projects/:id/setup-state

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **state** (string) - The current setup state of the project (e.g., "completed", "in_progress").
```

--------------------------------

### Example request using cURL

Source: https://docs.useplunk.com/api-reference/contacts/createContact.md

A command-line example showing how to authenticate and send the request.

```bash
curl -X POST 'https://next-api.useplunk.com/contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com"}'
```

--------------------------------

### Example DMARC Record

Source: https://docs.useplunk.com/guides/verifying-domains.md

This is an example of a DMARC TXT record. It's recommended to start with 'p=none' for monitoring before tightening to 'quarantine' or 'reject'.

```text
v=DMARC1; p=none; rua=mailto:dmarc-reports@yourdomain.com
```

--------------------------------

### Email Sending Request Examples

Source: https://docs.useplunk.com/openapi.json

Examples of JSON payloads for sending emails, including template overrides, marketing emails, and attachments.

```json
{"to":"user@example.com","template":"9c4d5e1f-2a3b-4c5d-8e9f-0a1b2c3d4e5f","subject":"Custom Subject Override","data":{"firstName":"Jane"}}
```

```json
{"to":"user@example.com","subject":"Weekly Newsletter","body":"<h1>This Week's Updates</h1>","subscribed":true}
```

```json
{"to":"user@example.com","subject":"Your Invoice","body":"<h1>Invoice Attached</h1><p>Please find your invoice attached.</p>","attachments":[{"filename":"invoice.pdf","content":"JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL...","contentType":"application/pdf"}]}
```

--------------------------------

### List segments request example

Source: https://docs.useplunk.com/api-reference/segments/listSegments.md

Example cURL request to retrieve all segments using an API key.

```bash
curl -X GET 'https://next-api.useplunk.com/segments' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

--------------------------------

### Webhook URL Example

Source: https://docs.useplunk.com/guides/webhooks.md

Example of a webhook URL that uses contact ID for parameterization. Ensure a static scheme (http/https) is included.

```text
https://api.example.com/users/{{id}}/events
```

--------------------------------

### Response examples

Source: https://docs.useplunk.com/api-reference/contacts/createContact.md

JSON response structures for successful operations and error states.

```json
{
  "id": "string",
  "email": "user@example.com",
  "subscribed": false,
  "data": null,
  "createdAt": "2026-08-10T16:42:13.831Z",
  "updatedAt": "2026-08-10T16:42:13.831Z",
  "_meta": {
    "isNew": false,
    "isUpdate": false
  }
}
```

```json
{
  "id": "string",
  "email": "user@example.com",
  "subscribed": false,
  "data": null,
  "createdAt": "2026-08-10T16:42:13.831Z",
  "updatedAt": "2026-08-10T16:42:13.831Z",
  "_meta": {
    "isNew": false,
    "isUpdate": false
  }
}
```

```json
{
  "error": "string"
}
```

```json
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "statusCode": 0,
    "requestId": "string",
    "errors": [
      {
        "field": "string",
        "message": "string",
        "code": "string",
        "received": null
      }
    ],
    "details": null,
    "suggestion": "string"
  },
  "timestamp": "2026-08-10T16:42:13.831Z"
}
```

--------------------------------

### Create Template cURL Request

Source: https://docs.useplunk.com/api-reference/templates/createTemplate.md

Example of how to create a template using the cURL command-line tool.

```bash
curl -X POST 'https://next-api.useplunk.com/templates' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"string","subject":"string","body":"string","from":"user@example.com"}'
```

--------------------------------

### Campaign Created Response Example

Source: https://docs.useplunk.com/api-reference/campaigns/createCampaign.md

JSON response returned upon successful creation of a campaign.

```json
{
  "success": false,
  "data": {
    "id": "string",
    "name": "string",
    "description": "string",
    "subject": "string",
    "body": "string",
    "from": "user@example.com",
    "fromName": "string",
    "replyTo": "user@example.com",
    "type": "TRANSACTIONAL",
    "status": "DRAFT",
    "audienceType": "ALL",
    "audienceCondition": {
      "logic": "AND",
      "groups": [
        {
          "filters": [
            {
              "field": "string",
              "operator": "equals"
            }
          ]
        }
      ]
    },
    "segmentId": "string",
    "scheduledFor": "2026-08-10T16:42:13.830Z",
    "totalRecipients": 0,
    "sentCount": 0,
    "deliveredCount": 0,
    "openedCount": 0,
    "clickedCount": 0,
    "bouncedCount": 0,
    "projectId": "string",
    "sentAt": "2026-08-10T16:42:13.830Z",
    "createdAt": "2026-08-10T16:42:13.830Z",
    "updatedAt": "2026-08-10T16:42:13.830Z"
  }
}
```

--------------------------------

### Request body example

Source: https://docs.useplunk.com/api-reference/contacts/createContact.md

The minimum required JSON payload to create or update a contact.

```json
{
  "email": "user@example.com"
}
```

--------------------------------

### Get Contact Request

Source: https://docs.useplunk.com/api-reference/contacts/getContact.md

Example cURL command to retrieve a contact by ID.

```bash
curl -X GET 'https://next-api.useplunk.com/contacts/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

--------------------------------

### List contacts request example

Source: https://docs.useplunk.com/api-reference/contacts/listContacts.md

A cURL command to fetch contacts using an API key for authentication.

```bash
curl -X GET 'https://next-api.useplunk.com/contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

--------------------------------

### Email Send Response Example

Source: https://docs.useplunk.com/openapi.json

Successful response structure for an email send request.

```json
{"success":true,"data":{"emails":[{"contact":{"id":"cnt_abc123","email":"user@example.com"},"email":"ac32f08e-c6b9-45d3-9824-a73dff1e3bbf"}],"timestamp":"2025-01-15T10:30:00.000Z"}}
```

--------------------------------

### GET /users/@me/projects

Source: https://docs.useplunk.com/api-reference/overview.md

Lists all projects associated with the currently authenticated user.

```APIDOC
## GET /users/@me/projects

### Description
List the user's projects.

### Method
GET

### Endpoint
/users/@me/projects

### Response
#### Success Response (200)
- **projects** (array) - A list of projects belonging to the user.
  - **id** (string) - The project's unique identifier.
  - **name** (string) - The name of the project.
```

--------------------------------

### GET /templates/:id/usage

Source: https://docs.useplunk.com/concepts/templates.md

Lists all references to a specific template, including campaigns and workflow steps.

```APIDOC
## GET /templates/:id/usage

### Description
Lists every campaign, workflow step, and other reference that points at this template. Use this to answer "what breaks if I change this template?" or to find leftover references before deletion.

### Method
GET

### Endpoint
/templates/:id/usage

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the template to check.
```

--------------------------------

### Update contact request body example

Source: https://docs.useplunk.com/api-reference/contacts/updateContact.md

Example JSON payload for updating a contact's email, subscription status, and clearing a data field.

```json
{
  "email": "user@example.com",
  "subscribed": false,
  "data": null
}
```

--------------------------------

### Create Campaign Request Body Example

Source: https://docs.useplunk.com/api-reference/campaigns/createCampaign.md

Minimal JSON structure required to create a new campaign with an audience type of ALL.

```json
{
  "name": "string",
  "subject": "string",
  "body": "string",
  "from": "user@example.com",
  "audienceType": "ALL"
}
```

--------------------------------

### GET /config

Source: https://docs.useplunk.com/api-reference/overview.md

Retrieves public feature flags and configuration settings, indicating which integrations are enabled.

```APIDOC
## GET /config

### Description
Public, no-auth feature flags — which integrations are enabled (OAuth providers, billing, S3, SMTP, …).

### Method
GET

### Endpoint
/config

### Response
#### Success Response (200)
- **integrations** (object) - An object detailing enabled integrations.
  - **oauthProviders** (array) - List of enabled OAuth providers.
  - **billing** (boolean) - Whether billing is enabled.
  - **s3** (boolean) - Whether S3 integration is enabled.
  - **smtp** (boolean) - Whether SMTP integration is enabled.
```

--------------------------------

### GET /campaigns

Source: https://docs.useplunk.com/api-reference/campaigns/listCampaigns.md

Retrieves a list of campaigns with pagination support.

```APIDOC
## GET /campaigns

### Description
Retrieve a paginated list of campaigns for the project.

### Method
GET

### Endpoint
/campaigns

### Response
#### Success Response (200)
- **data** (array<object>) - List of campaign objects
- **page** (integer) - Current page number
- **pageSize** (integer) - Number of items per page
- **total** (integer) - Total campaigns matching the filters
- **totalPages** (integer) - Total number of pages

#### Response Example
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "subject": "string",
      "body": "string",
      "from": "user@example.com",
      "fromName": "string",
      "replyTo": "user@example.com",
      "type": "TRANSACTIONAL",
      "status": "DRAFT",
      "audienceType": "ALL",
      "audienceCondition": {
        "logic": "AND",
        "groups": [
          {
            "filters": [
              {
                "field": "string",
                "operator": "equals"
              }
            ]
          }
        ]
      },
      "segmentId": "string",
      "scheduledFor": "2026-08-10T16:42:13.831Z",
      "totalRecipients": 0,
      "sentCount": 0,
      "deliveredCount": 0,
      "openedCount": 0,
      "clickedCount": 0,
      "bouncedCount": 0,
      "projectId": "string",
      "sentAt": "2026-08-10T16:42:13.831Z",
      "createdAt": "2026-08-10T16:42:13.831Z",
      "updatedAt": "2026-08-10T16:42:13.831Z"
    }
  ],
  "page": 0,
  "pageSize": 0,
  "total": 0,
  "totalPages": 0
}
```

--------------------------------

### GET /projects/:id/security

Source: https://docs.useplunk.com/api-reference/overview.md

Retrieves the security state for a single project.

```APIDOC
## GET /projects/:id/security

### Description
Security state for a single project.

### Method
GET

### Endpoint
/projects/:id/security

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **securityStatus** (string) - The security status of the project (e.g., "secure", "at_risk").
```

--------------------------------

### Confirmation Email Template

Source: https://docs.useplunk.com/recipes/waitlist.md

Example of a marketing email template for a waitlist, using {{variable}} placeholders for personalization.

```text
Subject: You're on the list, {{firstName}}

Hi {{firstName}}, thanks for joining the {{product}} waitlist.
We'll let you know as soon as your spot opens up.
```

--------------------------------

### GET /activity/types

Source: https://docs.useplunk.com/api-reference/overview.md

List the distinct types of activity recorded within the project.

```APIDOC
## GET /activity/types

### Description
Distinct activity types in the project.

### Method
GET

### Endpoint
/activity/types
```

--------------------------------

### GET /templates

Source: https://docs.useplunk.com/api-reference/templates/listTemplates.md

Retrieves a paginated list of email templates from the Plunk API.

```APIDOC
## GET /templates

### Description
Get a paginated list of email templates. This endpoint uses offset pagination (`page` / `pageSize`).

### Method
GET

### Endpoint
https://next-api.useplunk.com/templates

### Parameters
#### Query Parameters
- **page** (integer) - Optional - 1-based page number.
- **pageSize** (integer) - Optional - Items per page.
- **type** (enum) - Optional - Filter by template type ("TRANSACTIONAL" | "MARKETING" | "HEADLESS").
- **search** (string) - Optional - Case-insensitive match on name, description, or subject.
- **sort** (enum) - Optional - Column to sort by ("name" | "createdAt" | "updatedAt").
- **dir** (enum) - Optional - Sort direction ("asc" | "desc").

### Response
#### Success Response (200)
- **data** (array<object>) - List of templates.
- **total** (integer) - Total templates matching the filters.
- **page** (integer) - Current page number.
- **pageSize** (integer) - Items per page.
- **totalPages** (integer) - Total number of pages.

#### Response Example
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "subject": "string",
      "body": "string",
      "from": "user@example.com",
      "fromName": "string",
      "replyTo": "user@example.com",
      "type": "TRANSACTIONAL",
      "projectId": "string",
      "createdAt": "2026-08-10T16:42:13.859Z",
      "updatedAt": "2026-08-10T16:42:13.859Z"
    }
  ],
  "total": 0,
  "page": 0,
  "pageSize": 0,
  "totalPages": 0
}
```

--------------------------------

### Start Workflow Execution with Initial Context

Source: https://docs.useplunk.com/concepts/workflows.md

Initiate a new workflow execution. You can provide an initial context object to parameterize variables for this specific execution, which is useful for data not stored on the contact.

```bash
POST /workflows/:id/executions
{
  "context": {
    "couponCode": "SUMMER2024",
    "referrerName": "Jane Doe"
  }
}
```

--------------------------------

### GET /auth/oauth-config

Source: https://docs.useplunk.com/api-reference/overview.md

Retrieves information about the configured OAuth providers available for authentication.

```APIDOC
## GET /auth/oauth-config

### Description
Which OAuth providers are configured.

### Method
GET

### Endpoint
/auth/oauth-config

### Response
#### Success Response (200)
- **providers** (array) - A list of configured OAuth providers.
  - **name** (string) - The name of the OAuth provider (e.g., "google", "github").
  - **clientId** (string) - The client ID for the OAuth provider.
```

--------------------------------

### Email verification response examples

Source: https://docs.useplunk.com/api-reference/public-api/verifyEmail.md

JSON response structures for successful verification and error scenarios.

```json
{
  "success": false,
  "data": {
    "email": "user@example.com",
    "valid": false,
    "isDisposable": false,
    "isAlias": false,
    "isTypo": false,
    "isPlusAddressed": false,
    "isPersonalEmail": false,
    "domainExists": false,
    "hasWebsite": false,
    "hasMxRecords": false,
    "reasons": [
      "string"
    ]
  }
}
```

```json
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "statusCode": 0,
    "requestId": "string",
    "errors": [
      {
        "field": "string",
        "message": "string",
        "code": "string",
        "received": null
      }
    ],
    "details": null,
    "suggestion": "string"
  },
  "timestamp": "2026-08-10T16:42:13.860Z"
}
```

--------------------------------

### GET /domains/project/:projectId

Source: https://docs.useplunk.com/api-reference/overview.md

List domains configured for a project. This includes both verified and pending domains.

```APIDOC
## GET /domains/project/:projectId

### Description
List domains configured for a project (verified and pending).

### Method
GET

### Endpoint
/domains/project/:projectId

### Parameters
#### Path Parameters
- **projectId** (string) - Required - The ID of the project to list domains for.
```

--------------------------------

### GET /campaigns

Source: https://docs.useplunk.com/api-reference/campaigns/listCampaigns.md

Retrieves a list of all campaigns. Requires an API key in the Authorization header.

```APIDOC
## GET https://next-api.useplunk.com/campaigns

### Description
Retrieves a list of all campaigns associated with the authenticated account.

### Method
GET

### Endpoint
https://next-api.useplunk.com/campaigns

### Request Example
curl -X GET 'https://next-api.useplunk.com/campaigns' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

--------------------------------

### Create Segment cURL Request

Source: https://docs.useplunk.com/api-reference/segments/createSegment.md

Example command to create a segment using the Plunk API.

```bash
curl -X POST 'https://next-api.useplunk.com/segments' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"string"}'
```

--------------------------------

### Track Event Request Body Example

Source: https://docs.useplunk.com/api-reference/public-api/trackEvent.md

A minimal JSON payload for tracking an event for a specific contact.

```json
{
  "email": "user@example.com",
  "event": "string"
}
```

--------------------------------

### Webhook Security Header Example

Source: https://docs.useplunk.com/guides/webhooks.md

Configure a secret header on the webhook step to verify the authenticity of incoming webhook requests. This is preferred over IP allowlisting.

```json
// Webhook step → Headers
{
  "Authorization": "Bearer your-shared-secret"
}
```

--------------------------------

### GET /users/@me/projects/:id/billing-limits

Source: https://docs.useplunk.com/api-reference/overview.md

Retrieves the per-category billing limits configured for a specific project.

```APIDOC
## GET /users/@me/projects/:id/billing-limits

### Description
Read per-category billing caps.

### Method
GET

### Endpoint
/users/@me/projects/:id/billing-limits

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the project to retrieve billing limits for.

### Response
#### Success Response (200)
- **limits** (object) - An object containing billing limits per category.
  - **categoryName** (object) - Details for a specific billing category.
    - **limit** (number) - The billing limit amount.
    - **unit** (string) - The unit of the limit (e.g., "requests", "GB").
```

--------------------------------

### Sending an Idempotency-Key

Source: https://docs.useplunk.com/guides/idempotency.md

Examples of how to include the Idempotency-Key header in API requests using cURL, JavaScript, and Python.

```bash
curl -X POST https://api.useplunk.com/v1/send \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Idempotency-Key: receipt-order-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Your receipt",
    "body": "<p>Thanks for your order!</p>"
  }'
```

```javascript
await fetch('https://api.useplunk.com/v1/send', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_your_secret_key',
    'Idempotency-Key': 'receipt-order-1234',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: 'customer@example.com',
    subject: 'Your receipt',
    body: '<p>Thanks for your order!</p>',
  }),
});
```

```python
import requests

requests.post(
    "https://api.useplunk.com/v1/send",
    headers={
        "Authorization": "Bearer sk_your_secret_key",
        "Idempotency-Key": "receipt-order-1234",
    },
    json={
        "to": "customer@example.com",
        "subject": "Your receipt",
        "body": "<p>Thanks for your order!</p>",
    },
)
```

--------------------------------

### Cursor-Based Pagination Request

Source: https://docs.useplunk.com/api-reference/overview.md

Use cursor-based pagination for list endpoints by including the 'limit' and 'cursor' parameters in your GET request.

```bash
GET /contacts?limit=100&cursor=abc123
```

--------------------------------

### Email verification cURL request

Source: https://docs.useplunk.com/api-reference/public-api/verifyEmail.md

Example of how to call the verify endpoint using cURL with an API key.

```bash
curl -X POST 'https://next-api.useplunk.com/v1/verify' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com"}'
```

--------------------------------

### Example: Engaged users on Pro plan

Source: https://docs.useplunk.com/guides/segment-filters.md

This snippet demonstrates how to filter for subscribed Pro-plan users who have engaged with emails recently but not too recently. It uses a combination of 'equals', 'triggeredWithin', and 'notTriggeredWithin' operators.

```json
{
  "logic": "AND",
  "groups": [
    {
      "filters": [
        { "field": "subscribed", "operator": "equals", "value": true },
        { "field": "data.plan",  "operator": "equals", "value": "pro" }
      ]
    },
    {
      "filters": [],
      "conditions": {
        "logic": "OR",
        "groups": [
          { "filters": [{ "field": "email.opened",  "operator": "triggeredWithin", "value": 14, "unit": "days" }] },
          { "filters": [{ "field": "email.clicked", "operator": "triggeredWithin", "value": 14, "unit": "days" }] }
        ]
      }
    },
    {
      "filters": [
        { "field": "email.clicked", "operator": "notTriggeredWithin", "value": 30, "unit": "days" }
      ]
    }
  ]
}
```

--------------------------------

### Create Contact and Track Signup Event

Source: https://docs.useplunk.com/recipes/double-opt-in.md

Use cURL to create a contact with 'subscribed: false' and then track a 'signup.pending' event to initiate the confirmation workflow. Ensure both calls use your secret API key.

```bash
curl https://next-api.useplunk.com/contacts \
  -H "Authorization: Bearer sk_your_secret_key" \
  -d '{ "email": "ada@example.com", "subscribed": false, "data": { "firstName": "Ada" } }'
```

```bash
curl https://next-api.useplunk.com/v1/track \
  -H "Authorization: Bearer sk_your_secret_key" \
  -d '{ "event": "signup.pending", "email": "ada@example.com", "subscribed": false }'
```

--------------------------------

### GET /analytics/campaign-stats

Source: https://docs.useplunk.com/api-reference/overview.md

Get a detailed campaign-level breakdown of analytics.

```APIDOC
## GET /analytics/campaign-stats

### Description
Campaign-level breakdown.

### Method
GET

### Endpoint
/analytics/campaign-stats
```

--------------------------------

### GET /domains/:id/verify

Source: https://docs.useplunk.com/api-reference/overview.md

Force a verification check for a specific domain. This check runs immediately, otherwise, it's performed every 5 minutes in the background.

```APIDOC
## GET /domains/:id/verify

### Description
Force a verification check now (otherwise checked every 5 minutes in the background).

### Method
GET

### Endpoint
/domains/:id/verify

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the domain to verify.
```

--------------------------------

### List Contacts Endpoint Definition

Source: https://docs.useplunk.com/openapi.json

Describes the GET /contacts endpoint, including query parameters for pagination, searching, filtering, and sorting.

```json
{"get":{"tags":["Contacts"],"summary":"List contacts","description":"Get a paginated list of contacts with cursor-based pagination.","operationId":"listContacts","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Case-insensitive substring match on email."},{"name":"subscribed","in":"query","schema":{"type":"boolean"},"description":"Filter by subscription state. Omit to return both subscribed and unsubscribed contacts."},{"name":"sort","in":"query","schema":{"type":"string","enum":["email","createdAt"],"default":"createdAt"},"description":"Column to sort by. Unrecognised values fall back to `createdAt`."},{"$ref":"#/components/parameters/SortDirection"}],"responses":{"200":{"description":"List of contacts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"cursor":{"type":"string","nullable":true,"description":"Cursor for the next page. Pass this back as the `cursor` query parameter to fetch the next page."},"hasMore":{"type":"boolean"},"total":{"type":"integer","description":"Total count.
```

--------------------------------

### Webhook Body with Contact and Event Data

Source: https://docs.useplunk.com/guides/webhooks.md

Example of a custom webhook request body that includes contact email, plan, and event referrer. Variables are interpolated.

```json
{
  "email": "{{email}}",
  "plan": "{{plan}}",
  "referrer": "{{event.referrer}}"
}
```

--------------------------------

### POST /auth/signup

Source: https://docs.useplunk.com/api-reference/overview.md

Allows new users to sign up. This endpoint is subject to the `DISABLE_SIGNUPS` configuration, which may prevent new signups.

```APIDOC
## POST /auth/signup

### Description
Sign up a new user (subject to `DISABLE_SIGNUPS`).

### Method
POST

### Endpoint
/auth/signup

### Parameters
#### Request Body
- **email** (string) - Required - The email address for the new user.
- **password** (string) - Required - The password for the new user.
- **name** (string) - Optional - The name of the new user.

### Response
#### Success Response (201)
- **message** (string) - Confirmation message of successful signup.
```

--------------------------------

### GET /contacts/:id

Source: https://docs.useplunk.com/api-reference/overview.md

Get a single contact by their ID.

```APIDOC
## GET /contacts/:id

### Description
Get a single contact by their ID.

### Method
GET

### Endpoint
/contacts/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the contact.
```

--------------------------------

### Verify Email Request Body

Source: https://docs.useplunk.com/openapi.json

Defines the JSON structure for the verifyEmail operation, including examples for valid, typo-prone, and disposable email addresses.

```json
{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Email address to verify"}}},"examples":{"validEmail":{"summary":"Valid email address","value":{"email":"user@gmail.com"}},"typoEmail":{"summary":"Email with potential typo","value":{"email":"user@gmial.com"}},"disposableEmail":{"summary":"Disposable email address","value":{"email":"user@tempmail.com"}}}}}}
```

--------------------------------

### GET /activity/stats

Source: https://docs.useplunk.com/api-reference/overview.md

Get aggregated counts for various activity metrics, suitable for dashboard display.

```APIDOC
## GET /activity/stats

### Description
Aggregated counts for dashboard charts.

### Method
GET

### Endpoint
/activity/stats
```

--------------------------------

### POST /users/@me/projects

Source: https://docs.useplunk.com/api-reference/overview.md

Creates a new project for the currently authenticated user.

```APIDOC
## POST /users/@me/projects

### Description
Create a project.

### Method
POST

### Endpoint
/users/@me/projects

### Parameters
#### Request Body
- **name** (string) - Required - The name of the new project.

### Response
#### Success Response (201)
- **id** (string) - The unique identifier of the newly created project.
- **name** (string) - The name of the project.
```

--------------------------------

### Handle Case Statements

Source: https://docs.useplunk.com/guides/template-language.md

Use case/when blocks to handle multiple specific plan scenarios efficiently.

```html
{% case plan %}
  {% when 'pro' %}<p>Here's 20% off your renewal.</p>
  {% when 'free' %}<p>Upgrade now and save 20%.</p>
  {% else %}<p>Thanks for being with us.</p>
{% endcase %}
```

--------------------------------

### Build Custom Docker Image

Source: https://docs.useplunk.com/self-hosting/docker.md

Build a custom Docker image for Plunk from source. Tag the image as 'plunk:custom' for use in your deployment.

```bash
docker build -t plunk:custom .
```

--------------------------------

### GET /users/@me

Source: https://docs.useplunk.com/api-reference/overview.md

Retrieves information about the currently authenticated user.

```APIDOC
## GET /users/@me

### Description
Get the current user.

### Method
GET

### Endpoint
/users/@me

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the user.
- **email** (string) - The email address of the user.
- **name** (string) - The name of the user.
```

--------------------------------

### GET /analytics/top-events

Source: https://docs.useplunk.com/api-reference/overview.md

List the most frequent custom event names.

```APIDOC
## GET /analytics/top-events

### Description
Most frequent custom event names.

### Method
GET

### Endpoint
/analytics/top-events
```

--------------------------------

### Create Campaign via cURL

Source: https://docs.useplunk.com/api-reference/campaigns/createCampaign.md

Sends a POST request to the campaigns endpoint to initialize a new campaign.

```bash
curl -X POST 'https://next-api.useplunk.com/campaigns' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"string","subject":"string","body":"string","from":"user@example.com","audienceType":"ALL"}'
```

--------------------------------

### GET /auth/logout

Source: https://docs.useplunk.com/api-reference/overview.md

Clears the authentication cookie, effectively logging the user out.

```APIDOC
## GET /auth/logout

### Description
Clear the auth cookie.

### Method
GET

### Endpoint
/auth/logout

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of successful logout.
```

--------------------------------

### GET /analytics/top-campaigns

Source: https://docs.useplunk.com/api-reference/overview.md

Identify top-performing campaigns based on specified metrics.

```APIDOC
## GET /analytics/top-campaigns

### Description
Top-performing campaigns by metric.

### Method
GET

### Endpoint
/analytics/top-campaigns
```

--------------------------------

### GET /projects/:id/members

Source: https://docs.useplunk.com/api-reference/overview.md

Retrieves the list of team members for a specific project.

```APIDOC
## GET /projects/:id/members

### Description
Project team members.

### Method
GET

### Endpoint
/projects/:id/members

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **members** (array) - A list of project members.
  - **userId** (string) - The ID of the member.
  - **role** (string) - The role of the member in the project (e.g., "admin", "developer").
```

--------------------------------

### POST /domains

Source: https://docs.useplunk.com/api-reference/overview.md

Add a domain for verification. The response will include the necessary DNS records that need to be added to your domain's configuration.

```APIDOC
## POST /domains

### Description
Add a domain for verification. Returns the DNS records you need to add.

### Method
POST

### Endpoint
/domains

### Response
#### Success Response (200)
- **dnsRecords** (array) - An array of DNS records required for domain verification.
```

--------------------------------

### GET /analytics/timeseries

Source: https://docs.useplunk.com/api-reference/overview.md

Retrieve time-series data for email sends, opens, and clicks.

```APIDOC
## GET /analytics/timeseries

### Description
Email send / open / click time-series.

### Method
GET

### Endpoint
/analytics/timeseries
```

--------------------------------

### GET /activity/upcoming

Source: https://docs.useplunk.com/api-reference/overview.md

View upcoming scheduled sends and currently active executions.

```APIDOC
## GET /activity/upcoming

### Description
Upcoming scheduled sends and active executions.

### Method
GET

### Endpoint
/activity/upcoming
```

--------------------------------

### Import Accordion Components

Source: https://docs.useplunk.com/guides/receiving-emails.md

Imports necessary Accordion components from 'fumadocs-ui' for displaying collapsible content.

```javascript
import {Accordion, Accordions} from 'fumadocs-ui/components/accordion';
```

--------------------------------

### POST /campaigns

Source: https://docs.useplunk.com/api-reference/campaigns/createCampaign.md

Create a new email campaign. Campaigns are created as DRAFT; use POST /campaigns/{id}/send to send or schedule one.

```APIDOC
## POST /campaigns

### Description
Create a new email campaign. Campaigns are created as DRAFT; use POST /campaigns/{id}/send to send or schedule one. The sender domain must already be verified for this project.

### Method
POST

### Endpoint
https://next-api.useplunk.com/campaigns

### Parameters
#### Request Body
- **name** (string) - Required - Campaign name
- **description** (string) - Optional - Campaign description
- **subject** (string) - Required - Email subject line
- **body** (string) - Required - HTML email body
- **from** (string) - Required - Sender email address (must be from verified domain)
- **fromName** (string) - Optional - Sender name
- **replyTo** (string) - Optional - Reply-to email address
- **type** (enum) - Optional - Content type of the campaign email (TRANSACTIONAL, MARKETING, HEADLESS). Defaults to MARKETING.
- **audienceType** (enum) - Required - Target audience type (ALL, SEGMENT, FILTERED)
- **segmentId** (string) - Optional - Segment ID. Required when audienceType is SEGMENT.
- **audienceCondition** (object) - Optional - Audience filter tree. Required when audienceType is FILTERED.

### Request Example
{
  "name": "string",
  "subject": "string",
  "body": "string",
  "from": "user@example.com",
  "audienceType": "ALL"
}

### Response
#### Success Response (201)
- **success** (boolean) - Success status
- **data** (object) - Campaign details object

#### Response Example
{
  "success": false,
  "data": {
    "id": "string",
    "name": "string",
    "description": "string",
    "subject": "string",
    "body": "string",
    "from": "user@example.com",
    "fromName": "string",
    "replyTo": "user@example.com",
    "type": "TRANSACTIONAL",
    "status": "DRAFT",
    "audienceType": "ALL",
    "audienceCondition": {
      "logic": "AND",
      "groups": [
        {
          "filters": [
            {
              "field": "string",
              "operator": "equals"
            }
          ]
        }
      ]
    },
    "segmentId": "string",
    "scheduledFor": "2026-08-10T16:42:13.830Z",
    "totalRecipients": 0,
    "sentCount": 0,
    "deliveredCount": 0,
    "openedCount": 0,
    "clickedCount": 0,
    "bouncedCount": 0,
    "projectId": "string",
    "sentAt": "2026-08-10T16:42:13.830Z",
    "createdAt": "2026-08-10T16:42:13.830Z",
    "updatedAt": "2026-08-10T16:42:13.830Z"
  }
}
```

--------------------------------

### Implement logic with Liquid conditionals and loops

Source: https://docs.useplunk.com/concepts/templates.md

Use case statements for branching logic and for loops to iterate over arrays like cart items.

```html
{% case plan %}
  {% when 'pro' %}<p>Here's 20% off your renewal.</p>
  {% when 'free' %}<p>Upgrade and save 20%.</p>
  {% else %}<p>Thanks for being with us.</p>
{% endcase %}

<ul>
  {% for item in cartItems %}
    <li>{{item.name}} — {{item.price | times: quantity | round: 2}}</li>
  {% endfor %}
</ul>
```

--------------------------------

### GET /contacts/import/:jobId

Source: https://docs.useplunk.com/api-reference/overview.md

Poll the status of a CSV import job using its `jobId`.

```APIDOC
## GET /contacts/import/:jobId

### Description
Poll the status of a CSV import job using its `jobId`.

### Method
GET

### Endpoint
/contacts/import/:jobId

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The ID of the import job.
```

--------------------------------

### Inspect all custom fields

Source: https://docs.useplunk.com/guides/custom-fields.md

Returns a list of all standard and custom fields with their inferred types and coverage percentages.

```json
{
  "fields": [
    { "field": "email",        "type": "string",  "isCustom": false, "coverage": 1.0 },
    { "field": "data.plan",    "type": "string",  "isCustom": true,  "coverage": 0.62 },
    { "field": "data.signupDate", "type": "date",  "isCustom": true,  "coverage": 0.95 }
  ]
}
```

--------------------------------

### POST /templates

Source: https://docs.useplunk.com/api-reference/templates/createTemplate.md

Creates a new email template. The 'from' address must belong to a domain verified for the project.

```APIDOC
## POST /templates

### Description
Create a new email template. The 'from' field is required and its domain must already be verified for this project.

### Method
POST

### Endpoint
https://next-api.useplunk.com/templates

### Request Body
- **name** (string) - Required - Internal name for the template.
- **description** (string) - Optional - Internal note.
- **subject** (string) - Required
- **body** (string) - Required - HTML body with {{variable}} placeholders.
- **from** (string) - Required - Sender email address.
- **fromName** (string) - Optional - Sender display name.
- **replyTo** (string) - Optional - Reply-to email address.
- **type** (enum) - Optional - TRANSACTIONAL, MARKETING, or HEADLESS.

### Request Example
{
  "name": "string",
  "subject": "string",
  "body": "string",
  "from": "user@example.com"
}

### Response
#### Success Response (201)
- **id** (string) - Template ID
- **name** (string) - Template name
- **description** (string) - Template description
- **subject** (string) - Template subject
- **body** (string) - HTML content
- **from** (string) - Sender address
- **fromName** (string) - Sender display name
- **replyTo** (string) - Reply-to address
- **type** (enum) - Template type
- **projectId** (string) - Project ID
- **createdAt** (string) - Creation timestamp
- **updatedAt** (string) - Update timestamp

#### Response Example
{
  "id": "string",
  "name": "string",
  "description": "string",
  "subject": "string",
  "body": "string",
  "from": "user@example.com",
  "fromName": "string",
  "replyTo": "user@example.com",
  "type": "TRANSACTIONAL",
  "projectId": "string",
  "createdAt": "2026-08-10T16:42:13.857Z",
  "updatedAt": "2026-08-10T16:42:13.857Z"
}
```

--------------------------------

### GET /campaigns

Source: https://docs.useplunk.com/api-reference/campaigns/listCampaigns.md

Retrieves a paginated list of email campaigns with optional filtering and sorting parameters.

```APIDOC
## GET /campaigns

### Description
Get a paginated list of email campaigns. This endpoint uses offset pagination (page / pageSize).

### Method
GET

### Endpoint
https://next-api.useplunk.com/campaigns

### Parameters
#### Query Parameters
- **page** (integer) - Optional - 1-based page number.
- **pageSize** (integer) - Optional - Items per page.
- **status** (enum) - Optional - Filter by campaign status ("DRAFT" | "SCHEDULED" | "SENDING" | "SENT" | "CANCELLED").
- **search** (string) - Optional - Case-insensitive match on name, subject, or sender address.
- **sort** (enum) - Optional - Column to sort by ("name" | "createdAt" | "updatedAt").
- **dir** (enum) - Optional - Sort direction ("asc" | "desc").
```

--------------------------------

### Minimal .env Configuration

Source: https://docs.useplunk.com/self-hosting/docker.md

Configure essential environment variables for Plunk deployment, including JWT secret, database password, domain names, and AWS SES settings. Ensure domains point to your server and use a secure password.

```bash
# Required
JWT_SECRET="$(openssl rand -base64 32)"
DB_PASSWORD="your-secure-password"

# Domains (point these to your server)
API_DOMAIN="api.yourdomain.com"
DASHBOARD_DOMAIN="app.yourdomain.com"
LANDING_DOMAIN="www.yourdomain.com"
WIKI_DOMAIN="docs.yourdomain.com"
USE_HTTPS="true"

# AWS SES
AWS_SES_REGION="us-east-1"
AWS_SES_ACCESS_KEY_ID="your-key"
AWS_SES_SECRET_ACCESS_KEY="your-secret"
SES_CONFIGURATION_SET="plunk-tracking"
```

--------------------------------

### POST /users/@me/projects/:id/checkout

Source: https://docs.useplunk.com/api-reference/overview.md

Creates a Stripe Checkout session for the specified project, likely for payment or subscription purposes.

```APIDOC
## POST /users/@me/projects/:id/checkout

### Description
Create a Stripe Checkout session.

### Method
POST

### Endpoint
/users/@me/projects/:id/checkout

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the project for which to create a checkout session.

### Response
#### Success Response (200)
- **checkoutUrl** (string) - The URL for the Stripe Checkout session.
```

--------------------------------

### GET /segments

Source: https://docs.useplunk.com/api-reference/segments/listSegments.md

Retrieves all audience segments for the project. The response is a bare array of segment objects.

```APIDOC
## GET /segments

### Description
Get all audience segments for the project, newest first. This endpoint is not paginated — it returns a bare array of every segment.

### Method
GET

### Endpoint
https://next-api.useplunk.com/segments

### Response
#### Success Response (200)
- **items** (array) - List of segment objects
  - **id** (string) - Segment ID
  - **name** (string) - Segment name
  - **description** (string) - Segment description
  - **type** (enum) - DYNAMIC or STATIC
  - **condition** (object) - Filter condition for DYNAMIC segments
  - **trackMembership** (boolean) - Whether to emit entry/exit events
  - **memberCount** (integer) - Cached member count
  - **projectId** (string) - Project ID
  - **createdAt** (string) - Creation timestamp
  - **updatedAt** (string) - Last update timestamp

#### Response Example
[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "type": "DYNAMIC",
    "condition": {
      "logic": "AND",
      "groups": [
        {
          "filters": [
            {
              "field": "string",
              "operator": "equals"
            }
          ]
        }
      ]
    },
    "trackMembership": false,
    "memberCount": 0,
    "projectId": "string",
    "createdAt": "2026-08-10T16:42:13.859Z",
    "updatedAt": "2026-08-10T16:42:13.859Z"
  }
]
```

--------------------------------

### GET /users/@me/projects/:id/billing-invoices

Source: https://docs.useplunk.com/api-reference/overview.md

Retrieves a list of Stripe invoices associated with a specific project.

```APIDOC
## GET /users/@me/projects/:id/billing-invoices

### Description
Stripe invoices for the project.

### Method
GET

### Endpoint
/users/@me/projects/:id/billing-invoices

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the project to retrieve invoices for.

### Response
#### Success Response (200)
- **invoices** (array) - A list of Stripe invoices.
  - **invoiceId** (string) - The ID of the invoice.
  - **date** (string) - The date the invoice was issued.
  - **amount** (number) - The total amount of the invoice.
  - **status** (string) - The status of the invoice (e.g., "paid", "unpaid").
```

--------------------------------

### POST /campaigns

Source: https://docs.useplunk.com/api-reference/campaigns/createCampaign.md

Creates a new campaign with the specified name, subject, body, sender, and audience type.

```APIDOC
## POST https://next-api.useplunk.com/campaigns

### Description
Creates a new email campaign.

### Method
POST

### Endpoint
https://next-api.useplunk.com/campaigns

### Request Body
- **name** (string) - Required - The name of the campaign
- **subject** (string) - Required - The email subject line
- **body** (string) - Required - The email content
- **from** (string) - Required - The sender email address
- **audienceType** (string) - Required - The target audience type (e.g., ALL)

### Request Example
{
  "name": "string",
  "subject": "string",
  "body": "string",
  "from": "user@example.com",
  "audienceType": "ALL"
}
```
Tokens:
Raw