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/:campaign_id/test Posts campaign message to arbitrary subscribers for testing.
POST /api/campaigns Creates a new campaign.
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'

To skip pagination and retrieve all records, pass per_page=all.

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 <[email protected]>",
                "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 <[email protected]>",
        "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": []
}

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: multipart/form-data; boundary=--------------------------047372886665819311890787' \
--form '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 <[email protected]>",
        "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
}