High performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.
JavaScript campaigncampaign-managementemail-marketingemail-subscriptionlistmonkmailing-listnewsletternewsletter-managementnewsletter-softwareself-hostedsms-gatewaysmtptransactional-emails
openapi: 3.0.0
servers:
- description: Listmonk Developement Server
url: http://localhost:9000/api
info:
version: "1.0.0"
title: Listmonk
description: The API collection for listmonk
license:
name: AGPL-3.0 license
url: https://github.com/knadh/listmonk/blob/master/LICENSE
tags:
- name: Miscellaneous
description: Misc API
- name: Settings
description: Settings API
- name: Admin
description: Admin API
- name: Logs
description: Logs API
- name: Subscribers
description: Subscribers API
externalDocs:
url: https://listmonk.app/docs/apis/subscribers/
- name: Bounces
description: Bounce API
- name: Lists
description: Subscriber List API
externalDocs:
url: https://listmonk.app/docs/apis/lists/
- name: Import
description: Import API
externalDocs:
url: https://listmonk.app/docs/apis/lists/
- name: Campaigns
description: Campaign API
externalDocs:
url: https://listmonk.app/docs/apis/campaigns/
- name: Media
description: Media API
externalDocs:
url: https://listmonk.app/docs/apis/media/
- name: Templates
description: Templates API
externalDocs:
url: https://listmonk.app/docs/apis/templates/
- name: Transactional
description: Transactional API
externalDocs:
url: https://listmonk.app/docs/apis/transactional/
- name: Maintenance
description: Maintenance API
- name: Public
description: Listmonk Public API
paths:
/health:
get:
tags:
- Miscellaneous
description: healthcheck endpoint
operationId: getHealthCheck
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
/config:
get:
tags:
- Miscellaneous
description: returns general server config.
operationId: getServerConfig
responses:
"200":
description: A server config object
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/ServerConfig"
"/lang/{lang}":
get:
tags:
- Miscellaneous
description: returns the JSON language pack given the language code
operationId: getI18nLang
parameters:
- in: path
name: lang
required: true
description: JSON language pack required
schema:
type: string
responses:
"200":
description: requested language pack
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/LanguagePack"
/dashboard/charts:
get:
tags:
- Miscellaneous
description: returns chart data points to render on the dashboard.
operationId: getDashboardCharts
responses:
"200":
description: chart data points
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/DashboardChart"
/dashboard/counts:
get:
tags:
- Miscellaneous
description: returns stats counts to show on the dashboard
operationId: getDashboardCounts
responses:
"200":
description: stat counts
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/DashboardCount"
/settings:
get:
tags:
- Settings
description: returns settings from DB
operationId: getSettings
responses:
"200":
description: settings object
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/Settings"
put:
tags:
- Settings
description: returns updated settings from the DB.
operationId: updateSettings
requestBody:
description: updated settings field values
content:
application/json:
schema:
$ref: "#/components/schemas/Settings"
responses:
"200":
description: updated settings object
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
/settings/smtp/test:
post:
tags:
- Settings
description: test smtp settings
operationId: testSMTPSettings
requestBody:
description: updated SMTP settings field values
content:
application/json:
schema:
$ref: "#/components/schemas/SMTPTest"
responses:
"200":
description: updated SMTP test settings
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
/admin/reload:
post:
tags:
- Admin
description: restarts the app
operationId: reloadApp
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
/logs:
get:
tags:
- Logs
description: returns the log entries stored in the log buffer
operationId: getLogs
responses:
"200":
description: stored log entries
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: string
/subscribers:
get:
tags:
- Subscribers
description: returns all subscribers.
operationId: getSubscribers
parameters:
- in: query
name: page
description: Page number for paginated results.
required: false
schema:
type: integer
format: int32
- in: query
name: per_page
description: Number of items per page. Use an integer for specific page size or 'all' to retrieve all results
required: false
schema:
oneOf:
- type: integer
description: Number of items to return per page
- type: string
enum: ["all"]
description: Return all results without pagination
- in: query
name: query
description: query subscribers with an SQL expression.
required: false
schema:
type: string
- in: query
name: order_by
description: Result sorting field. Options are name, status, created_at, updated_at
required: false
schema:
type: string
enum: ["name", "status", "created_at", "updated_at"]
- in: query
name: order
description: ASC|DESC Sort by ascending or descending order.
required: false
schema:
type: string
enum: ["ASC", "DESC"]
- in: query
name: subscription_status
description: Subscription status to filter by if there are one or more list_ids.
required: false
schema:
type: string
- in: query
name: list_id
description: ID of lists to filter by. Repeat in the query for multiple values.
required: false
schema:
type: array
items:
type: integer
responses:
"200":
description: subscribers list
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
results:
type: array
items:
$ref: "#/components/schemas/Subscriber"
query:
type: string
total:
type: integer
per_page:
type: integer
page:
type: integer
post:
description: handles creation of new subscriber
operationId: createSubscriber
tags:
- Subscribers
requestBody:
description: new subscriber info
content:
application/json:
schema:
$ref: "#/components/schemas/NewSubscriber"
responses:
"200":
description: subscriber object
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/Subscriber"
delete:
description: handles subscribers deletion
operationId: deleteSubscriberByList
tags:
- Subscribers
parameters:
- in: query
name: id
required: true
description: subscriber id/s to be deleted
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
"/subscribers/{id}":
get:
description: handles the retrieval of a single subscriber by ID.
operationId: getSubscriberById
tags:
- Subscribers
parameters:
- in: path
name: id
required: true
description: The id value of the subscriber you want to get.
schema:
type: integer
responses:
"200":
description: gets a single subscriber.
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/Subscriber"
put:
description: modify subscriber data
operationId: updateSubscriberById
tags:
- Subscribers
parameters:
- in: path
name: id
required: true
description: The id of subscriber to update
schema:
type: integer
requestBody:
description: new subscriber info
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateSubscriber"
responses:
"200":
description: returns updated subscriber.
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/Subscriber"
delete:
description: handles subscriber deletion based on id
operationId: deleteSubscriberById
tags:
- Subscribers
parameters:
- in: path
name: id
required: true
description: The id value of the subscriber you want to get.
schema:
type: integer
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
/subscribers/lists:
put:
description: handles bulk addition or removal of subscribers
operationId: manageSubscriberLists
tags:
- Subscribers
requestBody:
description: The list of subscribers details to add or remove
content:
application/json:
schema:
$ref: "#/components/schemas/SubscriberQueryRequest"
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
"/subscribers/lists/{id}":
put:
description: handles bulk addition or removal of subscribers for a specified list id
operationId: manageSubscriberListById
tags:
- Subscribers
requestBody:
description: The list of subscribers to add or remove
content:
application/json:
schema:
$ref: "#/components/schemas/SubscriberQueryRequest"
parameters:
- in: path
name: id
required: true
description: The id of list you want to update
schema:
type: integer
format: int32
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
"/subscribers/blocklist":
put:
description: handles blocklisting of subscriber list
operationId: manageBlocklistBySubscriberList
tags:
- Subscribers
requestBody:
description: The list of subscribers to blocklist
content:
application/json:
schema:
$ref: "#/components/schemas/SubscriberQueryRequest"
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
"/subscribers/{id}/blocklist":
put:
description: handles the blocklisting of one or more subscribers.
operationId: manageBlocklistSubscribersById
tags:
- Subscribers
requestBody:
description: The id of subscriber to add or remove
content:
application/json:
schema:
$ref: "#/components/schemas/SubscriberQueryRequest"
parameters:
- in: path
name: id
required: true
description: The id value of the subscriber you want to blocklist.
schema:
type: integer
format: int32
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
"/subscribers/{id}/export":
get:
description: retrieves a subscriber's profile
operationId: exportSubscriberDataByID
tags:
- Subscribers
parameters:
- in: path
name: id
required: true
description: The id value of subscriber profile you want to export
schema:
type: integer
responses:
"200":
headers:
Cache-Control:
schema:
type: string
Content-Disposition:
schema:
type: string
example: attachment; filename="data.json"
description: subscriber data object
content:
application/json:
schema:
$ref: "#/components/schemas/SubscriberData"
"/subscribers/{id}/bounces":
get:
description: retrieves a subscriber's bounce records
operationId: getSubscriberBouncesById
tags:
- Subscribers
parameters:
- in: path
name: id
required: true
description: subscriber id
schema:
type: integer
responses:
"200":
description: list of bounce records of a subscriber
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/Bounce"
delete:
description: deletes a subscriber's bounce records
operationId: deleteSubscriberBouncesById
tags:
- Subscribers
parameters:
- in: path
name: id
required: true
description: subscriber id
schema:
type: integer
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
"/subscribers/{id}/optin":
post:
description: sends an optin confirmation e-mail to a subscriber.
operationId: subscriberSendOptinById
tags:
- Subscribers
parameters:
- in: path
name: id
required: true
description: sends an optin confirmation e-mail to a subscriber
schema:
type: integer
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
"/subscribers/query/delete":
post:
description: bulk deletes based on an arbitrary SQL expression.
operationId: deleteSubscriberByQuery
tags:
- Subscribers
requestBody:
description: Arbitrary SQL expression.
content:
text/plain:
schema:
type: string
application/json:
schema:
$ref: "#/components/schemas/SubscriberQueryRequest"
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
"/subscribers/query/blocklist":
put:
description: bulk blocklists subscribers based on an arbitrary SQL expression.
operationId: blocklistSubscribersQuery
tags:
- Subscribers
requestBody:
description: Arbitrary SQL expression.
content:
text/plain:
schema:
type: string
application/json:
schema:
$ref: "#/components/schemas/SubscriberQueryRequest"
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
"/subscribers/query/lists":
put:
description: bulk adds/removes/unsubscribes subscribers from one or more lists based on an arbitrary SQL expression.
operationId: manageSubscriberListsByQuery
tags:
- Subscribers
requestBody:
description: Arbitrary SQL expression.
content:
text/plain:
schema:
type: string
application/json:
schema:
$ref: "#/components/schemas/SubscriberQueryRequest"
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
/bounces:
get:
description: handles retrieval of bounce records.
operationId: getBounces
tags:
- Bounces
parameters:
- in: query
name: campaign_id
description: Numeric identifier for retrieving bounce records associated with a specific campaign
schema:
type: integer
- in: query
name: page
description: Page number for paginated results. Start from 1 for the first page
schema:
type: integer
- in: query
name: per_page
description: Number of items per page. Use an integer for specific page size or 'all' to retrieve all results
schema:
oneOf:
- type: integer
description: Number of items to return per page
- type: string
enum:
- "all"
description: Return all results without pagination
- in: query
name: source
description: Filter bounce records by their source of origin
schema:
type: string
- in: query
name: order_by
description: Specifies the field by which to sort the bounce records. Available options are 'email', 'campaign_name', 'source', and 'created_at'
schema:
type: string
enum: ["email", "campaign_name", "source", "created_at"]
- in: query
name: order
description: Determines the sort order of results. Use 'asc' for ascending or 'desc' for descending order
schema:
type: string
enum: ["asc", "desc"]
responses:
"200":
description: list of bounce records
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
results:
type: array
items:
$ref: "#/components/schemas/Bounce"
query:
type: string
total:
type: integer
per_page:
type: integer
page:
type: integer
delete:
description: handles deletion of bounce records.
operationId: deleteBounces
tags:
- Bounces
parameters:
- in: query
name: all
description: flag for multiple bounce record deletion
schema:
type: boolean
- in: query
name: id
description: list of bounce ids to delete
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
"/bounces/{id}":
get:
description: handles retrieval of bounce record by id
operationId: getBounceById
parameters:
- in: path
name: id
required: true
description: The id value of the bounce you want to retreive.
schema:
type: integer
tags:
- Bounces
responses:
"200":
description: bounce object
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/Bounce"
delete:
description: handles bounce deletion, either a single one (ID in the URI), or a list.
operationId: deleteBounceById
parameters:
- in: path
name: id
required: true
description: The id value of the bounce you want to delete.
schema:
type: integer
tags:
- Bounces
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
/lists:
get:
description: retrieves lists with additional metadata like subscriber counts. This may be slow.
operationId: getLists
tags:
- Lists
parameters:
- in: query
name: page
description: total number of pages
required: false
schema:
type: integer
- in: query
name: per_page
description: number of items per page
required: false
schema:
oneOf:
- type: integer
description: Number of items to return per page
- type: string
enum: ["all"]
description: Return all results without pagination
- in: query
name: query
description: Optional string to search a list by name.
required: false
schema:
type: string
- in: query
name: order_by
description: Field to sort results by. name|status|created_at|updated_at
required: false
schema:
type: string
enum: ["name", "status", "created_at", "updated_at"]
- in: query
name: order
description: ASC|DESC Sort by ascending or descending order.
required: false
schema:
type: string
enum: ["ASC", "DESC"]
- in: query
name: minimal
description: When set to true, returns response without body content
required: false
schema:
type: boolean
- in: query
name: tag
description: Tags to filter lists. Repeat in the query for multiple values.
required: false
schema:
type: array
items:
type: string
responses:
"200":
description: list of metadata
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
results:
type: array
items:
$ref: "#/components/schemas/List"
total:
type: integer
per_page:
type: integer
page:
type: integer
post:
description: handles list creation
operationId: createList
tags:
- Lists
requestBody:
description: new list info
content:
application/json:
schema:
$ref: "#/components/schemas/NewList"
responses:
"200":
description: updated list object
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/List"
"/lists/{list_id}":
get:
description: retrieves lists with additional metadata like subscriber counts. This may be slow.
operationId: getListById
tags:
- Lists
parameters:
- in: path
name: list_id
required: true
description: The id value of the list you want to retreive.
schema:
type: integer
responses:
"200":
description: list object
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/List"
put:
description: handles list modification
operationId: updateListById
tags:
- Lists
parameters:
- in: path
name: list_id
required: true
description: The id value of the list you want to update
schema:
type: integer
requestBody:
description: updated list field values
content:
application/json:
schema:
$ref: "#/components/schemas/List"
responses:
"200":
description: updated list object
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/List"
delete:
description: handles list deletion, either a single one (ID in the URI), or a list.
operationId: deleteListById
tags:
- Lists
parameters:
- in: path
name: list_id
required: true
description: The id value of the lists you want to delete.
schema:
type: integer
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
/import/subscribers:
get:
description: returns import status.
operationId: getImportSubscribers
tags:
- Import
responses:
"200":
description: import status
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/ImportStatus"
post:
description: handles the uploading and bulk importing of a ZIP file of one or more CSV files.
operationId: importSubscribers
tags:
- Import
requestBody:
description: uploads and bulk imports of compressed CSV files
content:
multipart/form-data:
schema:
type: object
properties:
params:
type: string
description: JSON string containing import parameters for more detail https://listmonk.app/docs/apis/import/#params-json-string
example: '{"mode":"subscribe", "subscription_status":"confirmed", "delim":",", "lists":[1, 2], "overwrite": true}'
file:
type: string
format: binary
description: File for upload.
responses:
"200":
description: updated import status
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/ImportStatus"
delete:
description: sends a stop signal to the importer.
operationId: stopImportSubscribers
tags:
- Import
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/ImportStatus"
/import/subscribers/logs:
get:
description: returns import logs from an ongoing import
operationId: getImportSubscriberLogs
tags:
- Import
responses:
"200":
description: import statistics
content:
application/json:
schema:
type: object
properties:
data:
type: string
/campaigns:
get:
description: handles retrieval of campaigns
operationId: getCampaigns
parameters:
- in: query
name: status
description: Filter campaigns by status. Multiple status values can be specified by repeating the parameter
required: false
schema:
type: array
items:
type: string
enum: ["scheduled", "running", "paused", "cancelled"]
- in: query
name: no_body
description: When set to true, returns response without body content
required: false
schema:
type: boolean
- in: query
name: page
description: Page number for paginated results.
required: false
schema:
type: integer
- in: query
name: per_page
description: Number of items per page. Use an integer for specific page size or 'all' to retrieve all results
required: false
schema:
oneOf:
- type: integer
description: Number of items to return per page
- type: string
enum: ["all"]
description: Return all results without pagination
- in: query
name: tags
description: Filter campaigns by tags. Multiple tags can be specified by repeating the parameter
required: false
schema:
type: array
items:
type: string
- in: query
name: order
description: Determines the sort order of results. ASC for ascending, DESC for descending order
required: false
schema:
type: string
enum: ["ASC", "DESC"]
- in: query
name: order_by
description: Specifies the field by which to sort the campaigns. Available options are 'name', 'status', 'created_at', and 'updated_at'
required: false
schema:
type: string
enum: ["name", "status", "created_at", "updated_at"]
- in: query
name: query
description: SQL query expression to filter campaigns by custom criteria
required: false
schema:
type: string
tags:
- Campaigns
responses:
"200":
description: list of campaigns
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
results:
type: array
items:
$ref: "#/components/schemas/Campaign"
query:
type: string
total:
type: integer
per_page:
type: integer
page:
type: integer
post:
description: handles campaign creation
operationId: createCampaign
tags:
- Campaigns
requestBody:
description: new campaign info
content:
application/json:
schema:
$ref: "#/components/schemas/CampaignRequest"
responses:
"200":
description: new campaign object
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/CampaignUpdate"
"/campaigns/{id}":
get:
description: handles retrieval of campaigns.
operationId: getCampaignById
tags:
- Campaigns
parameters:
- in: path
name: id
required: true
description: The id value of the campaign you want to get.
schema:
type: integer
- in: query
name: no_body
required: false
description: boolean flag for response with/without body
schema:
type: boolean
responses:
"200":
description: campaign object
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/Campaign"
put:
description: handle updation of campaign
operationId: updateCampaignById
tags:
- Campaigns
parameters:
- in: path
name: id
required: true
description: the id value of campaign you want to update
schema:
type: integer
requestBody:
description: updated campaign fields
content:
application/json:
schema:
$ref: "#/components/schemas/CampaignRequest"
responses:
"200":
description: updated campaign object
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/CampaignUpdate"
delete:
description: deletes specified campaign
operationId: deleteCampaignById
tags:
- Campaigns
parameters:
- in: path
name: id
required: true
description: The id value of the campaign you want to get.
schema:
type: integer
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
/campaigns/running/stats:
get:
description: returns stats of a given set of campaign IDs.
operationId: getRunningCampaignStats
tags:
- Campaigns
parameters:
- in: query
name: campaign_id
description: Campaign IDs to get stats for.
required: true
schema:
type: number
responses:
"200":
description: list of stats for given set of campaign ids
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/CampaignStats"
"/campaigns/analytics/{type}":
get:
description: retrieves view counts for a campaign.
operationId: getCampaignAnalytics
tags:
- Campaigns
parameters:
- in: path
required: true
name: type
description: type of stats, either links, view, click or bounce
schema:
type: string
enum: [links, views, clicks, bounces]
- in: query
required: true
name: from
description: start value of date range
schema:
type: string
format: date
- in: query
required: true
name: to
description: end value of date range
schema:
type: string
- in: query
name: id
description: campaign id/s to retrive view counts
required: true
schema:
type: string
responses:
"200":
description: list of stats for given set of campaign ids
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/CampaignAnalyticsCount"
"/campaigns/{id}/preview":
get:
description: renders the HTML preview of a campaign body
operationId: previewCampaignById
tags:
- Campaigns
parameters:
- in: path
name: id
required: true
description: The id value of the campaign you want to get the preview of
schema:
type: integer
responses:
"200":
description: HTML Preview of requested campaign
content:
text/html:
schema:
type: string
example: <h3>Hi John!</h3>This is a e-mail campaign. Your second name is Doe and you are from Bengaluru
post:
description: renders the HTML preview of a campaign body
operationId: updatePreviewCampaignById
tags:
- Campaigns
parameters:
- in: path
name: id
required: true
description: The id value of the campaign you want to get the preview of
schema:
type: integer
requestBody:
required: true
description: template id, body and content type
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
template_id:
description: template id
type: integer
content_type:
description: content type
type: string
body:
description: template body
type: string
responses:
"200":
description: HTML Preview of requested campaign
content:
text/html:
schema:
type: string
example: <h3>Hi John!</h3>This is a e-mail campaign. Your second name is Doe and you are from Bengaluru
"/campaigns/{id}/text":
post:
description: renders the HTML preview of a campaign body
operationId: previewCampaignTextById
tags:
- Campaigns
requestBody:
required: true
description: template id, content type and campaign body
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
template_id:
description: template id
type: integer
content_type:
description: content type
type: string
body:
description: campaign body
type: string
parameters:
- in: path
name: id
required: true
description: The id value of the campaign you want to get the preview of
schema:
type: integer
responses:
"200":
description: response
content:
text/html:
schema:
type: string
example: <h3>Hi John!</h3><p>This is a test e-mail campaign. Your second name is Doe and you are from Bengaluru</p>
"/campaigns/{id}/status":
put:
description: handles campaign status modification
operationId: updateCampaignStatusById
tags:
- Campaigns
parameters:
- in: path
name: id
required: true
description: The id value of the campaign you want to get the preview of
schema:
type: integer
requestBody:
description: campaign status update
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum: [scheduled, running, paused, cancelled]
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/Campaign"
"/campaigns/{id}/archive":
put:
description: handles campaign status modification
operationId: updateCampaignArchiveById
tags:
- Campaigns
parameters:
- in: path
name: id
required: true
description: The id value of the campaign you want to get the preview of
schema:
type: integer
requestBody:
description: archive campaign related parameters
content:
application/json:
schema:
type: object
properties:
archive:
type: boolean
archive_template_id:
type: integer
archive_meta:
type: object
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
"/campaigns/{id}/content":
post:
description: handles campaign content (body) format conversions.
operationId: createCampaignContentById
tags:
- Campaigns
requestBody:
description: updated campaign content
content:
application/json:
schema:
$ref: "#/components/schemas/CampaignContentRequest"
parameters:
- in: path
name: id
description: ID of campaign that you choose to create content
required: true
schema:
type: integer
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
type: string
"/campaigns/{id}/test":
post:
description: handles sending of campaign message to arbitrary subscribers for testing
operationId: testCampaignById
tags:
- Campaigns
parameters:
- in: path
name: id
description: ID of campaign that you want to test
required: true
schema:
type: integer
requestBody:
required: true
description: template id
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
template_id:
description: template id
type: integer
application/json:
schema:
$ref: "#/components/schemas/CampaignRequest"
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
"/media":
get:
description: handles retrieval of uploaded media.
operationId: getMedia
tags:
- Media
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/MediaFileObject"
post:
description: handles media file uploads.
operationId: uploadMedia
tags:
- Media
requestBody:
description: upload media file
content:
multipart/form-data:
schema:
type: string
format: binary
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/MediaFileObject"
"/media/{id}":
get:
description: handles retrieval of uploaded media.
operationId: getMediaById
tags:
- Media
parameters:
- in: path
name: id
required: true
description: media file id
schema:
type: integer
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/MediaFileObject"
delete:
description: handles deletion of uploaded media.
operationId: deleteMediaById
tags:
- Media
parameters:
- in: path
name: id
required: true
description: The id value of the list you want to delete.
schema:
type: integer
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
/templates:
get:
description: handles retrieval of templates
operationId: getTemplates
tags:
- Templates
parameters:
- in: query
name: no_body
description: boolean flag for response with/without body
required: true
schema:
type: boolean
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/Template"
post:
description: handles template creation
operationId: createTemplate
tags:
- Templates
requestBody:
description: new template info
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/NewTemplate"
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/Template"
"/templates/{id}":
get:
description: handles retrieval of templates
operationId: getTemplateById
tags:
- Templates
parameters:
- in: path
name: id
required: true
schema:
type: integer
description: The id value of the template you want to get.
- in: query
name: no_body
description: boolean flag for response with/without body
required: false
schema:
type: boolean
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/Template"
put:
description: handles template modification
operationId: updateTemplateById
tags:
- Templates
parameters:
- in: path
name: id
required: true
description: The id value of the template you want to update.
schema:
type: integer
requestBody:
description: updated template info
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateTemplate"
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
$ref: "#/components/schemas/Template"
delete:
description: handles deletion of templates
operationId: deleteTemplateById
tags:
- Templates
parameters:
- in: path
name: id
required: true
description: The id value of the template you want to delete.
schema:
type: integer
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
/templates/preview:
post:
description: get the HTML preview of a template.
operationId: previewTemplate
tags:
- Templates
requestBody:
required: true
description: template parameters
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
template_type:
description: type of template
type: string
body:
description: template body
type: string
responses:
"200":
description: response
content:
text/html:
schema:
type: string
example: <p>Hi there</p>
"/templates/{id}/preview":
get:
description: renders the HTML preview of a template.
operationId: previewTemplateById
tags:
- Templates
requestBody:
description: template parameters
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
template_type:
description: type of template
type: string
body:
description: template body
type: string
parameters:
- in: path
name: id
required: true
schema:
type: integer
description: The id value of the template you want to get.
responses:
"200":
description: response
content:
text/html:
schema:
type: string
example: <p>Hi there</p>
"/templates/{id}/default":
put:
description: handles template modification.
operationId: setDefaultTemplateById
tags:
- Templates
parameters:
- in: path
name: id
required: true
description: The id value of the template you want to set to the default template.
schema:
type: integer
responses:
"200":
description: response
content:
application/json:
schema:
$ref: "#/components/schemas/Template"
/tx:
post:
tags:
- Transactional
description: send message to a subscriber
operationId: transactWithSubscriber
requestBody:
description: email message to a subscriber
content:
application/json:
schema:
$ref: "#/components/schemas/TransactionalMessage"
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
"/maintenance/subscribers/{type}":
delete:
description: garbage collects (deletes) orphaned or blocklisted subscribers.
operationId: deleteGCSubscribers
tags:
- Maintenance
parameters:
- in: path
name: type
description: type of GC collected subscribers
schema:
type: string
required: true
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
count:
type: integer
"/maintenance/analytics/{type}":
delete:
description: garbage collects (deletes) campaign analytics.
operationId: deleteCampaignAnalyticsByType
tags:
- Maintenance
requestBody:
description: date parameter
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
before_date:
type: string
format: date
parameters:
- in: path
name: type
description: type of GC collected subscribers
schema:
type: string
required: true
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
type: boolean
"/maintenance/subscriptions/unconfirmed":
delete:
description: garbage collects (deletes) orphaned or blocklisted subscribers.
operationId: deleteUnconfirmedSubscriptions
tags:
- Maintenance
requestBody:
required: true
description: date parameter
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
before_date:
type: string
format: date
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
count:
type: integer
"/public/lists":
get:
description: returns the list of public lists with minimal fields
operationId: getPublicLists
tags:
- Public
responses:
"200":
description: response
content:
application/json:
schema:
type: array
items:
type: object
properties:
uuid:
type: string
name:
type: string
"/public/subscription":
post:
description: handles subscription requests coming from public API calls.
operationId: handlePublicSubscription
tags:
- Public
requestBody:
description: subscription request parameters
content:
application/json:
schema:
type: object
properties:
name:
type: string
email:
type: string
list_uuids:
type: array
items:
type: string
responses:
"200":
description: response
content:
application/json:
schema:
type: object
properties:
has_optin:
type: boolean
components:
schemas:
LanguagePack:
type: object
properties:
data:
type: object
description: Translation keys and localized strings. See i18n/en.json for the current keys.
additionalProperties:
type: string
properties:
_.code:
type: string
_.name:
type: string
ServerConfig:
type: object
properties:
data:
type: object
properties:
messengers:
type: array
items:
type: string
langs:
type: array
items:
type: object
properties:
code:
type: string
name:
type: string
lang:
type: string
update:
type: string
needs_restart:
type: boolean
version:
type: string
DashboardChart:
type: object
properties:
link_clicks:
type: array
items:
type: object
properties:
count:
type: integer
date:
type: string
campaign_views:
type: array
items:
type: object
properties:
count:
type: integer
date:
type: string
DashboardCount:
type: object
properties:
data:
type: object
properties:
subscribers:
type: object
properties:
total:
type: integer
blocklisted:
type: object
orphans:
type: integer
lists:
type: object
properties:
total:
type: integer
private:
type: integer
public:
type: integer
optin_single:
type: integer
optin_double:
type: integer
campaigns:
type: object
properties:
total:
type: integer
by_status:
type: object
properties:
draft:
type: integer
messages:
type: integer
SMTPSettings:
type: object
properties:
uuid:
type: string
enabled:
type: boolean
host:
type: string
hello_hostname:
type: string
port:
type: integer
auth_protocol:
type: string
username:
type: string
email_headers:
type: array
items:
type: object
max_conns:
type: integer
max_msg_retries:
type: integer
idle_timeout:
type: string
wait_timeout:
type: string
tls_type:
type: string
tls_skip_verify:
type: boolean
SMTPTest:
type: object
properties:
uuid:
type: string
enabled:
type: boolean
host:
type: string
hello_hostname:
type: string
port:
type: integer
auth_protocol:
type: string
username:
type: string
email_headers:
type: array
items:
type: object
max_conns:
type: integer
max_msg_retries:
type: integer
idle_timeout:
type: string
wait_timeout:
type: string
tls_type:
type: string
tls_skip_verify:
type: boolean
strEmailHeaders:
type: string
password:
type: string
email:
type: string
MailBoxBounces:
type: object
properties:
uuid:
type: string
enabled:
type: boolean
type:
type: string
host:
type: string
port:
type: integer
auth_protocol:
type: string
return_path:
type: string
username:
type: string
tls_enabled:
type: boolean
tls_skip_verify:
type: boolean
scan_interval:
type: string
Settings:
type: object
properties:
app.site_name:
type: string
app.root_url:
type: string
app.logo_url:
type: string
app.favicon_url:
type: string
app.from_email:
type: array
description: Sender addresses. The first must be a literal email address and is the default for campaigns and system emails.
minItems: 1
maxItems: 100
items:
type: string
maxLength: 2000
app.notify_emails:
type: array
items:
type: string
app.enable_public_subscription_page:
type: boolean
app.enable_public_archive:
type: boolean
app.send_optin_confirmation:
type: boolean
app.check_updates:
type: boolean
app.lang:
type: string
app.batch_size:
type: integer
app.concurrency:
type: integer
app.max_send_errors:
type: integer
app.message_rate:
type: integer
app.message_sliding_window:
type: boolean
app.message_sliding_window_duration:
type: string
app.message_sliding_window_rate:
type: integer
privacy.individual_tracking:
type: boolean
privacy.unsubscribe_header:
type: boolean
privacy.allow_blocklist:
type: boolean
privacy.allow_preferences:
type: boolean
privacy.allow_export:
type: boolean
privacy.allow_wipe:
type: boolean
privacy.exportable:
type: array
items:
type: string
privacy.domain_blocklist:
type: array
items:
type: object
upload.provider:
type: string
upload.filesystem.upload_path:
type: string
upload.filesystem.upload_uri:
type: string
upload.s3.url:
type: string
upload.s3.public_url:
type: string
upload.s3.aws_access_key_id:
type: string
upload.s3.aws_default_region:
type: string
upload.s3.bucket:
type: string
upload.s3.bucket_domain:
type: string
upload.s3.bucket_path:
type: string
upload.s3.bucket_type:
type: string
upload.s3.expiry:
type: string
smtp:
type: array
items:
$ref: "#/components/schemas/SMTPSettings"
messengers:
type: array
items:
type: object
bounce.enabled:
type: boolean
bounce.webhooks_enabled:
type: boolean
bounce.count:
type: integer
bounce.action:
type: string
bounce.ses:
type: object
properties:
enabled:
type: boolean
topic_arns:
type: array
items:
type: string
bounce.azure:
type: object
properties:
enabled:
type: boolean
shared_secret:
type: string
shared_secret_header:
type: string
bounce.sendgrid:
type: object
properties:
enabled:
type: boolean
key:
type: string
bounce.forwardemail:
type: object
properties:
enabled:
type: boolean
key:
type: string
bounce.postmark:
type: object
properties:
enabled:
type: boolean
username:
type: string
password:
type: string
bounce.lettermint:
type: object
properties:
enabled:
type: boolean
key:
type: string
bounce.mailboxes:
type: array
items:
$ref: "#/components/schemas/MailBoxBounces"
appearance.admin.custom_css:
type: string
appearance.admin.custom_js:
type: string
appearance.public.custom_css:
type: string
appearance.public.custom_js:
type: string
SubscriberProfile:
type: object
properties:
id:
type: integer
uuid:
type: string
email:
type: string
name:
type: string
attribs:
type: object
additionalProperties: true
status:
type: string
created_at:
type: string
updated_at:
type: string
Subscriptions:
type: object
properties:
subscription_status:
type: string
name:
type: string
type:
type: string
created_at:
type: string
SubscriberData:
type: object
properties:
email:
type: string
profile:
type: array
items:
$ref: "#/components/schemas/SubscriberProfile"
subscriptions:
type: array
items:
$ref: "#/components/schemas/Subscriptions"
campaign_views:
type: array
items:
type: object
link_clicks:
type: array
items:
type: object
Subscriber:
type: object
properties:
id:
type: integer
created_at:
type: string
updated_at:
type: string
uuid:
type: string
email:
type: string
name:
type: string
attribs:
type: object
additionalProperties: true
status:
type: string
lists:
type: array
items:
type: object
properties:
subscription_status:
type: string
id:
type: integer
uuid:
type: string
name:
type: string
type:
type: string
tags:
type: array
items:
type: string
created_at:
type: string
updated_at:
type: string
NewSubscriber:
type: object
properties:
email:
type: string
name:
type: string
status:
type: string
lists:
type: array
items:
type: integer
list_uuids:
type: array
items:
type: string
preconfirm_subscriptions:
type: boolean
attribs:
type: object
additionalProperties: true
UpdateSubscriber:
type: object
properties:
email:
type: string
name:
type: string
status:
type: string
lists:
type: array
items:
type: integer
list_uuids:
type: array
items:
type: string
preconfirm_subscriptions:
type: boolean
attribs:
type: object
additionalProperties: true
SubscriberQueryRequest:
type: object
properties:
query:
type: string
ids:
type: array
description: The ids of the subscribers to be modified.
items:
type: integer
action:
type: string
enum: [add, remove, unsubscribe]
description: Whether to add, remove, or unsubscribe the users.
target_list_ids:
type: integer
description: The ids of the lists to be modified.
items:
type: integer
status:
type: string
enum: [confirmed, unconfirmed, unsubscribed]
description: confirmed, unconfirmed, or unsubscribed status.
Bounce:
type: object
properties:
results:
type: array
items:
type: object
properties:
id:
type: integer
type:
type: string
source:
type: string
meta:
type: object
created_at:
type: string
email:
type: string
subscriber_uuid:
type: string
subscriber_id:
type: integer
campaign:
type: object
properties:
id:
type: integer
name:
type: string
campaign_uuid:
type: string
total:
type: integer
List:
type: object
properties:
id:
type: integer
created_at:
type: string
updated_at:
type: string
uuid:
type: string
name:
type: string
type:
type: string
optin:
type: string
tags:
type: array
items:
type: string
subscriber_count:
type: integer
description:
type: string
NewList:
type: object
properties:
name:
type: string
type:
type: string
enum: [public, private]
optin:
type: string
enum: [single, double]
tags:
type: array
items:
type: string
description:
type: string
ImportStatus:
type: object
properties:
data:
type: object
properties:
name:
type: string
total:
type: integer
imported:
type: integer
status:
type: string
Campaign:
type: object
properties:
id:
type: integer
created_at:
type: string
updated_at:
type: string
CampaignID:
type: integer
views:
type: integer
clicks:
type: integer
lists:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
started_at:
type: string
to_send:
type: integer
sent:
type: integer
uuid:
type: string
type:
type: string
enum: [regular, optin]
name:
type: string
subject:
type: string
from_email:
type: string
body:
type: string
send_at:
type: string
status:
type: string
content_type:
type: string
enum: [richtext, html, markdown, plain]
tags:
type: array
items:
type: string
template_id:
type: integer
messenger:
type: string
CampaignContentRequest:
type: object
properties:
id:
type: integer
created_at:
type: string
updated_at:
type: string
CampaignID:
type: integer
views:
type: integer
clicks:
type: integer
lists:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
started_at:
type: string
to_send:
type: integer
sent:
type: integer
uuid:
type: string
type:
type: string
enum: [regular, optin]
name:
type: string
subject:
type: string
from_email:
type: string
body:
type: string
send_at:
type: string
status:
type: string
content_type:
type: string
enum: [richtext, html, markdown, plain]
tags:
type: array
items:
type: string
template_id:
type: integer
messenger:
type: string
from:
type: string
to:
type: string
CampaignRequest:
type: object
properties:
name:
type: string
subject:
type: string
lists:
type: array
items:
type: number
from_email:
type: string
content_type:
type: string
messenger:
type: string
type:
type: string
tags:
type: array
items:
type: string
send_later:
type: boolean
send_at:
type: object
properties:
headers:
type: array
items:
type: object
template_id:
type: number
CampaignUpdate:
type: object
properties:
name:
type: string
subject:
type: string
lists:
type: array
items:
type: integer
from_email:
type: string
messenger:
type: string
type:
type: string
tags:
type: array
items:
type: string
send_later:
type: boolean
send_at:
type: object
headers:
type: array
items:
type: object
template_id:
type: integer
content_type:
type: string
body:
type: string
altbody:
type: string
archive:
type: boolean
archive_template_id:
type: integer
archive_meta:
type: object
CampaignStats:
type: object
properties:
id:
type: integer
status:
type: string
to_send:
type: integer
sent:
type: integer
started_at:
type: string
format: date
updated_at:
type: string
format: date
rate:
type: integer
net_rate:
type: integer
CampaignAnalyticsCount:
type: object
properties:
campaign_id:
type: integer
count:
type: integer
timestamp:
type: string
format: date-time
MediaFileObject:
type: object
properties:
id:
type: integer
uuid:
type: string
filename:
type: string
content_type:
type: string
created_at:
type: string
thumb_url:
type: string
thumb_uri:
type: string
provider:
type: string
meta:
type: object
url:
type: string
uri:
type: string
Template:
type: object
properties:
id:
type: integer
created_at:
type: string
updated_at:
type: string
name:
type: string
body:
type: string
body_source:
type: string
subject:
type: string
type:
type: string
is_default:
type: boolean
NewTemplate:
type: object
required:
- name
- type
- body
properties:
name:
type: string
description: Name of the template
type:
type: string
enum: [campaign, campaign_visual, tx]
description: Type of the template
subject:
type: string
description: Subject line for the template (only for tx)
body_source:
type: string
description: JSON source for the email-builder template (only for campaign_visual)
body:
type: string
description: HTML body of the template
UpdateTemplate:
type: object
properties:
name:
type: string
description: Name of the template
type:
type: string
enum: [campaign, campaign_visual, tx]
description: Type of the template
subject:
type: string
description: Subject line for the template (only for tx)
body_source:
type: string
description: JSON source for the email-builder template (only for campaign_visual)
body:
type: string
description: HTML body of the template
TransactionalMessage:
type: object
properties:
subscriber_email:
type: string
subscriber_id:
type: integer
template_id:
type: integer
from_email:
type: string
data:
type: object
headers:
type: array
items:
type: object
messenger:
type: string
content_type:
type: string