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	Modifies a campaign status.
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.

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	The new status value, can be set to "draft", "scheduled", "running", "paused", "finished", "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
}