Query campaigns curl -u 'username:password' 'https://listmonk.mysite.com/api/campaigns' \ -G \ -d 'page=1' \ -d 'status=running' \ -d 'query=newsletter'
Retrieves a paginated list of campaigns.
Authentication: RequiredPermission: campaigns:get_all or campaigns:getQuery Parameters Search term to filter campaigns by name
Filter by status (can be specified multiple times): draft, scheduled, running, paused, finished, cancelled
Filter by tag (can be specified multiple times)
order_by
string
default: "created_at"
Field to order by
If true, excludes campaign body from response
Response Array of campaign objects Campaign type: regular or optin
Campaign body (HTML/text)
Original body source (for visual campaigns)
Plain text alternative body
Scheduled send time (null for immediate)
Status: draft, scheduled, running, paused, finished, cancelled
Content type: richtext, html, markdown, plain, visual
Messenger backend: email or SMTP name
Target lists with IDs and names
When campaign started sending
Total number of emails to send
Get campaign curl -u 'username:password' 'https://listmonk.mysite.com/api/campaigns/1'
Retrieves a single campaign by ID.
Authentication: RequiredPermission: campaigns:get_all or campaigns:getPath Parameters Query Parameters If true, excludes body from response
Create campaign curl -u 'username:password' 'https://listmonk.mysite.com/api/campaigns' \ -H 'Content-Type: application/json' \ -d '{ "name": "Monthly Newsletter", "subject": "Newsletter for {{ .Subscriber.FirstName }}", "lists": [1, 2], "type": "regular", "content_type": "richtext", "body": "<p>Hello {{ .Subscriber.FirstName }}!</p>", "altbody": "Hello!", "from_email": "[email protected] ", "messenger": "email", "template_id": 1, "tags": ["newsletter"], "send_at": "2024-12-01T10:00:00Z" }'
Creates a new campaign in draft status.
Authentication: RequiredPermission: campaigns:manage_all or campaigns:manageRequest Body Campaign name (max 2000 characters)
Email subject line (supports template variables)
Array of list IDs to send to
Campaign type: regular or optin
Content type: richtext, html, markdown, plain, visual
From email address (defaults to system setting)
Plain text alternative body
ISO 8601 timestamp for scheduled sending (null for immediate)
Custom email headers (array of objects with key-value pairs)
Array of media IDs to attach
Update campaign curl -u 'username:password' -X PUT 'https://listmonk.mysite.com/api/campaigns/1' \ -H 'Content-Type: application/json' \ -d '{ "name": "Updated Newsletter", "subject": "New Subject", "body": "<p>Updated content</p>" }'
Updates a campaign. Only campaigns in draft, scheduled, or paused status can be updated.
Authentication: RequiredPermission: campaigns:manage_all or campaigns:managePath Parameters Request Body Same fields as create campaign. Only provided fields will be updated.
Update campaign status PUT /api/campaigns/:id/status
curl -u 'username:password' -X PUT 'https://listmonk.mysite.com/api/campaigns/1/status' \ -H 'Content-Type: application/json' \ -d '{"status": "running"}'
Changes a campaign’s status to start, pause, or cancel it.
Authentication: RequiredPermission: campaigns:manage_all or campaigns:managePath Parameters Request Body New status:
running: Start sending the campaignpaused: Pause a running campaignscheduled: Schedule a draft campaigncancelled: Cancel a campaign Update campaign archive settings PUT /api/campaigns/:id/archive
curl -u 'username:password' -X PUT 'https://listmonk.mysite.com/api/campaigns/1/archive' \ -H 'Content-Type: application/json' \ -d '{ "archive": true, "archive_template_id": 1, "archive_slug": "monthly-newsletter-2024-01", "archive_meta": {"public": true} }'
Configures campaign archiving for public viewing.
Authentication: RequiredPermission: campaigns:manage_all or campaigns:managePath Parameters Request Body Template ID for archive page
Custom URL slug for archive page
Custom metadata for archive
Delete campaign DELETE /api/campaigns/:id
curl -u 'username:password' -X DELETE 'https://listmonk.mysite.com/api/campaigns/1'
Deletes a campaign. Only draft and scheduled campaigns can be deleted.
Authentication: RequiredPermission: campaigns:manage_all or campaigns:managePath Parameters Delete campaigns (bulk) curl -u 'username:password' -X DELETE 'https://listmonk.mysite.com/api/campaigns?id=1&id=2'
Deletes multiple campaigns.
Authentication: RequiredPermission: campaigns:manage_all or campaigns:manageQuery Parameters Campaign ID (can be specified multiple times)
Get running campaign stats GET /api/campaigns/running/stats
curl -u 'username:password' 'https://listmonk.mysite.com/api/campaigns/running/stats'
Retrieves real-time statistics for currently running campaigns.
Authentication: RequiredPermission: campaigns:get_all or campaigns:getResponse Array of campaign stats with send rates Current send rate (per minute)
Average send rate since start
Preview campaign GET /api/campaigns/:id/preview
POST /api/campaigns/:id/preview
curl -u 'username:password' 'https://listmonk.mysite.com/api/campaigns/1/preview'
Previews campaign content with rendered template.
Authentication: RequiredPermission: campaigns:get_all or campaigns:getPath Parameters Request Body (POST only) Convert campaign content POST /api/campaigns/:id/content
curl -u 'username:password' -X POST 'https://listmonk.mysite.com/api/campaigns/1/content' \ -H 'Content-Type: application/json' \ -d '{ "body": "# Markdown Content\n\nHello!", "from": "markdown", "to": "html" }'
Converts campaign content between formats (e.g., Markdown to HTML).
Authentication: RequiredPermission: campaigns:manage_all or campaigns:managePath Parameters Request Body Target format: html or richtext
Test campaign POST /api/campaigns/:id/test
curl -u 'username:password' -X POST 'https://listmonk.mysite.com/api/campaigns/1/test' \ -H 'Content-Type: application/json' \ -d '{ "subscribers": ["[email protected] ", "[email protected] "], "name": "Test Campaign", "subject": "Test Subject", "body": "<p>Test body</p>" }'
Sends test emails to specified addresses.
Authentication: RequiredPermission: campaigns:manage_all or campaigns:managePath Parameters Request Body Array of subscriber email addresses to send test to
Get campaign analytics GET /api/campaigns/analytics/:type
curl -u 'username:password' 'https://listmonk.mysite.com/api/campaigns/analytics/views' \ -G \ -d 'id=1' \ -d 'id=2' \ -d 'from=2024-01-01T00:00:00Z' \ -d 'to=2024-12-31T23:59:59Z'
Retrieves campaign analytics data.
Authentication: RequiredPermission: campaigns:get_analyticsPath Parameters Analytics type: views, clicks, or links
Query Parameters Campaign ID (can be specified multiple times)
Response Returns analytics data with timestamps and counts for the specified period. 