Skip to main content
Campaigns are one-time or scheduled bulk emails sent to a defined audience. You can target all subscribed contacts, a saved segment, or a dynamically-filtered audience.
All campaign endpoints require a secret key (sk_*). The from address must belong to a verified domain on your project.

​
List campaigns

GET /campaigns Returns a paginated list of campaigns for the authenticated project.

​
Query parameters

​
page
number
default:"1"
Page number (1-indexed).
​
pageSize
number
default:"20"
Number of campaigns per page.
​
status
string
Filter by status. One of DRAFT, SCHEDULED, SENDING, SENT, or CANCELLED.

​
Response

​
campaigns
array
Array of campaign objects.
​
page
integer
Current page.
​
pageSize
integer
Items per page.
​
total
integer
Total matching campaigns.
​
totalPages
integer
Total pages.
Example
curl --request GET \
  --url 'https://next-api.useplunk.com/campaigns?status=DRAFT' \
  --header 'Authorization: Bearer sk_live_yourkey'

​
Create campaign

POST /campaigns Creates a new campaign in DRAFT status.

​
Body parameters

​
name
string
required
Internal campaign name.
​
subject
string
required
Email subject line.
​
body
string
required
HTML email body.
​
from
string
required
Sender email address. Must be from a verified domain on your project.
​
audienceType
string
required
Who to send this campaign to. One of:
  • ALL — all subscribed contacts in the project
  • SEGMENT — contacts in a specific saved segment (requires segmentId)
  • FILTERED — contacts matching inline filter conditions (requires audienceCondition)
​
description
string
Optional internal description.
​
fromName
string
Sender display name.
​
replyTo
string
Reply-to email address.
​
segmentId
string
Required when audienceType is SEGMENT. The ID of the segment to target.
​
audienceCondition
object
Required when audienceType is FILTERED. A FilterCondition object defining the dynamic audience rules. See the Segments documentation for the condition schema.

​
Response

​
success
boolean
true on success.
​
data
object
Example
curl --request POST \
  --url https://next-api.useplunk.com/campaigns \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "March Newsletter",
    "subject": "What'\''s new this month",
    "body": "<h1>March Updates</h1><p>Here'\''s what we shipped this month...</p>",
    "from": "[email protected]",
    "fromName": "My App",
    "audienceType": "ALL"
  }'

​
Get campaign

GET /campaigns/:id Retrieves a single campaign by ID.

​
Path parameters

​
id
string
required
The campaign ID.
Example
curl --request GET \
  --url https://next-api.useplunk.com/campaigns/clx_cmp_abc123 \
  --header 'Authorization: Bearer sk_live_yourkey'

​
Update campaign

PUT /campaigns/:id Updates a campaign. Only campaigns in DRAFT or SCHEDULED status can be updated.

​
Path parameters

​
id
string
required
The campaign ID.

​
Body parameters

​
name
string
Campaign name.
​
description
string
Campaign description.
​
subject
string
Email subject line.
​
body
string
HTML email body.
​
from
string
Sender email (must be a verified domain).
​
fromName
string
Sender display name.
​
replyTo
string
Reply-to email address.
​
audienceType
string
Audience type: ALL, SEGMENT, or FILTERED.
​
segmentId
string
Segment ID (required when changing audienceType to SEGMENT).
​
audienceCondition
object
Audience filter conditions (required when changing audienceType to FILTERED).
Example
curl --request PUT \
  --url https://next-api.useplunk.com/campaigns/clx_cmp_abc123 \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{
    "subject": "What'\''s new in March 🚀",
    "audienceType": "SEGMENT",
    "segmentId": "clx_seg_xyz789"
  }'

​
Send or schedule campaign

POST /campaigns/:id/send Sends the campaign immediately or schedules it for future delivery.

​
Path parameters

​
id
string
required
The campaign ID.

​
Body parameters

​
scheduledFor
string
ISO 8601 timestamp for when to send the campaign. Omit this field (or set it to null) to send immediately.

​
Response

​
success
boolean
true on success.
​
data
object
Updated campaign object.
​
message
string
Human-readable status message.
curl --request POST \
  --url https://next-api.useplunk.com/campaigns/clx_cmp_abc123/send \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{}'

​
Cancel campaign

POST /campaigns/:id/cancel Cancels a campaign that is in SCHEDULED status.

​
Path parameters

​
id
string
required
The campaign ID.
Example
curl --request POST \
  --url https://next-api.useplunk.com/campaigns/clx_cmp_abc123/cancel \
  --header 'Authorization: Bearer sk_live_yourkey'

​
Send test email

POST /campaigns/:id/test Sends a test email for the campaign to a specified address so you can preview it before sending to the full audience.

​
Path parameters

​
id
string
required
The campaign ID.

​
Body parameters

​
email
string
required
Email address to send the test to.
Example
curl --request POST \
  --url https://next-api.useplunk.com/campaigns/clx_cmp_abc123/test \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "[email protected]"
  }'

​
Get campaign stats

GET /campaigns/:id/stats Returns delivery and engagement analytics for a sent campaign.

​
Path parameters

​
id
string
required
The campaign ID.

​
Response

​
success
boolean
true on success.
​
data
object
Example
curl --request GET \
  --url https://next-api.useplunk.com/campaigns/clx_cmp_abc123/stats \
  --header 'Authorization: Bearer sk_live_yourkey'
200
{
  "success": true,
  "data": {
    "delivered": 4821,
    "opens": 1203,
    "clicks": 347,
    "bounces": 12,
    "complaints": 2
  }
}

​
Delete campaign

DELETE /campaigns/:id Permanently deletes a campaign.
Only campaigns in DRAFT or CANCELLED status can be deleted. You cannot delete a campaign that is SENDING or SENT.

​
Path parameters

​
id
string
required
The campaign ID.

​
Response

Returns { "success": true, "message": "Campaign deleted successfully" } on success.
Example
curl --request DELETE \
  --url https://next-api.useplunk.com/campaigns/clx_cmp_abc123 \
  --header 'Authorization: Bearer sk_live_yourkey'

​
Duplicate campaign

POST /campaigns/:id/duplicate Creates a copy of the campaign in DRAFT status with the same content and settings.

​
Path parameters

​
id
string
required
The campaign ID to duplicate.

​
Response

Returns the new campaign object with HTTP 201.
Example
curl --request POST \
  --url https://next-api.useplunk.com/campaigns/clx_cmp_abc123/duplicate \
  --header 'Authorization: Bearer sk_live_yourkey'

Build docs developers (and LLMs) love

Get started for freeTalk to us