listmonk

https://listmonk.app/docs/
Admin
listmonk is a self-hosted, high-performance one-way mailing list and newsletter manager that runs as...
Tokens:70,828
Snippets:476
Trust Score:9.8
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### GET /api/bounces - Example Request

Source: https://listmonk.app/docs/apis/bounces

Retrieve bounce records with optional query parameters. The example uses campaign_id, page, per_page, source, order_by, and order parameters.

```bash
curl -u "api_user:token" -X GET 'http://localhost:9000/api/bounces?campaign_id=1&page=1&per_page=2' \ 
    -H 'accept: application/json' -H 'Content-Type: application/x-www-form-urlencoded' \
    --data '{"source":"demo","order_by":"created_at","order":"asc"}'

```

--------------------------------

### GET /api/campaigns/{campaign_id} - Example response

Source: https://listmonk.app/docs/apis/campaigns

Example response for the GET /api/campaigns/{campaign_id} endpoint. Shows a single campaign object with its details.

```json
{
    "data": {
        "id": 1,
        "created_at": "2020-03-14T17:36:41.29451+01:00",
        "updated_at": "2020-03-14T17:36:41.29451+01:00",
        "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 }}.",
        "body_source": null,
        "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/import/subscribers/logs - Example Response

Source: https://listmonk.app/docs/apis/import

Example JSON response containing log lines. Each line represents a processing step with a timestamp.

```json
{
    "data": "2020/04/08 21:55:20 processing 'import.csv'\n2020/04/08 21:55:21 imported finished\n"
}

```

--------------------------------

### GET /api/campaigns - Example response

Source: https://listmonk.app/docs/apis/campaigns

Example response for the GET /api/campaigns endpoint. Shows a paginated list of campaigns with fields like id, name, subject, status, and body.

```json
{
    "data": {
        "results": [
            {
                "id": 1,
                "created_at": "2020-03-14T17:36:41.29451+01:00",
                "updated_at": "2020-03-14T17:36:41.29451+01:00",
                "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 }}.",
                "body_source": null,
                "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/import/subscribers/logs - Example Request

Source: https://listmonk.app/docs/apis/import

Retrieves logs from an ongoing import. Useful for debugging or monitoring progress.

```bash
curl -u "api_user:token" -X GET 'http://localhost:9000/api/import/subscribers/logs'

```

--------------------------------

### Install listmonk using Helm chart

Source: https://listmonk.app/docs/installation

Installs listmonk on a Kubernetes cluster using the community-maintained Helm chart from the HelmForge repository, with a custom values.yaml file.

```bash
$ helm upgrade \
    --create-namespace \
    --install listmonk listmonk \
    --namespace listmonk \
    --repo https://repo.helmforge.dev \
    --values values.yaml

```

--------------------------------

### GET /api/bounces - Example Response

Source: https://listmonk.app/docs/apis/bounces

Example JSON response for the GET /api/bounces request, showing a paginated list of bounce records with subscriber and campaign details.

```json
{
  "data": {
    "results": [
      {
        "id": 839971,
        "type": "hard",
        "source": "demo",
        "meta": {
          "some": "parameter"
        },
        "created_at": "2024-08-20T23:54:22.851858Z",
        "email": "gilles.deleuze@example.app",
        "subscriber_uuid": "32ca1f3e-1a1d-42e1-af04-df0757f420f3",
        "subscriber_id": 60,
        "campaign": {
          "id": 1,
          "name": "Test campaign"
        }
      },
      {
        "id": 839725,
        "type": "hard",
        "source": "demo",
        "meta": {
          "some": "parameter"
        },
        "created_at": "2024-08-20T22:46:36.393507Z",
        "email": "gottfried.leibniz@example.app",
        "subscriber_uuid": "5911d3f4-2346-4bfc-aad2-eb319ab0e879",
        "subscriber_id": 13,
        "campaign": {
          "id": 1,
          "name": "Test campaign"
        }
      }
    ],
    "query": "",
    "total": 528,
    "per_page": 2,
    "page": 1
  }
}

```

--------------------------------

### GET /api/import/subscribers - Example Request

Source: https://listmonk.app/docs/apis/import

Retrieves the status of an ongoing import. Use this to check progress or verify no import is running.

```bash
curl -u "api_user:token" -X GET 'http://localhost:9000/api/import/subscribers'

```

--------------------------------

### GET /api/import/subscribers - Example Response

Source: https://listmonk.app/docs/apis/import

Example JSON response showing import statistics. The status field indicates the current import state (e.g., 'none' when no import is active).

```json
{
    "data": {
        "name": "",
        "total": 0,
        "imported": 0,
        "status": "none"
    }
}

```

--------------------------------

### GET /api/lists - Example Response

Source: https://listmonk.app/docs/apis/lists

JSON response for the GET /api/lists endpoint, showing a paginated list of lists with subscriber counts.

```json
{
    "data": {
        "results": [
            {
                "id": 1,
                "created_at": "2020-02-10T23:07:16.194843+01:00",
                "updated_at": "2020-03-06T22:32:01.118327+01:00",
                "uuid": "ce13e971-c2ed-4069-bd0c-240e9a9f56f9",
                "name": "Default list",
                "type": "public",
                "optin": "double",
                "status": "active",
                "tags": [
                    "test"
                ],
                "subscriber_count": 2
            },
            {
                "id": 2,
                "created_at": "2020-03-04T21:12:09.555013+01:00",
                "updated_at": "2020-03-06T22:34:46.405031+01:00",
                "uuid": "f20a2308-dfb5-4420-a56d-ecf0618a102d",
                "name": "get",
                "type": "private",
                "optin": "single",
                "status": "active",
                "tags": [],
                "subscriber_count": 0
            }
        ],
        "total": 5,
        "per_page": 20,
        "page": 1
    }
}
```

--------------------------------

### POST /api/import/subscribers - Example Response

Source: https://listmonk.app/docs/apis/import

Example JSON response showing the import parameters echoed back. Note the comments are not part of the actual response.

```json
    {
        "mode": "subscribe", // subscribe or blocklist
        "delim": ",",        // delimiter in the uploaded file
        "lists":[1],         // array of list IDs to import into
        "overwrite": true    // overwrite existing entries or skip them?
    }

```

--------------------------------

### BasicAuth Example

Source: https://listmonk.app/docs/apis/apis

Example of authenticating an API request using BasicAuth.

```APIDOC
## BasicAuth Example

### Description
Authenticate API requests using BasicAuth with the API user's username and token.

### Method
GET

### Endpoint
/api/lists

### Authentication
BasicAuth with username `api_user` and password `token`.

### Request Example
```
curl -u "api_user:token" http://localhost:9000/api/lists
```
```

--------------------------------

### GET /api/lists - Example Request

Source: https://listmonk.app/docs/apis/lists

Curl commands to retrieve lists with various filters: all lists, active lists, and archived lists with minimal data. Uses basic authentication with api_user:token.

```bash
# Get all lists
curl -u "api_user:token" -X GET 'http://localhost:9000/api/lists?page=1&per_page=100'

# Get only active lists
curl -u "api_user:token" -X GET 'http://localhost:9000/api/lists?status=active&per_page=100'

# Get archived lists with minimal data
curl -u "api_user:token" -X GET 'http://localhost:9000/api/lists?status=archived&minimal=true&per_page=all'
```

--------------------------------

### GET /api/lists/{list_id} - Example Request

Source: https://listmonk.app/docs/apis/lists

Curl command to retrieve a specific list by ID, using basic authentication.

```bash
curl -u "api_user:token" -X GET 'http://localhost:9000/api/lists/5'
```

--------------------------------

### GET /api/public/lists - Example Request

Source: https://listmonk.app/docs/apis/lists

Unauthenticated curl command to retrieve public lists for subscription forms.

```bash
curl -X GET 'http://localhost:9000/api/public/lists'
```

--------------------------------

### Authorization Token Example

Source: https://listmonk.app/docs/apis/apis

Example of authenticating an API request using an Authorization token header.

```APIDOC
## Authorization Token Example

### Description
Authenticate API requests using an Authorization token header with the format `api_user:token`.

### Method
GET

### Endpoint
/api/lists

### Authentication
Authorization header with value `token api_user:token`.

### Request Example
```
curl -H "Authorization: token api_user:token" http://localhost:9000/api/lists
```
```

--------------------------------

### GET /api/public/lists - Example Response

Source: https://listmonk.app/docs/apis/lists

JSON array of public lists with uuid and name, used for subscription forms.

```json
[
  {
    "uuid": "55e243af-80c6-4169-8d7f-bc571e0269e9",
    "name": "Opt-in list"
  }
]
```

--------------------------------

### DELETE /api/bounces - Example Request (all=true)

Source: https://listmonk.app/docs/apis/bounces

Delete all bounces by confirming with the 'all' parameter set to true. The example uses basic authentication.

```bash
curl -u 'api_username:access_token' -X DELETE 'http://localhost:9000/api/bounces?all=true'

```

--------------------------------

### GET /api/lists/{list_id} - Example Response

Source: https://listmonk.app/docs/apis/lists

JSON response for a specific list, including details like name, type, optin, status, and subscriber count.

```json
{
    "data": {
        "id": 5,
        "created_at": "2020-03-07T06:31:06.072483+01:00",
        "updated_at": "2020-03-07T06:31:06.072483+01:00",
        "uuid": "1bb246ab-7417-4cef-bddc-8fc8fc941d3a",
        "name": "Test list",
        "type": "public",
        "optin": "double",
        "status": "active",
        "tags": [],
        "subscriber_count": 0
    }
}
```

--------------------------------

### GET /api/subscribers/{subscriber_id}/bounces - Example Request

Source: https://listmonk.app/docs/apis/subscribers

Curl command to fetch bounce records for a specific subscriber.

```bash
curl -u 'api_username:access_token' 'http://localhost:9000/api/subscribers/1/bounces' 

```

--------------------------------

### GET /api/templates/{template_id}/preview - Retrieve template HTML preview

Source: https://listmonk.app/docs/apis/templates

Retrieves the HTML preview of a template using the GET /api/templates/{template_id}/preview endpoint. The template_id path parameter is required and must be a number.

```bash
curl -u "api_user:token" -X GET 'http://localhost:9000/api/templates/1/preview'

```

```html
<p>Hi there</p>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis et elit ac elit sollicitudin condimentum non a magna.
    Sed tempor mauris in facilisis vehicula. Aenean nisl urna, accumsan ac tincidunt vitae, interdum cursus massa.
    Interdum et malesuada fames ac ante ipsum primis in faucibus. Aliquam varius turpis et turpis lacinia placerat.
    Aenean id ligula a orci lacinia blandit at eu felis. Phasellus vel lobortis lacus. Suspendisse leo elit, luctus sed
    erat ut, venenatis fermentum ipsum. Donec bibendum neque quis.</p>

<h3>Sub heading</h3>
<p>Nam luctus dui non placerat mattis. Morbi non accumsan orci, vel interdum urna. Duis faucibus id nunc ut euismod.
    Curabitur et eros id erat feugiat fringilla in eget neque. Aliquam accumsan cursus eros sed faucibus.</p>

<p>Here is a link to <a href="https://listmonk.app" target="_blank">listmonk</a>.</p>

```

--------------------------------

### GET /api/subscribers/{subscriber_id} - Example Response

Source: https://listmonk.app/docs/apis/subscribers

JSON response for the subscriber retrieval request, containing subscriber details and list subscriptions.

```json
{
    "data": {
        "id": 1,
        "created_at": "2020-02-10T23:07:16.199433+01:00",
        "updated_at": "2020-02-10T23:07:16.199433+01:00",
        "uuid": "ea06b2e7-4b08-4697-bcfc-2a5c6dde8f1c",
        "email": "john@example.com",
        "name": "John Doe",
        "attribs": {
            "city": "Bengaluru",
            "good": true,
            "type": "known"
        },
        "status": "enabled",
        "lists": [
            {
                "subscription_status": "unconfirmed",
                "id": 1,
                "uuid": "ce13e971-c2ed-4069-bd0c-240e9a9f56f9",
                "name": "Default list",
                "type": "public",
                "tags": [
                    "test"
                ],
                "created_at": "2020-02-10T23:07:16.194843+01:00",
                "updated_at": "2020-02-10T23:07:16.194843+01:00"
            }
        ]
    }
}

```

--------------------------------

### GET /settings

Source: https://listmonk.app/docs/swagger/collections.yaml

Returns settings from the database. Provides the current settings object.

```APIDOC
## GET /settings

### Description
Returns settings from the database.

### Method
GET

### Endpoint
/settings

### Response
#### Success Response (200)
- **data** (Settings) - Settings object.

#### Response Example
{
  "data": {}
}
```

--------------------------------

### GET /api/templates

Source: https://listmonk.app/docs/apis/templates

Retrieves all templates from the system.

```APIDOC
## GET /api/templates

### Description
Retrieve all templates.

### Method
GET

### Endpoint
/api/templates

### Parameters
None

### Request Example
curl -u "api_user:token" -X GET 'http://localhost:9000/api/templates'

### Response
#### Success Response (200)
- **data** (array) - List of template objects
- **id** (number) - Template ID
- **created_at** (string) - Creation timestamp
- **updated_at** (string) - Last update timestamp
- **name** (string) - Template name
- **body** (string) - Template body
- **body_source** (string|null) - JSON source for visual templates
- **type** (string) - Template type
- **is_default** (boolean) - Whether template is default

#### Response Example
{
    "data": [
        {
            "id": 1,
            "created_at": "2020-03-14T17:36:41.288578+01:00",
            "updated_at": "2020-03-14T17:36:41.288578+01:00",
            "name": "Default template",
            "body": "{{ template \"content\" . }}",
            "body_source": null,
            "type": "campaign",
            "is_default": true
        }
    ]
}
```

--------------------------------

### GET /api/templates - Retrieve all templates

Source: https://listmonk.app/docs/apis/templates

Retrieves all templates using the GET /api/templates endpoint. The response contains a data array with template objects including id, timestamps, name, body, body_source, type, and is_default.

```bash
curl -u "api_user:token" -X GET 'http://localhost:9000/api/templates'

```

```json
{
    "data": [
        {
            "id": 1,
            "created_at": "2020-03-14T17:36:41.288578+01:00",
            "updated_at": "2020-03-14T17:36:41.288578+01:00",
            "name": "Default template",
            "body": "{{ template \"content\" . }}",
            "body_source": null,
            "type": "campaign",
            "is_default": true
        }
    ]
}

```

--------------------------------

### GET /media

Source: https://listmonk.app/docs/swagger/collections.yaml

Retrieves a list of uploaded media files.

```APIDOC
## [GET] /media

### Description
Retrieves a list of uploaded media files.

### Method
GET

### Endpoint
/media

### Parameters
None

### Response
#### Success Response (200)
- **data** (array) - List of media file objects.

#### Response Example
{
  "data": []
}
```

--------------------------------

### GET /templates

Source: https://listmonk.app/docs/swagger/collections.yaml

Retrieves a list of templates, optionally without the body.

```APIDOC
## [GET] /templates

### Description
Retrieves a list of templates, optionally without the body.

### Method
GET

### Endpoint
/templates

### Parameters
#### Query Parameters
- **no_body** (boolean) - Required - Boolean flag for response with/without body

### Response
#### Success Response (200)
- **data** (array) - List of template objects.

#### Response Example
{
  "data": []
}
```

--------------------------------

### GET /api/campaigns/{campaign_id}/preview

Source: https://listmonk.app/docs/apis/campaigns

Retrieve preview of a campaign.

```APIDOC
## [GET] /api/campaigns/{campaign_id}/preview

### Description
Retrieve preview of a campaign.

### Method
GET

### Endpoint
/api/campaigns/{campaign_id}/preview

### Parameters
#### Path Parameters
- **campaign_id** (number) - Required - Campaign ID.

### Response
#### Success Response (200)
- **data** (object) - The preview data.

#### Response Example
```
{
  "data": {}
}
```
```

--------------------------------

### GET /import/subscribers/logs

Source: https://listmonk.app/docs/swagger/collections.yaml

Returns the logs from an ongoing import process.

```APIDOC
## [GET] /import/subscribers/logs

### Description
Returns import logs from an ongoing import.

### Method
GET

### Endpoint
/import/subscribers/logs

### Response
#### Success Response (200)
- **data** (string) - Import statistics or logs

#### Response Example
{
  "data": "string"
}
```

--------------------------------

### GET /campaigns/{id}/preview

Source: https://listmonk.app/docs/swagger/collections.yaml

Renders the HTML preview of a campaign body.

```APIDOC
## [GET] /campaigns/{id}/preview

### Description
Renders the HTML preview of a campaign body.

### Method
GET

### Endpoint
/campaigns/{id}/preview

### Parameters
#### Path Parameters
- **id** (integer) - Required - The id value of the campaign you want to get the preview of

### Response
#### Success Response (200)
- **body** (string) - HTML Preview of requested campaign

#### Response Example
<h3>Hi John!</h3>This is a   e-mail campaign. Your second name is Doe and you are from Bengaluru
```

--------------------------------

### Download and run listmonk with Docker Compose

Source: https://listmonk.app/docs/installation

Downloads the docker-compose.yml file from the listmonk repository and starts the services in the background. After running, visit http://localhost:9000 to create the Super Admin user and login.

```bash
# Download the compose file to the current directory.
curl -LO https://github.com/knadh/listmonk/raw/master/docker-compose.yml

# Run the services in the background.
docker compose up -d

```

--------------------------------

### Bind mount data/uploads to /listmonk/uploads

Source: https://listmonk.app/docs/configuration

Bind mount example that maps './data/uploads' on the host to '/listmonk/uploads' in the container. Files will be available in '/data/uploads' on the host.

```yaml
  app:
    volumes:
      - ./data/uploads:/listmonk/uploads

```

--------------------------------

### Fetch static files with wget and tar

Source: https://listmonk.app/docs/templating

Downloads and extracts the listmonk static files to /home/ubuntu/listmonk/static. Use this command to obtain the default system templates for customization.

```bash
mkdir -p /home/ubuntu/listmonk/static ; wget -O - https://github.com/knadh/listmonk/archive/master.tar.gz | tar xz -C /home/ubuntu/listmonk/static --strip=2 "listmonk-master/static"
```

--------------------------------

### POST /api/import/subscribers - Example Request

Source: https://listmonk.app/docs/apis/import

Uploads a CSV file (optionally ZIP compressed) for bulk import. Uses multipart form data with 'params' and 'file' fields.

```bash
curl -u "api_user:token" -X POST 'http://localhost:9000/api/import/subscribers' \
  -F 'params={"mode":"subscribe", "subscription_status":"confirmed", "delim":",", "lists":[1, 2], "overwrite": true}' \
  -F "file=@/path/to/subs.csv"

```

--------------------------------

### Bind mount host path to container

Source: https://listmonk.app/docs/configuration

Generic bind mount example for media uploads. Replace the host path and container path with your own values.

```yaml
  app:
    volumes:
      - ./path/on/your/host/:/path/inside/container

```

--------------------------------

### Example response JSON

Source: https://listmonk.app/docs/apis/subscribers

Sample JSON response showing subscriber objects with lists, attributes, and pagination metadata.

```json
{
    "data": {
        "results": [
            {
                "id": 1,
                "created_at": "2020-02-10T23:07:16.199433+01:00",
                "updated_at": "2020-02-10T23:07:16.199433+01:00",
                "uuid": "ea06b2e7-4b08-4697-bcfc-2a5c6dde8f1c",
                "email": "john@example.com",
                "name": "John Doe",
                "attribs": {
                    "city": "Bengaluru",
                    "good": true,
                    "type": "known"
                },
                "status": "enabled",
                "lists": [
                    {
                        "subscription_status": "unconfirmed",
                        "id": 1,
                        "uuid": "ce13e971-c2ed-4069-bd0c-240e9a9f56f9",
                        "name": "Default list",
                        "type": "public",
                        "tags": [
                            "test"
                        ],
                        "created_at": "2020-02-10T23:07:16.194843+01:00",
                        "updated_at": "2020-02-10T23:07:16.194843+01:00"
                    }
                ]
            },
            {
                "id": 2,
                "created_at": "2020-02-18T21:10:17.218979+01:00",
                "updated_at": "2020-02-18T21:10:17.218979+01:00",
                "uuid": "ccf66172-f87f-4509-b7af-e8716f739860",
                "email": "quadri@example.com",
                "name": "quadri",
                "attribs": {},
                "status": "enabled",
                "lists": [
                    {
                        "subscription_status": "unconfirmed",
                        "id": 1,
                        "uuid": "ce13e971-c2ed-4069-bd0c-240e9a9f56f9",
                        "name": "Default list",
                        "type": "public",
                        "tags": [
                            "test"
                        ],
                        "created_at": "2020-02-10T23:07:16.194843+01:00",
                        "updated_at": "2020-02-10T23:07:16.194843+01:00"
                    }
                ]
            },
            {
                "id": 3,
                "created_at": "2020-02-19T19:10:49.36636+01:00",
                "updated_at": "2020-02-19T19:10:49.36636+01:00",
                "uuid": "5d940585-3cc8-4add-b9c5-76efba3c6edd",
                "email": "sugar@example.com",
                "name": "sugar",
                "attribs": {},
                "status": "enabled",
                "lists": []
            }
        ],
        "query": "",
        "total": 3,
        "per_page": 20,
        "page": 1
    }
}
```

--------------------------------

### Create list response

Source: https://listmonk.app/docs/apis/lists

Example JSON response returned after successfully creating a list. Contains the list data including id, timestamps, name, type, optin, status, tags, subscriber_count, and description.

```json
{
    "data": {
        "id": 5,
        "created_at": "2020-03-07T06:31:06.072483+01:00",
        "updated_at": "2020-03-07T06:31:06.072483+01:00",
        "uuid": "1bb246ab-7417-4cef-bddc-8fc8fc941d3a",
        "name": "Test list",
        "type": "public",
        "optin": "single",
        "status": "active",
        "tags": [],
        "subscriber_count": 0,
        "description": "This is a test list"
    }
}

```

--------------------------------

### Find a subscriber by name

Source: https://listmonk.app/docs/querying-and-segmentation

Example SQL expression to find subscribers whose name starts with John.

```APIDOC
## Find a subscriber by name

### Description
Example SQL expression to find subscribers whose name starts with John.

### SQL Expression
```sql
-- Find all subscribers whose name start with John.
subscribers.email LIKE 'John%'
```
```

--------------------------------

### POST /api/templates - Create a template

Source: https://listmonk.app/docs/apis/templates

Creates a new template using the POST /api/templates endpoint. Required parameters are name, type (campaign, campaign_visual, or tx), and body; subject is optional and only for tx type, body_source is optional for campaign_visual type.

```bash
curl -u "api_user:token" -X POST 'http://localhost:9000/api/templates' \
-H 'Content-Type: application/json' \
-d '{
    "name": "New template",
    "type": "campaign",
    "subject": "Your Weekly Newsletter",
    "body": "<h1>Header</h1><p>Content goes here</p>"
}'

```

```json
{
    "data": [
        {
            "id": 1,
            "created_at": "2020-03-14T17:36:41.288578+01:00",
            "updated_at": "2020-03-14T17:36:41.288578+01:00",
            "name": "Default template",
            "body": "{{ template \"content\" . }}",
            "body_source": null,
            "type": "campaign",
            "is_default": true
        }
    ]
}

```

--------------------------------

### Bind mount default uploads folder

Source: https://listmonk.app/docs/configuration

Bind mount example that uses the default 'uploads' folder on the host, mapping it to '/listmonk/uploads' in the container.

```yaml
  app:
    volumes:
      - ./uploads:/listmonk/uploads

```

--------------------------------

### GET /api/subscribers/{subscriber_id} - Example Request

Source: https://listmonk.app/docs/apis/subscribers

Curl command to retrieve a specific subscriber by ID. Requires authentication with an API username and access token.

```bash
curl -u 'api_username:access_token' 'http://localhost:9000/api/subscribers/1' 

```

--------------------------------

### GET /api/subscribers/{subscriber_id}/export - Example Response

Source: https://listmonk.app/docs/apis/subscribers

JSON response for the export request, containing profile, subscriptions, campaign views, and link clicks data.

```json
{
  "profile": [
    {
      "id": 1,
      "uuid": "c2cc0b31-b485-4d72-8ce8-b47081beadec",
      "email": "john@example.com",
      "name": "John Doe",
      "attribs": {
        "city": "Bengaluru",
        "good": true,
        "type": "known"
      },
      "status": "enabled",
      "created_at": "2024-07-29T11:01:31.478677+05:30",
      "updated_at": "2024-07-29T11:01:31.478677+05:30"
    }
  ],
  "subscriptions": [
    {
      "subscription_status": "unconfirmed",
      "name": "Private list",
      "type": "private",
      "created_at": "2024-07-29T11:01:31.478677+05:30"
    }
  ],
  "campaign_views": [],
  "link_clicks": []
}

```

--------------------------------

### GET /api/subscribers/{subscriber_id}/bounces - Example Response

Source: https://listmonk.app/docs/apis/subscribers

JSON response for the bounce records request, containing an array of bounce objects with type, source, meta, and campaign details.

```json
{
  "data": [
    {
      "id": 841706,
      "type": "hard",
      "source": "demo",
      "meta": {
        "some": "parameter"
      },
      "created_at": "2024-08-22T09:05:12.862877Z",
      "email": "thomas.hobbes@example.com",
      "subscriber_uuid": "137c0d83-8de6-44e2-a55f-d4238ab21969",
      "subscriber_id": 99,
      "campaign": {
        "id": 2,
        "name": "Welcome to listmonk"
      }
    },
    {
      "id": 841680,
      "type": "hard",
      "source": "demo",
      "meta": {
        "some": "parameter"
      },
      "created_at": "2024-08-19T14:07:53.141917Z",
      "email": "thomas.hobbes@example.com",
      "subscriber_uuid": "137c0d83-8de6-44e2-a55f-d4238ab21969",
      "subscriber_id": 99,
      "campaign": {
        "id": 1,
        "name": "Test campaign"
      }
    }
  ]
}

```

--------------------------------

### POST /lists

Source: https://listmonk.app/docs/swagger/collections.yaml

Handles list creation.

```APIDOC
## [POST] /lists

### Description
Handles list creation.

### Method
POST

### Endpoint
/lists

### Parameters
#### Request Body
- **NewList** (object) - Required - new list info

### Response
#### Success Response (200)
- **data** (List) - Description

#### Response Example
{
  "data": {}
}
```

--------------------------------

### GET /api/subscribers/{subscriber_id}/export - Example Request

Source: https://listmonk.app/docs/apis/subscribers

Curl command to export a specific subscriber's data, including profile, list subscriptions, campaign views, and link clicks. Private list names are replaced with 'Private list'.

```bash
curl -u 'api_username:access_token' 'http://localhost:9000/api/subscribers/1/export' 

```

--------------------------------

### Custom config.toml for listmonk

Source: https://listmonk.app/docs/installation

Example configuration file for listmonk, setting the app address and database connection parameters. The database host is set to the Postgres container name from the compose file.

```toml
[app]
address = "0.0.0.0:9000"

# Database.
[db]
host = "listmonk_db" # Postgres container name in the compose file.
port = 5432
user = "listmonk"
password = "listmonk"
database = "listmonk"
ssl_mode = "disable"
max_open = 25
max_idle = 25
max_lifetime = "300s"

```

--------------------------------

### DELETE /api/bounces/{bounce_id} - Example Request

Source: https://listmonk.app/docs/apis/bounces

Delete a specific bounce record by its ID. The example deletes bounce ID 840965.

```bash
curl -u 'api_username:access_token' -X DELETE 'http://localhost:9000/api/bounces/840965'

```

--------------------------------

### POST /templates

Source: https://listmonk.app/docs/swagger/collections.yaml

Creates a new template.

```APIDOC
## [POST] /templates

### Description
Creates a new template.

### Method
POST

### Endpoint
/templates

### Parameters
#### Request Body
- **NewTemplate** (object) - Required - New template information.

### Request Example
{
  "name": "string",
  "body": "string"
}

### Response
#### Success Response (200)
- **data** (object) - The created template object.

#### Response Example
{
  "data": {}
}
```

--------------------------------

### DELETE /api/bounces - Example Response (all=true)

Source: https://listmonk.app/docs/apis/bounces

Example JSON response for deleting all bounces, returning a data field with value true.

```json
{
    "data": true
}

```

--------------------------------

### POST /campaigns

Source: https://listmonk.app/docs/swagger/collections.yaml

Creates a new campaign.

```APIDOC
## [POST] /campaigns

### Description
Creates a new campaign.

### Method
POST

### Endpoint
/campaigns

### Parameters
#### Request Body
- **CampaignRequest** (object) - Required - New campaign information.

### Request Example
{
  "CampaignRequest": {}
}

### Response
#### Success Response (200)
- **data** (CampaignUpdate) - The created campaign object.

#### Response Example
{
  "data": {}
}
```

--------------------------------

### Subscriber attributes JSON example

Source: https://listmonk.app/docs/concepts

Example of a subscriber attributes JSON map. Attributes are arbitrary properties attached to a subscriber and can be used for segmentation and inserted into e-mails.

```json
{
  "city": "Bengaluru",
  "likes_tea": true,
  "spoken_languages": ["English", "Malayalam"],
  "projects": 3,
  "stack": {
    "frameworks": ["echo", "go"],
    "languages": ["go", "python"],
    "preferred_language": "go"
  }
}
```

--------------------------------

### BasicAuth example: curl -u

Source: https://listmonk.app/docs/apis/apis

Authenticates to the listmonk API using BasicAuth with the format api_user:token. Replace api_user and token with credentials created in the admin UI (Admin -> Users).

```bash
curl -u "api_user:token" http://localhost:9000/api/lists

```

--------------------------------

### Create campaign response

Source: https://listmonk.app/docs/apis/campaigns

Example response from creating a campaign. Shows the created campaign object with fields like id, uuid, status (draft), and the associated list. The response is wrapped in a data object.

```json
{
    "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": "",
        "body_source": null,
        "altbody": null,
        "send_at": null,
        "status": "draft",
        "content_type": "richtext",
        "tags": ["test"],
        "template_id": 1,
        "messenger": "email",
        "headers": {},
        "attribs": {}
    }
}
```

--------------------------------

### GET /api/templates/{template_id} - Retrieve a template

Source: https://listmonk.app/docs/apis/templates

Retrieves a specific template by its ID using the GET /api/templates/{template_id} endpoint. The template_id path parameter is required and must be a number.

```bash
curl -u "api_user:token" -X GET 'http://localhost:9000/api/templates/1'

```

```json
{
    "data": {
        "id": 1,
        "created_at": "2020-03-14T17:36:41.288578+01:00",
        "updated_at": "2020-03-14T17:36:41.288578+01:00",
        "name": "Default template",
        "body": "{{ template \"content\" . }}",
        "body_source": null,
        "type": "campaign",
        "is_default": true
    }
}

```

--------------------------------

### Create a new list - POST /api/lists

Source: https://listmonk.app/docs/apis/lists

Creates a new list. The request requires authentication via basic auth. The response returns the created list object with its ID, timestamps, and other details.

```bash
curl -u "api_user:token" -X POST 'http://localhost:9000/api/lists'

```

--------------------------------

### DELETE /api/bounces - Example Request (multiple IDs)

Source: https://listmonk.app/docs/apis/bounces

Delete multiple bounce records by providing multiple 'id' query parameters. The example deletes three specific bounce IDs.

```bash
curl -u 'api_username:access_token' -X DELETE 'http://localhost:9000/api/bounces?id=840965&id=840168&id=840879'

```

--------------------------------

### Get running campaign stats with GET /api/campaigns/running/stats

Source: https://listmonk.app/docs/apis/campaigns

Use this curl command to retrieve stats for a running campaign by its ID. The response is a JSON object with a data array, which may be empty if no stats are available.

```bash
curl -u "api_user:token" -X GET 'http://localhost:9000/api/campaigns/running/stats?campaign_id=1'

```

```json
{
    "data": []
}

```

--------------------------------

### GET /api/subscribers

Source: https://listmonk.app/docs/apis/subscribers

Query and retrieve subscribers.

```APIDOC
## GET /api/subscribers

### Description
Query and retrieve subscribers.

### Method
GET

### Endpoint
/api/subscribers

```

--------------------------------

### Create a public subscription with JSON request

Source: https://listmonk.app/docs/apis/subscribers

Creates a public subscription using a JSON-encoded body. Requires email and list_uuids. The response is a boolean true.

```bash
curl 'http://localhost:9000/api/public/subscription' -H 'Content-Type: application/json' \
    --data '{"email":"subscriber@domain.com","name":"The Subscriber","list_uuids": ["eb420c55-4cfb-4972-92ba-c93c34ba475d", "0c554cfb-eb42-4972-92ba-c93c34ba475d"]}'
```

```json
{
  "data": true
}
```

--------------------------------

### Get campaign analytics links with GET /api/campaigns/analytics/{type}

Source: https://listmonk.app/docs/apis/campaigns

Use this curl command to fetch link click analytics for a campaign within a date range. The response includes a data array with url and count for each clicked link.

```bash
curl -u "api_user:token" -X GET 'http://localhost:9000/api/campaigns/analytics/links?id=1&from=2024-08-04T18%3A30%3A00.624Z&to=2024-08-12T18%3A29%3A00.624Z'

```

```json
{
  "data": [
    {
      "url": "https://freethebears.org",
      "count": 294
    },
    {
      "url": "https://calmcode.io",
      "count": 278
    },
    {
      "url": "https://climate.nasa.gov",
      "count": 261
    },
    {
      "url": "https://www.storybreathing.com",
      "count": 260
    }
  ]
}

```

--------------------------------

### POST /campaigns/{id}

Source: https://listmonk.app/docs/swagger/collections.yaml

Renders the HTML preview of a campaign body.

```APIDOC
## [POST] /campaigns/{id}

### Description
Renders the HTML preview of a campaign body.

### Method
POST

### Endpoint
/campaigns/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The id value of the campaign you want to get the preview of

#### Request Body
- **template_id** (integer) - Required - template id
- **content_type** (string) - Required - content type
- **body** (string) - Required - template body

### Request Example
{
  "template_id": 0,
  "content_type": "string",
  "body": "string"
}

### Response
#### Success Response (200)
- **text/html** (string) - HTML Preview of requested campaign

#### Response Example
<h3>Hi John!</h3>This is a   e-mail campaign. Your second name is Doe and you are from Bengaluru
```
Tokens:
Raw