Skip to main content

​
Base URL

https://next-api.useplunk.com

​
API groups

The Plunk API has two groups of endpoints that serve different purposes.

Public API

For use in your application code. Endpoints are versioned under /v1/.
  • POST /v1/send — send transactional email
  • POST /v1/track — track an event for a contact

Dashboard API

For managing your Plunk project. Endpoints are unversioned.Covers contacts, templates, campaigns, segments, workflows, events, and domains.
The Public API accepts both secret keys (sk_*) and public keys (pk_*), depending on the endpoint. The Dashboard API requires a secret key for all requests. See Authentication for details.

​
Request format

All requests must include the Content-Type: application/json header and send a JSON body where applicable. 
curl -X POST https://next-api.useplunk.com/v1/send \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"to": "[email protected]", "subject": "Hello", "body": "<p>Hi there</p>"}'

​
Response format

Every response from the Plunk API uses a consistent envelope, making it straightforward to check for success or handle errors without inspecting HTTP status codes alone.

​
Success

{
  "success": true,
  "data": {
    "contact": "cnt_abc123",
    "event": "evt_xyz789",
    "timestamp": "2025-11-30T10:30:00.000Z"
  }
}
List endpoints include pagination metadata alongside the items: 
{
  "success": true,
  "data": {
    "items": [],
    "nextCursor": "abc123",
    "hasMore": true,
    "total": 1000
  }
}

​
Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 422,
    "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "errors": [
      {
        "field": "email",
        "message": "Invalid email",
        "code": "invalid_string"
      }
    ],
    "suggestion": "One or more fields have incorrect types."
  },
  "timestamp": "2025-11-30T10:30:00.000Z"
}
FieldDescription
successfalse for all error responses
error.codeMachine-readable error code for programmatic handling
error.messageHuman-readable description of the error
error.statusCodeHTTP status code
error.requestIdUnique identifier for this request — include it when contacting support
error.errorsArray of field-level validation details (present on VALIDATION_ERROR only)
error.suggestionGuidance for resolving the error
timestampISO 8601 timestamp of when the error occurred
See the Error codes reference for a complete list of codes and example responses.

​
Pagination

List endpoints use cursor-based pagination. Pass limit and cursor as query parameters. 
GET /contacts?limit=50&cursor=abc123
ParameterDefaultMaximumDescription
limit20100Number of items to return
cursor——Cursor value from the previous response’s nextCursor field
When hasMore is false in the response, you have reached the last page.

​
Rate limits

LimitValue
Email sending14 emails per second (AWS SES default)
API requests1,000 requests per minute per project
Bulk operations such as campaign sends are automatically queued for background processing and do not consume your per-minute request budget. When you exceed a limit, the API returns a 429 Too Many Requests response with error code RATE_LIMIT_EXCEEDED. Implement exponential backoff before retrying.

​
What’s next

Authentication

Learn how to obtain and use your API keys.

Error codes

Complete reference for all error codes and troubleshooting guidance.

Send an email

Send your first transactional email with POST /v1/send.

Track an event

Track contact activity with POST /v1/track.

Build docs developers (and LLMs) love

Get started for freeTalk to us