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
}

API / Campaigns¶

GET /api/campaigns¶

Example Request¶

Parameters¶

Example Response¶

GET /api/campaigns/:campaign_id¶

Parameters¶

Example Request¶

Example Response¶

GET /api/campaigns/:campaign_id/preview¶

Parameters¶

Example Request¶

Example Response¶

GET /api/campaigns/running/stats¶

Parameters¶

Example Request¶

Example Response¶

POST /api/campaigns¶

Parameters¶

Example request¶

Example response¶

PUT /api/campaigns/:campaign_id/status¶

Parameters¶

Note:¶

Example Request¶

Example Response¶

DELETE /api/campaigns/:campaign_id¶

Parameters¶

Example Request¶

Example Response¶

`GET` /api/campaigns¶

`GET` /api/campaigns/:`campaign_id`¶

`GET` /api/campaigns/:`campaign_id`/preview¶

`GET` /api/campaigns/running/stats¶

`POST` /api/campaigns¶

`PUT` /api/campaigns/:`campaign_id`/status¶

`DELETE` /api/campaigns/:`campaign_id`¶