API Overview

Introduction

The listmonk API is a RESTful HTTP API that provides programmatic access to all core functionality. It enables you to manage subscribers, lists, campaigns, templates, and more from external applications. Base URL: http://your-listmonk-instance:9000/api

Key Features

RESTful Design

Standard HTTP methods (GET, POST, PUT, DELETE) for intuitive API interactions

JSON Responses

All responses are in JSON format with consistent structure

Role-Based Access

Fine-grained permissions system for secure API access

Pagination Support

Efficient data retrieval with pagination for large datasets

Response Format

All successful API responses follow this structure:

{
  "data": {
    // Response data here
  }
}

For list endpoints with pagination:

{
  "data": {
    "results": [...],
    "total": 150,
    "per_page": 20,
    "page": 1
  }
}

Error Handling

Error responses include an HTTP status code and a JSON body with error details:

{
  "message": "Error description",
  "data": null
}

Common HTTP Status Codes

Status Code	Description
`200`	Success
`201`	Created successfully
`400`	Bad request - invalid parameters
`401`	Unauthorized - authentication required
`403`	Forbidden - insufficient permissions
`404`	Resource not found
`500`	Internal server error

Content Types

The API accepts and returns JSON data: Request Header:

Content-Type: application/json

For file uploads (e.g., media, import):

Content-Type: multipart/form-data

Pagination

List endpoints support pagination with query parameters:

page - Page number (default: 1)
per_page - Results per page (default: 20, max: 100)

Example:

GET /api/subscribers?page=2&per_page=50

Filtering and Searching

Many endpoints support filtering with query parameters: Subscribers:

query - Search by name or email
list_id - Filter by list membership
subscription_status - Filter by status (confirmed, unconfirmed, unsubscribed)

Lists:

query - Search by name
type - Filter by type (public, private, temporary)
tags - Filter by tags

Campaigns:

query - Search by name
status - Filter by status (draft, running, scheduled, paused, cancelled, finished)

Example:

GET /api/subscribers?query=john&list_id=5&subscription_status=confirmed

Rate Limiting

listmonk does not enforce rate limiting by default, but you should implement rate limiting in your application or reverse proxy to prevent abuse.

Consider implementing:

Per-IP rate limits
Per-user rate limits
Transactional email rate limits based on your SMTP provider’s limits

Health Check

Test API availability with the health endpoint:

curl

curl http://localhost:9000/api/health

Response:

{
  "data": true
}

Quick Start Example

Here’s a complete example of creating a subscriber and adding them to a list:

Authenticate

Obtain your API credentials from the dashboard. See Authentication for details.

Create a Subscriber

curl -u 'username:password' -X POST http://localhost:9000/api/subscribers \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "name": "John Doe",
    "status": "enabled",
    "lists": [1],
    "preconfirm_subscriptions": true
  }'

Verify Creation

curl -u 'username:password' http://localhost:9000/api/subscribers/1

API Resources

Subscribers

Manage subscriber data and subscriptions

Lists

Create and manage mailing lists

Campaigns

Create, schedule, and manage email campaigns

Templates

Manage email templates

Media

Upload and manage media files

Bounces

Handle email bounces and complaints

Transactional

Send one-off transactional emails

Import

Bulk import subscribers

Best Practices

Use Appropriate HTTP Methods

GET: Retrieve data (read-only, no side effects)
POST: Create new resources
PUT: Update existing resources
DELETE: Remove resources

Handle Errors Gracefully

Always check the HTTP status code and parse error messages from the response body. Implement retry logic with exponential backoff for transient errors (5xx codes).

Respect Pagination

When fetching large datasets, use pagination to avoid timeouts and excessive memory usage. Process data in chunks rather than fetching everything at once.

Validate Input

Validate email addresses, ensure required fields are present, and sanitize user input before sending to the API.

Secure Your API Keys

Store credentials securely using environment variables or secrets management systems. Never commit API keys to version control.

Endpoints

API Overview

Introduction

Key Features

RESTful Design

JSON Responses

Role-Based Access

Pagination Support

Response Format

Error Handling

Common HTTP Status Codes

Content Types

Filtering and Searching

Rate Limiting

Health Check

Quick Start Example

API Resources

Subscribers

Lists

Campaigns

Templates

Media

Bounces

Transactional

Import

Best Practices

Next Steps

Authentication

Subscriber API

Build docs developers (and LLMs) love

API Overview

Endpoints

​Introduction

​Key Features

RESTful Design

JSON Responses

Role-Based Access

Pagination Support

​Response Format

​Error Handling

​Common HTTP Status Codes

​Content Types

​Pagination

​Filtering and Searching

​Rate Limiting

​Health Check

​Quick Start Example

​API Resources

Subscribers

Lists

Campaigns

Templates

Media

Bounces

Transactional

Import

​Best Practices

​Next Steps

Authentication

Subscriber API

Build docs developers (and LLMs) love

Introduction

Key Features

Response Format

Error Handling

Common HTTP Status Codes

Content Types

Pagination

Filtering and Searching

Rate Limiting

Health Check

Quick Start Example

API Resources

Best Practices

Next Steps