curl -u 'username:password' 'https://listmonk.mysite.com/api/media' \
-G \
-d 'page=1' \
-d 'per_page=50'
Permission: media:get
Query Parameters
Page number for pagination
Number of results per page
Search term to filter media by filename
Response
Array of media objects
Thumbnail URL (for images)
MIME type (e.g., “image/png”, “image/jpeg”)
Metadata including width and height for images
Storage provider (e.g., “filesystem”, “s3”)
Total number of media files
curl -u 'username:password' 'https://listmonk.mysite.com/api/media/1'
Permission: media:get
Path Parameters
Response
Returns a single media object with the same structure as the query endpoint
curl -u 'username:password' 'https://listmonk.mysite.com/api/media' \
-F '[email protected]'
Permission: media:manage
Request Body
File to upload (multipart/form-data)
Response
Returns the uploaded media object
Public URL to access the file
Thumbnail URL (for images)
Metadata (width/height for images)
Supported File Types
By default, the following file types are supported:
- Images:
.png, .jpg, .jpeg, .gif, .svg
File type restrictions can be configured in the listmonk settings. Check with your administrator for allowed file types.
File Processing
- Images (PNG, JPG, GIF): Automatically generates a thumbnail (250px width)
- SVG: Uses the original file as thumbnail
- Other files: No thumbnail generated
Example: Upload Image
curl -u 'username:password' 'https://listmonk.mysite.com/api/media' \
-F 'file=@/path/to/newsletter-header.png'
{
"data": {
"id": 1,
"uuid": "5e6e3e8f-6b5a-4c8d-9c3a-1f2e3c4b5a6d",
"filename": "newsletter-header.png",
"url": "https://listmonk.mysite.com/uploads/newsletter-header.png",
"thumb_url": "https://listmonk.mysite.com/uploads/thumb_newsletter-header.png",
"content_type": "image/png",
"meta": {
"width": 800,
"height": 600
},
"provider": "filesystem",
"created_at": "2024-01-15T10:30:00Z"
}
}
curl -u 'username:password' -X DELETE 'https://listmonk.mysite.com/api/media/1'
Permission: media:manage
Path Parameters
Response
Returns true on successful deletion
Deleting media files that are referenced in campaigns will break image links in those campaigns. Ensure media files are not in use before deleting.
Insert Media in Campaign Body
Once uploaded, media can be referenced in campaign HTML:
<img src="https://listmonk.mysite.com/uploads/newsletter-header.png"
alt="Newsletter Header" />
curl -u 'username:password' 'https://listmonk.mysite.com/api/campaigns' \
-H 'Content-Type: application/json' \
-d '{
"name": "Newsletter",
"subject": "Monthly Update",
"lists": [1],
"body": "<p>Newsletter content</p>",
"media": [1, 2, 3]
}'
Storage Providers
listmonk supports multiple storage providers for media files:
Filesystem (Default)
Files are stored on the server’s local filesystem in the uploads directory.
Amazon S3
Files are stored in an S3-compatible object storage.
Configuration
Storage provider settings are configured in the listmonk settings. Contact your administrator for provider-specific configurations. 