/campaigns/:status
Returns all campaigns you have in your account by :status which is required. Also basic summary for each campaign including the ID.
There are three possible values of :status parameter:
sent- campaigns which are sent alreadydraft- campaigns which aren't completed or sent to subscribersoutbox- campaigns which are being sent right now or scheduled campaigns
If you do not specify :status parameter, it defaults to sent.
There are some optional parameters which are described above.
id
Integer
ID of a campaign
total_recipients
Integer
Total count of receivers in campaign
type
String
Possible values:
regularabfollowuprss
date_created
String
When the campaign was created
date_sent
String
When the email was sent. If campaign type is outbox, this parameter will show the scheduled date.
name
String
Campaign name, which is inherited from email subject.
status
String
Possible values:
sentdraftoutbox
opened
Object
opened.count
Integer
Total opens of campaign.
Available only for sent campaigns.
Default value: 0
opened.rate
Float
Open rate of campaign.
Available only for sent campaigns.
Default value: 0
clicked
Object
clicked.count
Integer
Total clicks of campaign.
Available only for sent campaigns.
Default value: 0
clicked.rate
Float
Click rate of campaign.
Available only for sent campaigns.
Default value: 0
You can retrieve only the number of campaigns by type. If you do not specify :status, it defaults to sent.
{
"count": 3
}/campaigns
Create campaign where you will use your custom HTML template
Email type of created campaign
Campaigns that are created using this endpoint require your own custom HTML templates to be added via API using /campaigns/:id/content endpoint or directly in MailerLiter application.
Here is more details about ab_settings object.
All fields are required!
values
array
Must contain two values. It depends on send_type.
For example, if send_type equals to sender these values are used as sender names for AB test.
If send_type equals to subject these values are used as subjects for AB test.
send_type
string
Available values:
sendersubject
ab_win_type
string
It defines how winner will be selected.
Available values:
opensclicks
winner_after
integer
It defines how long AB test is active.
Pay attention that this is only a number and type is defined as winner_after_type
winner_after_type
string
Available values:
d- daysh- hours
split_part
integer
It defines size of every test group in percents equally.
Available range: 5-25
/campaigns/:id
Remove a campaign.
Be aware that deleting a scheduled campaign is not possible - you would have to cancel it first.
/campaigns/:id/content
Upload your HTML template to created campaign
You can use your custom HTML template and associate it with created campaign using this endpoint.
HTML template must contain a link for unsubscribe. It may look like this:
<a href="{$unsubscribe}">Unsubscribe</a>
Some email clients do not support HTML emails so you need to set plain text email and it must contain these variables:
- {$unsubscribe} - unsubscribe link
- {$url} - URL to your HTML newsletter
/campaigns/:id/actions/:action
Send, schedule or cancel campaign
Every action is active due to some conditions (campaign type) described in table below.
send
regularabfollowup
draft
You can send every campaign in draft which has step value equal to 3
cancel
regularabfollowuprss
outbox
You can cancel every campaign in outbox.
Please take attention that every action is available only for specific type campaigns:
send: you can send or schedule those campaigns which are indraftand hasstepvalue equal to3cancel: you can cancel only those campaigns which are inoutbox
Send or schedule endpoint has additional body parameters associated with Google analytics, schedule and followup campaigns.
We provide two options how campaign can be sent regarding to sending time.
Send now
There is no need to use request parameters for all types of campaigns.
Send later (schedule)
For all types of campaigns:
type = 2dateis requiredtimezone_idis optional. Default value is ID of timezone which is associated with Account
Followup campaign schedule
If campaign type is followup, its followup mail will be sent 24 hours from campaign sending time by default. If you want to set custom time for followup campaign, then use these additional request parameters:
followup_schedule = specificfollowup_dateis requiredfollowup_timezone_idis optional. Default value is ID of timezone which is associated with Account
type
Integer
Possible values:
1- send instantly (default value)2- schedule send
followup_schedule
String
Possible values:
24h- followup mail is sent in 24 hours (default value)specific- must provide custom time described below
Only for followup campaigns
analytics
Integer
Possible values:
0- false1- true
date
String
Format:
yyyy-mm-dd H:i
Available when type is 2
followup_date
String
Format:
yyyy-mm-dd H:i
Available only for followup campaigns when followup_schedule is specific
followup_timezone_id
Integer
ID of Timezone
Available only for followup campaigns when followup_schedule is specific
/segments
Returns all stored segments in your account.
id
Integer
ID of the segment
title
String
Title of the segment
filter
Object
Array of segment rules
total
Integer
Number of subscribers in the filter
sent
Integer
Total number of sent emails to the segment subscribers
opened
Integer
Total number of opened emails by segment subscribers
clicked
Integer
Total number or clicked links by segment subscribers
You can retrieve only the number of segments.
{
"count": 3
}/subscribers
Get account's subscribers
The response body contains the array of a subscriber objects which is documented here.
/subscribers
Add new single subscriber
Response contains Single Subscriber object.
Find out how to enable it in our help center.
/subscribers/(:id or :email)
Get single subscriber
id
integer
ID of a subscriber
email
string
Email address
name
string
Name of a subscriber
sent
integer
Count of emails sent to subscriber
opened
integer
Count of emails opened by subscriber
clicked
integer
Count of clicks made by subscriber
type
string
Available values:
activebouncedunsubscribedjunkunconfirmed
signup_ip
string
IPv4 or IPv6 address indicating the subscriber's signup
signup_timestamp
string
UTC in format Y-m-d H:i:s
confirmation_ip
string
IPv4 or IPv6 address indicating the subscriber's opt-in
confirmation_timestamp
string
UTC in format Y-m-d H:i:s
date_subscribe
string
Important only when getting Subscribers in a Group. It shows when subscriber is added to group.
Date format: Y-m-d
Default value: null.
date_unsubscribe
string
Important only when getting Subscribers in a Group. It shows when subscriber's status changed to unsubscribed.
Date format: Y-m-d H:i:s
Default value: null.
date_created
string
Date when subscriber is created
Format: Y-m-d H:i:s
date_updated
string
Datetime when subscriber is updated:
Format: Y-m-d H:i:s
Signup & Confirmation fields
signup_ipsignup_timestampconfirmation_ipconfirmation_timestamp
Those fields are filled automatically using our built-in webforms.
When double opt-in is enabled and subscriber signs up, we fill only signup_* fields. After subscriber's confirmation, confirmation_* fields are updated too.
When double opt-in is disabled, all the fields are filled with the same data because sign up and confirmation is performed as a single action.
We use Gravatar profile images for subscriber profile in web application. The image below is used as default.
/subscribers/(:id or :email)
Update single subscriber
Response contains Single Subscriber objects.
/subscribers/(:id or :email)/groups
Get groups subscriber belongs to
Response is an array of Group objects.
/subscribers/(:id or :email)/activity
Get activity (clicks, opens, etc) of selected subscriber
date
string
Date & time when action is performed
report_id
integer
ID of report actions belongs to
subject
string
Subject of received email
type
string
Available values:
openclickjunkbounceunsubscribeforward
These parameters are provided when the following condition is true:
type = click
link_id
integer
ID of link object
link
string
URL value
These parameters are provided when the following condition is true:
type = forward
receiver
object
receiver.name
string
Name of forwarded email receiver
receiver.email
string
Email of forwarded email receiver
sender
object
sender.name
string
Name of forwarded mail sender
sender.email
string
Email of forwarded mail sender
/subscribers/(:id or :email)/activity/:type
Get activity of selected subscriber by specified type (opens, clicks, etc)
This endpoint is the same as Actions of Subscriber but it allows to get actions by specified type.
/groups
Get list of groups
id
integer
ID of group
name
string
Title of group
total
integer
Total count of people in group
active
integer
Total count of active people in group
unsubscribed
integer
Total count of unsubscribed people in group
bounced
integer
Total count of bounced people in group
unconfirmed
integer
Total count of unconfirmed people in group
junk
integer
Total count of junk people in group
sent
integer
Total count of sent emails in a group
opened
integer
Total count of opens in a group
clicked
integer
Total count of clicks in a group
date_created
string
Date & time when group is created
date_updated
string
Date & time when group is updated
/groups/:id
Get single group by ID
id
integer
ID of group
name
string
Title of group
total
integer
Total count of people in group
active
integer
Total count of active people in group
unsubscribed
integer
Total count of unsubscribed people in group
bounced
integer
Total count of bounced people in group
unconfirmed
integer
Total count of unconfirmed people in group
junk
integer
Total count of junk people in group
sent
integer
Total count of sent emails in a group
opened
integer
Total count of opens in a group
clicked
integer
Total count of clicks in a group
date_created
string
Date & time when group is created
date_updated
string
Date & time when group is updated
/groups
Create new group
id
integer
ID of group
name
string
Title of group
total
integer
Total count of people in group
active
integer
Total count of active people in group
unsubscribed
integer
Total count of unsubscribed people in group
bounced
integer
Total count of bounced people in group
unconfirmed
integer
Total count of unconfirmed people in group
junk
integer
Total count of junk people in group
sent
integer
Total count of sent emails in a group
opened
integer
Total count of opens in a group
clicked
integer
Total count of clicks in a group
date_created
string
Date & time when group is created
date_updated
string
Date & time when group is updated
/groups/:id
Update existing group
id
integer
ID of group
name
string
Title of group
total
integer
Total count of people in group
active
integer
Total count of active people in group
unsubscribed
integer
Total count of unsubscribed people in group
bounced
integer
Total count of bounced people in group
unconfirmed
integer
Total count of unconfirmed people in group
junk
integer
Total count of junk people in group
sent
integer
Total count of sent emails in a group
opened
integer
Total count of opens in a group
clicked
integer
Total count of clicks in a group
date_created
string
Date & time when group is created
date_updated
string
Date & time when group is updated
/groups/:id/subscribers
Add new single subscriber to specified group
Response contains Single Subscriber object.
Find out how to enable it in our help center.
/groups/:id/subscribers/import
Add many new subscribers to specified group at once
Response contains Single Subscriber object.
/groups/:id/subscribers/import/:import_id
Add many new subscribers to specified group at once
id
id
ID of an import
type
string
Action type
stats
object
stats.imported
integer
Total created subscribers
stats.duplicates
integer
Total duplicated items in a single import
stats.invalid
integer
Total invalid email adresses
stats.unchanged
integer
Total unchanged subscribers
stats.total
integer
Total emails in the import
options
object
options.resubscribe
boolean
Determines if it needed to activate unsubscribed/bounced/unconfirmed subscribers
options.autoresponders
boolean
Determines if it is needed to trigger automations
is_finished
boolean
Determines if an import is finished
is_importing
boolean
Determines if an import is in progress
is_killed
boolean
Determines if an import is stopped
created_at
string
Datetime, UTC.
Format: Y-m-d H:i:s
/groups/:id/subscribers
Get all subscribers in a specified group
Response is the array of Single Subscriber objects.
Also there is some additional endpoints associated with subscribers in group:
{
"count": 5
}Endpoint
GET /groups/:group_id/subscribers/:type
Possible values of :type:
activeunsubscribedbouncedjunkunconfirmed
Response Example
The same structure as it is described above so response is the array of Single Subscriber objects.
# get all subscribers who were created in a provided period
curl -v http://api.mailerlite.com/api/v2/groups/3640549/subscribers?filters[date_created][$gte]=2017-03-01&filters[date_created][$lt]=2017-04-01 \
-H "X-MailerLite-ApiKey: fc7b8c5b32067bcd47cafb5f475d2fe9"
# get all subscribers who were after the selected day
curl -v http://api.mailerlite.com/api/v2/groups/3640549/subscribers?filters[date_created][$gte]=2017-03-01 \
-H "X-MailerLite-ApiKey: fc7b8c5b32067bcd47cafb5f475d2fe9"Available keys:
date_subscribedate_unsubscribedate_createddate_updated
Available operators:
$gt - greater than$gte - greater than or equal$lt - less than$lte - less than or equal
/groups/:id/subscribers/:type
Get all subscribers in a specified group
The same endpoint as /groups/:id/subscribers but it has type parameter defined so results are filtered by its value.
Possible values of :type:
activeunsubscribedbouncedjunkunconfirmed
Response is the array of Single Subscriber objects.
{
"count": 5
}/groups/:id/subscribers/(:subscriber_id)
Get all subscribers in a specified group
A response is an array of Single Subscriber objects.
/groups/:id/subscribers/:subscriber_id or :email
Remove single subscriber from specified group
/fields
Get subscriber fields of account
id
integer
ID of field
title
string
Title of field
key
string
Key of field which is generated automatically
type
string
Possible values:
TEXTNUMBERDATE
date_updated
string
Date & time.
Default: null
date_created
string
Date & time.
Default: null
/settings/double_optin
Retrieve the status if double opt-in for API and integrations is enabled
Language
ar
(arabic)العربية
bg
Български
ca
Català
ch
Chinese
cz
Český
de
Deutsch
dk
Dansk
ee
Eesti
en
English
es
Español
fi
Finnish
fr
Français
frq
Français - Québec
gr
Ελληνικά
he
(hebrew)עברית
hr
Hrvatski
hu
Magyar
it
Italiano
lt
Lietuviškai
lv
Latviešu
mk
Македонски
mx
Español (Mexican)
nl
Nederlands
no
Norsk
pl
Polski
pr
(persian)فارسی
pt
Português
ptbr
Português (Brazil)
ro
Română
ru
Русский
se
Svenska
sk
Slovensky
sl
Slovenski
sr
Српски
tr
Türkçe
ua
Українська
code
String
Language code
title
String
Language title
{
"code": "en",
"title": "English"
}Subscriber's Field Value
This object is used in Single Subscriber object. Subscriber has fields parameter and it is array of that kind of objects described below.
key
string
URL friendly field name
value
string
Value of field
type
string
Allowed type for field value.
Available values:
TEXTNUMBERDATE
{
"key": "first_name",
"value": "Justinas",
"type": "TEXT"
}{
"key": "favourite_color",
"value": "MailerLite Green",
"field_type": "TEXT"
}