Skip to content

API / Campaigns

Method Endpoint Description
GET /api/campaigns Gets all campaigns.
GET /api/campaigns/:campaign_id Gets a single campaign.
GET /api/campaigns/:campaign_id/preview Gets the HTML preview of a campaign body.
GET /api/campaigns/running/stats Gets the stats of a given set of campaigns.
POST /api/campaigns Creates a new campaign.
POST /api/campaigns/:campaign_id/test Posts campaign message to arbitrary subscribers for testing.
PUT /api/campaigns/:campaign_id Modifies a campaign.
PUT /api/campaigns/:campaign_id/status Start / pause / cancel / schedule a campaign.
DELETE /api/campaigns/:campaign_id Deletes a campaign.

GET /api/campaigns

Gets all campaigns.

Example Request
 curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns?page=1&per_page=100'
Parameters

Name | Type | Required/Optional | Description --------|--------------------|-------------|---------------------|--------------------- query | string | Optional | Optional string to search a list by name. order_by | string | Optional | Field to sort results by. name|status|created_at|updated_at order | string | Optional | ASC|DESCSort by ascending or descending order. page | number | Optional | Page number for paginated results. per_page | number | Optional | Results to return per page. Setting this to all skips pagination and returns all results.

Example Response
{
    "data": {
        "results": [
            {
                "id": 1,
                "created_at": "2020-03-14T17:36:41.29451+01:00",
                "updated_at": "2020-03-14T17:36:41.29451+01:00",
                "CampaignID": 0,
                "views": 0,
                "clicks": 0,
                "lists": [
                    {
                        "id": 1,
                        "name": "Default list"
                    }
                ],
                "started_at": null,
                "to_send": 0,
                "sent": 0,
                "uuid": "57702beb-6fae-4355-a324-c2fd5b59a549",
                "type": "regular",
                "name": "Test campaign",
                "subject": "Welcome to listmonk",
                "from_email": "No Reply <noreply@yoursite.com>",
                "body": "<h3>Hi {{ .Subscriber.FirstName }}!</h3>\n\t\t\tThis is a test e-mail campaign. Your second name is {{ .Subscriber.LastName }} and you are from {{ .Subscriber.Attribs.city }}.",
                "send_at": "2020-03-15T17:36:41.293233+01:00",
                "status": "draft",
                "content_type": "richtext",
                "tags": [
                    "test-campaign"
                ],
                "template_id": 1,
                "messenger": "email"
            }
        ],
        "query": "",
        "total": 1,
        "per_page": 20,
        "page": 1
    }
}

GET /api/campaigns/:campaign_id

Gets a single campaign.

Parameters
Name Parameter Type Data Type Required/Optional Description
campaign_id Path Parameter Number Required The id value of the campaign you want to get.
Example Request
curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/1'
Example Response
{
    "data": {
        "id": 1,
        "created_at": "2020-03-14T17:36:41.29451+01:00",
        "updated_at": "2020-03-14T17:36:41.29451+01:00",
        "CampaignID": 0,
        "views": 0,
        "clicks": 0,
        "lists": [
            {
                "id": 1,
                "name": "Default list"
            }
        ],
        "started_at": null,
        "to_send": 0,
        "sent": 0,
        "uuid": "57702beb-6fae-4355-a324-c2fd5b59a549",
        "type": "regular",
        "name": "Test campaign",
        "subject": "Welcome to listmonk",
        "from_email": "No Reply <noreply@yoursite.com>",
        "body": "<h3>Hi {{ .Subscriber.FirstName }}!</h3>\n\t\t\tThis is a test e-mail campaign. Your second name is {{ .Subscriber.LastName }} and you are from {{ .Subscriber.Attribs.city }}.",
        "send_at": "2020-03-15T17:36:41.293233+01:00",
        "status": "draft",
        "content_type": "richtext",
        "tags": [
            "test-campaign"
        ],
        "template_id": 1,
        "messenger": "email"
    }
}

GET /api/campaigns/:campaign_id/preview

Gets the html preview of a campaign body.

Parameters
Name Parameter Type Data Type Required/Optional Description
campaign_id Path Parameter Number Required The id value of the campaign to be previewed.
Example Request
curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/1/preview'
Example Response
<h3>Hi John!</h3>
This is a test e-mail campaign. Your second name is Doe and you are from Bengaluru.

GET /api/campaigns/running/stats

Gets the running stat of a given set of campaigns.

Parameters
Name Parameter Type Data Type Required/Optional Description
campaign_id Query Parameters Number Required The id values of the campaigns whose stat you want to get.
Example Request
curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/running/stats?campaign_id=1'
Example Response
{
    "data": []
}

POST /api/campaigns

Creates a new campaign.

Parameters

Name Data type Required/Optional Description
name String Required Name of the campaign.
subject String Required (E-mail) subject of the campaign.
lists []Number Required Array of list IDs to send the campaign to.
from_email String Optional From e-mail to show on the campaign e-mails. If left empty, the default value from settings is used.
type String Required regular or optin campaign.
content_type String Required richtext, html, markdown, plain
body String Required Campaign content body.
altbody String Optional Alternate plain text body for HTML (and richtext) e-mails.
send_at String Optional A timestamp to schedule the campaign at. Eg: 2021-12-25T06:00:00 (YYYY-MM-DDTHH:MM:SS)
messenger String Optional email or a custom messenger defined in the settings. If left empty, email is used.
template_id Number Optional ID of the template to use. If left empty, the default template is used.
tags []String Optional Array of string tags to mark the campaign.

Example request

curl -u "username:password" 'http://localhost:9000/api/campaigns' -X POST -H 'Content-Type: application/json;charset=utf-8' --data-raw '{"name":"Test campaign","subject":"Hello, world","lists":[1],"from_email":"listmonk <noreply@listmonk.yoursite.com>","content_type":"richtext","messenger":"email","type":"regular","tags":["test"],"template_id":1}'

Example response

{
    "data": {
        "id": 1,
        "created_at": "2021-12-27T11:50:23.333485Z",
        "updated_at": "2021-12-27T11:50:23.333485Z",
        "views": 0,
        "clicks": 0,
        "bounces": 0,
        "lists": [{
            "id": 1,
            "name": "Default list"
        }],
        "started_at": null,
        "to_send": 1,
        "sent": 0,
        "uuid": "90c889cc-3728-4064-bbcb-5c1c446633b3",
        "type": "regular",
        "name": "Test campaign",
        "subject": "Hello, world",
        "from_email": "listmonk \u003cnoreply@listmonk.yoursite.com\u003e",
        "body": "",
        "altbody": null,
        "send_at": null,
        "status": "draft",
        "content_type": "richtext",
        "tags": ["test"],
        "template_id": 1,
        "messenger": "email"
    }
}

PUT /api/campaigns/:campaign_id/status

Modifies a campaign status to start, pause, cancel, or schedule a campaign.

Parameters
Name Parameter Type Data Type Required/Optional Description
campaign_id Path Parameter Number Required The id value of the campaign whose status is to be modified.
status Request Body String Required scheduled, running, paused, cancelled.
Note:
  • Only "scheduled" campaigns can be saved as "draft".
  • Only "draft" campaigns can be "scheduled".
  • Only "paused" campaigns and "draft" campaigns can be started.
  • Only "running" campaigns can be "cancelled" and "paused".
Example Request
curl -u "username:password" -X PUT 'http://localhost:9000/api/campaigns/1/status' \
--header 'Content-Type: application/json' \
--data-raw '{"status":"scheduled"}'
Example Response
{
    "data": {
        "id": 1,
        "created_at": "2020-03-14T17:36:41.29451+01:00",
        "updated_at": "2020-04-08T19:35:17.331867+01:00",
        "CampaignID": 0,
        "views": 0,
        "clicks": 0,
        "lists": [
            {
                "id": 1,
                "name": "Default list"
            }
        ],
        "started_at": null,
        "to_send": 0,
        "sent": 0,
        "uuid": "57702beb-6fae-4355-a324-c2fd5b59a549",
        "type": "regular",
        "name": "Test campaign",
        "subject": "Welcome to listmonk",
        "from_email": "No Reply <noreply@yoursite.com>",
        "body": "<h3>Hi {{ .Subscriber.FirstName }}!</h3>\n\t\t\tThis is a test e-mail campaign. Your second name is {{ .Subscriber.LastName }} and you are from {{ .Subscriber.Attribs.city }}.",
        "send_at": "2020-03-15T17:36:41.293233+01:00",
        "status": "scheduled",
        "content_type": "richtext",
        "tags": [
            "test-campaign"
        ],
        "template_id": 1,
        "messenger": "email"
    }
}

DELETE /api/campaigns/:campaign_id

Deletes a campaign, only scheduled campaigns that have not yet been started can be deleted.

Parameters
Name Parameter Type Data Type Required/Optional Description
campaign_id Path Parameter Number Required The id value of the campaign you want to delete.
Example Request
curl -u "username:password" -X DELETE 'http://localhost:9000/api/campaigns/34'
Example Response
{
    "data": true
}