Introduction to the Moosend API and what topics are included in this API documentation.
Moosend is a cloud-based, AI-powered email marketing solution that allows you to target your audience at scale.
The API enables you to connect directly to the Moosend infrastructure and programmatically run many of the system’s capabilities from creating email lists to retrieving advanced real-time analytics in an easier, faster, and more efficient manner.
To get started, you need a Moosend account and an API key. By accessing the API endpoints, you can programmatically leverage the system’s core capabilities:
Email lists
Create, retrieve, update, or delete email lists and their details.
Create or update custom data included in the email lists.
Subscribers
Add up to 1000 subscribers with their custom data or retrieve them by ID or email address.
Remove subscribers or unsubscribe them from an email list or a campaign.
Campaigns
Create or clone campaigns, and efficiently retrieve their details and campaign senders.
Send a test campaign, schedule campaign delivery, or dispatch it immediately.
Retrieve campaign metrics such as link performance, opens, clicks, and A/B test results to make data-driven decisions.
Segments
Create, update, delete, and retrieve segments with their details and subscribers.
Getting started with the Moosend API
Abstract
Overview of how to get started with the Moosend API.
Before you can start using the Moosend API, you must have a Moosend account. Each account is associated with a specific role, such as Owner, Admin, Viewer, Manager, Designer, Admin observer, and GDPR viewer. The permissions specific to your role determine which resources and endpoints you can access with your API key.
Base URL
Abstract
Describes the base URL for all Moosend API endpoints.
All API request URLs referenced in this API documentation begin with the following base URL:
https://api.moosend.com/v3
The base URL includes the {hostname} which is api.moosend.com and the API version v3.
To make a request to a specific API endpoint, the path to the endpoint is added to the base URL.
For example, to make a request to get all active email lists in your account, create a GET request and add the specific endpoint path /lists to the base URL:
https://api.moosend.com/v3/lists
Authenticate a Moosend API request
Abstract
Overview of the authentication process and how to get your API key from your Moosend account.
All Moosend API requests are authenticated by providing your API key. Moosend provides your account with a unique key that can be found in your settings.
To get your API key:
Log in to your account.
On the menu bar, click More > Settings.
Click API key.
To copy your API key, click Copy.
Important
You must keep your API key secure to prevent any unauthorized access to your account. You can click Generate new API key to create a new API key if your account gets compromised.
When you obtain your API key, you can begin making calls to the Moosend API. The API key is a required query parameter in all API endpoints.
For example, if your API key is bafe55f4-e53e-4651-8164-c6d6ff05081b, then a sample request to get all campaigns looks like the following:
Describes the standard HTTP methods to use when making calls to the Moosend APIs.
The Moosend API uses the following standard HTTP methods for indicating the action to take on available resources:
GET - you can use this method to retrieve data from your account in our system. When you make a GET request, all request parameters are added to the request URL, in a format specific to the API call.
POST - you can use this method to send data to our system to modify data in your account. When you make a POST request, the request URL usually contains the response format and authentication, and the request stream contains hypothetical parameters for Name, Subject, SenderEmail, WebLocation, and MailingListID:
Describes the different types of request and response parameters that are used when making calls to the Moosend API.
When making an API request, you can pass different parameters to the API endpoints to determine the response. There are several types of request parameters: header parameters, path parameters, query parameters, and request body parameters.
Not all Moosend API endpoints contain each type of parameter. The API Reference details the specific request and response parameters for each API endpoint.
Header parameters
You must set the correct header parameters in every API request to retrieve the response data in the expected format and data type. The following headers are supported in Moosend API requests:
Request header
Value
Accept
application/json
application/xml
application/html+xml
Content-Type
application/json
For the response header parameter, only the JSON type is supported.
Request header
Value
Accept
application/json
Content-Type
application/json
Query parameters
You can use query parameters for filtering, pagination, and partial responses in the Moosend API. Query parameters are added to the request URL after the query string ?. You can add one or more query parameters separated by &.
The following is an example that shows three query parameters apikey, WithStatistics, and SortMethod.
The apikey is an example of a request query parameter that is required in all Moosend API endpoints.
Path parameters
You can use path parameters as identifiers to help you structure your requests. Path parameters appear within the path of the request URL before the query string ? and are usually indicated in curly brackets { }.
The following example shows three path parameters Page, PageSize, and Format:
Format is an example of a path parameter that is required in all Moosend API endpoints. There are only two available formats you can use in getting a response: xml and json.
Request body parameters
For POST requests, you must include a request body with parameters. You can find the details of request body parameters for each endpoint, including required fields in the API Reference.
The following is an example of a request body containing the Name, ConfirmationPage, and RedirectAfterUnsubscribePage parameters:
All responses to API calls include an HTTP status code, a response header, and a response schema with a JSON-formatted body. You can find the details of the response body parameters corresponding to each endpoint in the API Reference.
The following is an example of a JSON response body containing three parameters for Code, Error, and Context:
Describes the possible HTTP status codes returned in the Moosend API response.
The Moosend API returns standard HTTP success or error status codes. The following is a list of various HTTP status codes that the API returns:
HTTP status code
Description
200 OK
The request was successful.
201 Created
The request has been fulfilled and has resulted in one or more new resources being created.
202 Accepted
The request has been accepted for processing, but the processing has not been completed.
400 Bad Request
The server cannot process the request due to something that is perceived to be a client error.
API rate limiting
Abstract
Describes the API rate limiting enforced by Moosend to prevent having too many requests.
The Moosend API enforces rate limiting to prevent the API from being overwhelmed by too many requests. This means that it allows only a certain number of API calls from users within a given time. If a user sends too many requests, API rate limiting can throttle client connections.
The following table describes the current rate limit (number of requests per 10 seconds) per user (per API key):
The following is an example of a response when request submissions exceed the rate limit. When you go over the rate limit, you receive a RATE_LIMITING error in the response body.
Walkthrough: Create a mailing list and add subscribers
Abstract
Provides a walkthrough in making your first requests to the Moosend API to create a new email list and add multiple subscribers to the list.
This walkthrough shows how you can make your first calls to the Moosend API. When making API requests, you must always locate the specific API endpoints and parameters you need in API reference.
In this example, you create two requests using two API endpoints.
Send your API request. If successful, you get a response with HTTP code 200, a Content-Type: application/json response header, and the following JSON response:
The response body contains the Context parameter that gives you the ID of the new email list created. You can now use this ID to add subscribers to your new email list using the next API endpoint.
Add subscribers to your new email list using the API
Create a POST request using /subscribers/{MailingListID}/subscribe_many.{Format}.
Add your request header. You can use the following value: Content-Type:application/json.
Add the required path parameters in the request URL. Possible values for Format are json or xml. For MailingListID, use the ID of the new email list you created.
For example, if you select a JSON format and use the new email list ID, you can edit the URL as:
Add the required query parameter in the request URL after the ?.
For example, you can add your API key as https://{hostname}/v3/subscribers/6ca52d31-765c-4760-a78e-91e511e49d76/subscribe_many.json?apikey=bafe55f4-e53e-4651-8164-c6d6ff05081b
Add the required request body parameters for Subscribers. You must specify the Name, Email, and CustomEields for each subscriber on this list. Optionally, you can add the HasExternalDoubleOptIn parameter.
Send your API request. If successful, you get a response with HTTP code 200, a Content-Type: application/json response header, and the following JSON response:
{"Code":0,"Error":"2 items with invalid email address were ignored: email@email, email2@email","Context":[{"ID":"ca506fc5-0967-4756-8848-74e9766bdbdd","Name":"test1Email","Email":"test1@test.com","CreatedOn":"/Date(1465377493907+0100)/","UpdatedOn":"/Date(1465381164389)/","UnsubscribedOn":null,"UnsubscribedFromID":null,"SubscribeType":1,"SubscribeMethod":1,"CustomFields":[{"CustomFieldID":"42acf2cf-1096-4c80-960b-051791d9a276","Name":"Country","Value":"UK"}],"RemovedOn":null},{"ID":"b751f349-f6b3-4b14-8d75-c37dfafbe40a","Name":"test2133Email","Email":"test2133@test.com","CreatedOn":"/Date(1465377493907+0100)/","UpdatedOn":"/Date(1465381164389)/","UnsubscribedOn":null,"UnsubscribedFromID":null,"SubscribeType":1,"SubscribeMethod":1,"CustomFields":[{"CustomFieldID":"60d4e2b0-e5ae-4737-9ac5-ce071ab346fb","Name":"Age","Value":25},{"CustomFieldID":"42acf2cf-1096-4c80-960b-051791d9a276","Name":"Country","Value":"USA"}],"RemovedOn":null}]}
The response body contains the Context parameter that gives you the ID and details of each subscriber added to the new email list.
Introduction to segmentation
Abstract
Provides a basic description of segmentation and the query or expression used in Moosend API calls.
You can add segments to your email lists to send targeted email marketing campaigns. You can define a specific audience subset in your email lists using a segmentation query or expression to match the subscribers based on content engagement, location, language, and so on. You can have a single segmentation query or an expression consisting of multiple queries in complex or nested combinations.
A segmentation query or criterion consists of the following parts:
Comparer - the operator that defines how to compare a Field with its Value. Each field supports specific comparers based on the data type. See list of comparers.
Additional parameters:
MatchType - defines how to combine a group of queries or criteria. It specifies how subscribers are returned by your segment based on matching criteria. Possible values are:
All - returns subscribers that match all the given criteria.
Any - returns subscribers that match any of the given criteria.
FetchType -defines how many criteria-matching subscribers are contained in your segment. Possible values are:
All - returns all criteria-matching subscribers.
Top - returns only a maximum number of subscribers defined in FetchValue.
TopPercent - returns only a percentage of subscribers defined in FetchValue.
FetchValue - specifies the maximum number for FetchType:Top or percentage for FetchType:TopPercent of members to be contained in the created segment.
List of segmentation fields
Abstract
Lists the segmentation fields that are used in Moosend API segmentation expressions.
Segmentation queries or expressions can contain any combination of the Fields described in the following tables. You can use either the field name or the corresponding code in your JSON request body. Some fields accept these additional parameters:
Date Constrain - constrains the results based on a related date field.
OtherMailingListId - runs the query on another email list on members that are contained in both the current and the other email list.
CustomFieldId or CustomFieldName - used only with CustomField and specifies the custom field definition by the ID or the name for which the query applies. The custom field definition can be either one of the current email lists or the email list specified by the OtherMailingListId parameter.
Member fields
Code
Data type
Date constrain
OtherMailingListId
DateAdded
1
dateTime
Yes
DateUpdated
16
dateTime
Yes
RecipientName
2
string
Yes
RecipientEmail
3
string
SubscribeMethod
14
enum
Yes (SubscribedOn)
Yes
CustomField
99
string, decimal, dateTime, Boolean
Yes
MailingList
17
guid
Campaign fields
Code
Data type
Date constrain
OtherMailingListId
CampaignsOpened
4
integer
Yes (DeliveredOn)
Yes
LinksClicked
5
integer
Yes (DeliveredOn)
Yes
CampaignName
6
string
Yes (DeliveredOn)
Yes
CampaignTitle
20
string
Yes (Timestamp)
Yes
LinkURL
7
guid
Yes (DeliveredOn)
Yes
CampaignSent
15
guid
Yes (Timestamp)
Yes
OpenedAnyCampaign
24
Boolean
Yes (Timestamp)
Yes
CampaignID
19
guid
Yes (Timestamp)
Yes
SpecificCampaignClicked
26
string
Yes (Timestamp)
Yes
CampaignIdNotOpened
27
string
Yes
User agent fields
Code
Data type
Date constrain
OtherMailingListId
Platform
8
enum (Desktop = 1, Mobile = 2, Other = 3)
OperatingSystem
9
string
EmailClient
10
string
WebBrowser
11
string
MobileBrowser
12
string
Website fields
Code
Data type
Date constrain
OtherMailingListId
AddedAnythingToCart
21
Boolean + extra (CampaignId, ProductCode, WebsiteId, Times)
Yes (Timestamp)
Yes
ViewedProduct
22
Boolean + extra (CampaignId, ProductCode, WebsiteId, Times)
Yes (Timestamp)
Yes
PurchasedProduct
23
Boolean + extra (CampaignId, ProductCode, WebsiteId, Times)
Yes (Timestamp)
Yes
List of comparers
Abstract
Lists the comparers or operators that are used in Moosend API segmentation queries.
Query comparers or operators differ according to the data type of the field. The following table lists the supported operators for each data type. You can use either the name or the code in your JSON request body.
IsEmpty* and IsNotEmpty* are available when the field is nullable.
Operator
Code
String
Integer
Decimal
DateTime
Enum
Guid
Boolean
Is
0
+
+
+
+
+
+
IsNot
1
+
+
+
+
+
+
Contains
2
+
DoesNotContain
3
+
StartsWith
4
+
DoesNotStartWith
5
+
EndsWith
6
+
DoesNotEndWith
7
+
IsGreaterThan
8
+
+
IsGreaterThanOrEqualTo
9
+
+
IsLessThan
10
+
+
IsLessThanOrEqualTo
11
+
+
IsBefore
12
+
IsAfter
13
+
IsEmpty*
14
+
+
+
+
+
+
+
IsNotEmpty*
15
+
+
+
+
+
+
+
IsTrue
16
+
IsFalse
17
+
IsBetween
24
+
+
+
IsNotBetween
25
+
+
+
List of date functions
Abstract
Lists the date functions that are used in Moosend API segmentation fields.
The following table describes the DateFunction values that you can use with fields that have a DateTime data type. You can query based on a property of the date instead of the date itself. The calculation depends on the TimeZoneUsed parameter. Possible time zone values are Local or Utc. When Local is used, the user’s time zone offset is considered.
Function name
Code
Description
Year
1
The four-digit year part of the date.
Month
2
The month part of the date from 1 to 12.
Day
3
The day part of the date from 1 to 31.
WeekDay
4
The day of the week from 1 to 7. For example, 1 for Sunday, 2 for Monday, and so on.
DaysPassed
5
The number of days that have passed until now.
HoursPassed
6
The number of hours that have passed until now.
MinutesPassed
7
The number of minutes that have passed until now.
List of date constrain parameters
Abstract
Lists the date parameters that are used to constrain results of a Moosend API response based on the elapsed time or date span.
You can constrain the results of a Moosend API response based on the elapsed time or date span using the following parameters:
LastXMinutes - constrains the results by the time that has elapsed.
DateFrom and DateTo - constrain the results based on a specific date span.
API reference
The following sections provide the reference containing all the information required to work with the Moosend API endpoints:
Describes how to use the Moosend API to create, edit, and manage email lists in your account.
Use the Moosend API to get your email lists, get details about email lists, create, update, and delete email lists. You can also create, update, or remove custom fields in your email lists.
Get all active mailing lists
Abstract
Describes the request and response details of this Moosend API endpoint to get your active email lists.
GET /lists.{Format}
Retrieves a list of all the active email lists in your Moosend account.
Request
Parameter
In
Type
Required
Description
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml.
apikey
query
string
true
The API key of your account.
WithStatistics
query
string
false
Specifies whether to fetch statistics for the subscribers.
Possible values: true (Default) and false.
SortBy
query
string
false
The name of the email list property to sort results by.
Possible values: Name, Subject, Status, DeliveredOn, and CreatedOn (Default).
SortMethod
query
string
false
Specifies the method to sort results.
Possible values: DESC for descending and ASC (Default) for ascending.
Code - the response code. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - an object that contains all the Paging and MailingLists information for the requested email list:
Paging - an object that contains the following information:
PageSize - the page size of the results. This is 0 if not defined.
CurrentPage - the number of the result page. This is 1 if not defined.
Totalresults - the number of email lists that are included in the response.
TotalPageCount - the total number of available email list pages in your account.
SortExpression - the sort expression associated with the column or columns being sorted.
SortIsAscending - this is false if the results are not displayed in ascending order based on the sort expression.
MailingLists - a list of email lists in your account containing the following information for each email list:
ID -the ID of the email list.
Name - the name of the email list.
ActiveMemberCount - the number of active members in the email list.
BouncedMemberCount - the number of bounced emails in the email list.
RemovedMemberCount - the number of emails removed from the email list.
UnsubscribedMemberCount - the number of emails unsubscribed from the email list.
Status - status of the email list. For created, this is 0, for imported, this is 1, for importing, this is 2 , and for deleted, this is 3.
CustomFieldsDefinition - an array containing the parameters of custom fields in the email list. The parameters are:
ID - the ID of the custom field.
Name - the name of the custom field
Context - the context of the custom field. This is null if the field type is not SingleSelectDropDown.
IsRequired - this is true if the custom field is required and false if it is not.
Type - the data type of the custom field. Possible values: 0 for text, 1 for number, 2 for dateTime, 3 for SingleSelectDropDown, and 5 for checkbox.
CreatedBy - the IP address used to create the requested email list.
CreatedOn - the date-time the requested email list was created.
UpdatedBy - the IP address used to update the requested email list.
UpdatedOn - the date-time the requested email list was updated.
ImportOperation - an object that contains the details of the latest import operation performed in the requested email list. This is blank if there was no import done.
ID - the ID of the import operation.
DataHash - a globally unique identifier (GUID) for the import operation
Mappings - the data mappings used for the specific import operation.
EmailNotify - this is null if the import operation notification email was not selected to be sent
CreatedOn - the date-time when the import operation was created.
StartedOn - the date-time when the import operation was stated.
CompletedOn - the date-time when the import operation was completed.
TotalInserted - the total number of inserted emails.
TotalUpdated - the total number of updated emails.
TotalUnsubscribed - the total number of unsubscribed emails.
TotalInvalid - the total number of invalid emails.
TotalIgnored - the total number of ignored emails.
TotalDuplicate - the total number of duplicate emails.
TotalMembers - the total number of members that were selected to be imported.
Message - the message of the import operation. This is null if successful.
Success - this is true if successful.
SkipNewMembers - this is false if the skip new members option was not selected before the import operation began.
Preferences - an object that contains the details of the preferences field.
FallbackValue - this returns if the field has a fallback value.
IsRequired - this is true if the preferences field is required, and false if it is not.
Options - an object that contains all the Preferences options.
SelectType - this is the data type of the field. It is 0 for single-select and 1 for multi-select.
Request
GET https://{hostname}/v3/lists.{Format}?apikey=&WithStatistics=&SortBy=&SortMethod=
Describes the request and response details of this Moosend API endpoint to get your email list details.
GET /lists/{MailingListID}/details.{Format}
Retrieves the details about a specific email list in your account. You can include subscriber statistics in your results. Any segments existing in the requested email list are excluded from the results.
Request
Parameter
In
Type
Required
Description
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml.
MailingListID
path
string
true
The ID of the email list that contains the details you are requesting.
apikey
query
string
true
The API key of your account.
WithStatistics
query
string
false
Specifies whether to fetch statistics for the subscribers.
Code - the response code. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - an object that contains all the following information for the requested email list:
ID - the ID of the email list.
Name - the name of the email list.
ActiveMemberCount - the number of active members in the email list.
BouncedMemberCount - the number of bounced emails in the email list.
RemovedMemberCount - the number of emails removed from the email list.
UnsubscribedMemberCount - the number of emails unsubscribed from the email list.
Status - status of the email list. For created, this is 0, for imported, this is 1, for importing, this is 2 , and for deleted, this is 3.
CustomFieldsDefinition - an array containing the parameters of custom fields in the email list. The parameters are:
ID - the ID of the custom field.
Name - the name of the custom field
Context - the context of the custom field. This is null if the field type is not SingleSelectDropDown.
IsRequired - this is true if the custom field is required and false if it is not.
Type - the data type of the custom field. Possible values: 0 for text, 1 for number, 2 for dateTime, 3 for SingleSelectDropDown, and 5 for checkbox.
CreatedBy - the IP address used to create the requested email list.
CreatedOn - the date-time the requested email list was created.
UpdatedBy - the IP address used to update the requested email list.
UpdatedOn - the date-time the requested email list was updated.
ImportOperation - an object that contains the details of the latest import operation performed in the requested email list. This is blank if there was no import done.
ID - the ID of the import operation.
DataHash - a globally unique identifier (GUID) for the import operation
Mappings - the data mappings used for the specific import operation.
EmailNotify - this is null if the import operation notification email was not selected to be sent
CreatedOn - the date-time when the import operation was created.
StartedOn - the date-time when the import operation was stated.
CompletedOn - the date-time when the import operation was completed.
TotalInserted - the total number of inserted emails.
TotalUpdated - the total number of updated emails.
TotalUnsubscribed - the total number of unsubscribed emails.
TotalInvalid - the total number of invalid emails.
TotalIgnored - the total number of ignored emails.
TotalDuplicate - the total number of duplicate emails.
TotalMembers - the total number of members that were selected to be imported.
Message - the message of the import operation. This is null if successful.
Success - this is true if successful.
SkipNewMembers - this is false if the skip new members option was not selected before the import operation began.
Preferences - an object that contains the details of the preferences field.
FallbackValue - this returns if the field has a fallback value.
IsRequired - this is true if the preferences field is required, and false if it is not.
Options - an object that contains all the Preferences options.
SelectType - this is the data type of the field. It is 0 for single-select and 1 for multi-select.
Request
GET https://{hostname}/v3/lists/{MailingListID}/details.{Format}?apikey=&WithStatistics=
Describes the request and response details of this Moosend API endpoint to get your active email lists with paging information included.
GET /lists/{Page}/{PageSize}.{Format}
Retrieves a list of all the active email lists in your Moosend account with paging information. Because the results for this call could be quite big, you can add paging information as input.
Request
Parameter
In
Type
Required
Description
Page
path
number
false
The page that you want to get.
PageSize
path
number
false
The number of email lists per page.
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml.
apikey
query
string
true
The API key of your account.
SortBy
query
string
false
The name of the email list property to sort results by.
Possible values: Name, Subject, Status, DeliveredOn, and CreatedOn (Default).
SortMethod
query
string
false
Specifies the method to sort results.
Possible values: DESC for descending and ASC (Default) for ascending.
Code - the response code. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - an object that contains all the Paging and MailingLists information for the requested email list:
Paging - an object that contains the following information:
PageSize - the page size of the results. This is 0 if not defined.
CurrentPage - the number of the result page. This is 1 if not defined.
Totalresults - the number of email lists that are included in the response.
TotalPageCount - the total number of available email list pages in your account.
SortExpression - the sort expression associated with the column or columns being sorted.
SortIsAscending - this is false if the results are not displayed in ascending order based on the sort expression.
MailingLists - a list of email lists in your account containing the following information for each email list:
ID -the ID of the email list.
Name - the name of the email list.
ActiveMemberCount - the number of active members in the email list.
BouncedMemberCount - the number of bounced emails in the email list.
RemovedMemberCount - the number of emails removed from the email list.
UnsubscribedMemberCount - the number of emails unsubscribed from the email list.
Status - status of the email list. For created, this is 0, for imported, this is 1, for importing, this is 2 , and for deleted, this is 3.
CustomFieldsDefinition - an array containing the parameters of custom fields in the email list. The parameters are:
ID - the ID of the custom field.
Name - the name of the custom field
Context - the context of the custom field. This is null if the field type is not SingleSelectDropDown.
IsRequired - this is true if the custom field is required and false if it is not.
Type - the data type of the custom field. Possible values: 0 for text, 1 for number, 2 for dateTime, 3 for SingleSelectDropDown, and 5 for checkbox.
CreatedBy - the IP address used to create the requested email list.
CreatedOn - the date-time the requested email list was created.
UpdatedBy - the IP address used to update the requested email list.
UpdatedOn - the date-time the requested email list was updated.
ImportOperation - an object that contains the details of the latest import operation performed in the requested email list. This is blank if there was no import done.
ID - the ID of the import operation.
DataHash - a globally unique identifier (GUID) for the import operation
Mappings - the data mappings used for the specific import operation.
EmailNotify - this is null if the import operation notification email was not selected to be sent
CreatedOn - the date-time when the import operation was created.
StartedOn - the date-time when the import operation was stated.
CompletedOn - the date-time when the import operation was completed.
TotalInserted - the total number of inserted emails.
TotalUpdated - the total number of updated emails.
TotalUnsubscribed - the total number of unsubscribed emails.
TotalInvalid - the total number of invalid emails.
TotalIgnored - the total number of ignored emails.
TotalDuplicate - the total number of duplicate emails.
TotalMembers - the total number of members that were selected to be imported.
Message - the message of the import operation. This is null if successful.
Success - this is true if successful.
SkipNewMembers - this is false if the skip new members option was not selected before the import operation began.
Preferences - an object that contains the details of the preferences field.
FallbackValue - this returns if the field has a fallback value.
IsRequired - this is true if the preferences field is required, and false if it is not.
Options - an object that contains all the Preferences options.
SelectType - this is the data type of the field. It is 0 for single-select and 1 for multi-select.
Request
GET https://{hostname}/v3/lists/{Page}/{PageSize}.{Format}?apikey=&SortBy=&SortMethod=
Describes the request and response details of this Moosend API endpoint to create a custom field.
POST /lists/{MailingListID}/customfields/create.{Format}
Creates a new custom field in a specific email list.
Request
Parameter
In
Type
Required
Description
Accept
header
string
true
Determines the expected format and data type to retrieve the response data.
Value: application/json
MailingListID
path
string
true
The ID of the email list where the custom field is created.
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml.
apikey
query
string
true
The API key of your account.
Name
body
string
true
The name of the custom field.
CustomFieldType
body
string
false
Specifies the data type of the custom field. This must be one of the following values.
Text (Default) - accepts any text value as input.
Number - accepts only numeric values as input.
DateTime - accepts only date values as input, with or without time.
SingleSelectDropdown - accepts only values explicitly defined in a list.
CheckBox - accepts only values of true or false.
Options
body
string
false
If you want to create a SingleSelectDropdown custom field, you must set this parameter to specify the available options for the user to choose from. Use a comma (,) to separate different options.
IsRequired
body
Boolean
false
Specifies whether the custom field is mandatory or not when adding a subscriber to your list. You must specify a value of true or false (Default).
IsHidden
body
Boolean
false
Specifies whether the custom field is visible to your subscribers in the Update Profile page. You must specify a value of true or false (Default).
Describes the request and response details of this Moosend API endpoint to update a custom field.
POST /lists/{MailingListID}/customfields/{CustomFieldID}/update.{Format}
Updates the properties of a custom field in a specific email list.
Request
Parameter
In
Type
Required
Description
Accept
header
string
true
Determines the expected format and data type to retrieve the response data.
Value: application/json
MailingListID
path
string
true
The ID of the email list containing the custom field.
CustomFieldID
path
string
true
The ID of the custom field to be updated.
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml.
apikey
query
string
true
The API key of your account.
Name
body
string
true
The name of the custom field.
CustomFieldType
body
string
false
Specifies the data type of the custom field. This must be one of the following values.
Text (Default) - accepts any text value as input.
Number - accepts only numeric values as input.
DateTime - accepts only date values as input, with or without time.
SingleSelectDropdown - accepts only values explicitly defined in a list.
CheckBox - accepts only values of true or false.
Options
body
string
false
If you want to update a SingleSelectDropdown custom field, you must set this parameter to specify the available options for the user to choose from. Use a comma (,) to separate different options.
IsRequired
body
Boolean
false
Specifies whether the custom field is mandatory or not when adding a subscriber to your list. You must specify a value of true or false (Default).
IsHidden
body
Boolean
false
Specifies whether the custom field is visible to your subscribers in the Update Profile page. You must specify a value of true or false (Default).
Describes how to use the Moosend API to get, add, update, unsubscribe, and remove subscribers from email lists in your account.
Use the Moosend API to fetch your subscribers, get details about your subscribers, add, update, remove subscribers, and unsubscribe subscribers from email lists or campaigns.
Get all subscribers
Abstract
Describes the request and response details of this Moosend API endpoint to get all your subscribers.
GET /lists/{MailingListID}/subscribers/{Status}.{Format}
Retrieves a list of subscribers in a specific email list in your Moosend account. You can filter the list by status. Because this call can return a large number of results, you can add paging information as input.
Request
Parameter
In
Type
Required
Description
MailingListID
path
string
true
The ID of the email list containing the subscribers.
Status
path
string
true
Specifies the type of subscriber statistics results to return.
Possible values: Subscribed , Unsubscribed , Bounced, Removed.
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml.
apikey
query
string
true
The API key of your account.
Page
path
number
false
The page of subscriber statistics results to return.
PageSize
path
number
false
The page size of subscriber statistics results to return.
Code - the response code. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - an object that contains all the Paging and Subscribers information in the specific email list:
Paging - an object that contains the following information:
PageSize - the page size of the results. This is 0 if not defined.
CurrentPage - the number of the result page. This is 1 if not defined.
Totalresults - the number of all the subscribers that are included in the response.
TotalPageCount - the total number of available subscriber pages in your account.
SortExpression - the sort expression associated with the column or columns being sorted.
SortIsAscending - this is false if the results are not displayed in ascending order based on the sort expression.
Subscribers - a list of subscribers in the email list containing the following information for each subscriber:
ID - the ID of the subscriber.
Name - the name of the subscriber.
Email - the email address of the subscriber.
CreatedOn - the date-time the subscriber was added to the email list.
UnsubscribedOn - the date-time the subscriber was unsubscribed from the email list. This is null if not unsubscribed from the list.
UnsubscribedFromID - the ID that the subscriber is unsubscribed from.
SubscribeType - the status of the subscriber. For subscribed, this is 1, for unsubscribed, this is 2, for bounced, this is 3 , and for removed, this is 4.
SubscribeMethod - the method used to subscribe the member to the email list. For subscription forms, this is 0, for file imports, this is 1, for manually added, this is 2.
CustomFields - a list containing the custom fields of the new subscriber. Each custom field contains the following:
CustomFieldID - the ID of the custom field.
Name - the name of the custom field.
Value - the value of the custom field.
RemovedOn - the date-time the subscriber was removed from the email list.
Tags - a list containing the tags of the new subscriber.
Preferences - a list containing the preference values of the new subscriber.
Request
GET https://{hostname}/v3/lists/{MailingListID}/subscribers/{Status}.{Format}?apikey=&Page=&PageSize=
Describes the request and response details of this Moosend API endpoint to get a specific subscriber by email address.
GET /subscribers/{MailingListID}/view.{Format}
Retrieves the details about a subscriber by email address in a specific email list in your account. The response returns detailed information such as ID, name, date created, date unsubscribed, status, and custom fields.
Request
Parameter
In
Type
Required
Description
MailingListID
path
string
true
The ID of the email list that contains the subscriber.
Code - the response code. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - an object that contains all the following information for the requested subscriber:
ID - the ID of the subscriber.
Name - the name of the subscriber.
Email - the email address of the subscriber.
CreatedOn - the date-time the subscriber was added to the email list.
UnsubscribedOn - the date-time the subscriber was unsubscribed from the email list. This is null if not unsubscribed from the list.
UnsubscribedFromID - the ID that the subscriber is unsubscribed from.
SubscribeType - the status of the subscriber. For subscribed, this is 1, for unsubscribed, this is 2, for bounced, this is 3 , and for removed, this is 4.
SubscribeMethod - the method used to subscribe the member to the email list. For subscription forms, this is 0, for file imports, this is 1, for manually added, this is 2.
CustomFields - a list containing the custom fields of the new subscriber. Each custom field contains the following:
CustomFieldID - the ID of the custom field.
Name - the name of the custom field.
Value - the value of the custom field.
RemovedOn - the date-time the subscriber was removed from the email list.
Tags - a list containing the tags of the new subscriber.
Preferences - a list containing the preference values of the new subscriber.
Request
GET https://{hostname}/v3/subscribers/{MailingListID}/view.{Format}?apikey=&Email=
Describes the request and response details of this Moosend API endpoint to get a specific subscriber by ID.
GET /subscribers/{MailingListID}/find/{SubscriberID}.{Format}
Retrieves the details about a subscriber by ID in a specific email list in your account. The response returns detailed information such as ID, name, date created, date unsubscribed, status, and custom fields.
Request
Parameter
In
Type
Required
Description
MailingListID
path
string
true
The ID of the email list that contains the subscriber.
Code - the response code. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - an object that contains all the following information for the subscriber:
ID - the ID of the subscriber.
Name - the name of the subscriber.
Email - the email address of the subscriber.
CreatedOn - the date-time the subscriber was added to the email list.
UnsubscribedOn - the date-time the subscriber was unsubscribed from the email list. This is null if not unsubscribed from the list.
UnsubscribedFromID - the ID that the subscriber is unsubscribed from.
SubscribeType - the status of the subscriber. For subscribed, this is 1, for unsubscribed, this is 2, for bounced, this is 3 , and for removed, this is 4.
SubscribeMethod - the method used to subscribe the member to the email list. For subscription forms, this is 0, for file imports, this is 1, for manually added, this is 2.
CustomFields - a list containing the custom fields of the new subscriber. Each custom field contains the following:
CustomFieldID - the ID of the custom field.
Name - the name of the custom field.
Value - the value of the custom field.
RemovedOn - the date-time the subscriber was removed from the email list.
Tags - a list containing the tags of the new subscriber.
Preferences - a list containing the preference values of the new subscriber.
Request
GET https://{hostname}/v3/subscribers/{MailingListID}/find/{SubscriberID}.{Format}?apikey=
Describes the request and response details of this Moosend API endpoint to add a new subscriber to an email list.
POST /subscribers/{MailingListID}/subscribe.{Format}
Adds a new subscriber to a specific email list in your Moosend account. If the subscriber with the specified email address already exists in the list, the list is instead updated.
Note
When you add a single subscriber to an email list manually or through the API, the subscriber is added regardless of whether the subscriber has previously been unsubscribed.
Request
Parameter
In
Type
Required
Description
Accept
header
string
true
Determines the expected format and data type to retrieve the response data.
Value: application/json
MailingListID
path
string
true
The ID of the email list where you want to add a new subscriber.
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml.
apikey
query
string
true
The API key of your account.
Name
body
string
false
The name of the new subscriber.
Email
body
string
true
The email address of the new subscriber.
HasExternalDoubleOptIn
body
Boolean
false
When true, it flags the added subscriber as having given subscription consent by other means.
CustomFields
body
array
false
A list of name-value pairs that match the subscriber’s custom fields defined in the email list.
For example, if you have two custom fields for Age and Country, you must specify the values for these two fields.
Tags
body
object
false
The member tag you can use to filter members by when working with an email list.
Preferences
body
object
false
The member preferences you can use to segment or filter members by, when working with an email list.
Code - the response code. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - an object that contains all the following information for the new subscriber added to the email list:
ID - the ID of the subscriber.
Name - the name of the subscriber.
Email - the email address of the subscriber.
CreatedOn - the date-time the subscriber was added to the email list.
UnsubscribedOn - the date-time the subscriber was unsubscribed from the email list. This is null if not unsubscribed from the list.
UnsubscribedFromID - the ID that the subscriber is unsubscribed from.
SubscribeType - the status of the subscriber. For subscribed, this is 1, for unsubscribed, this is 2, for bounced, this is 3 , and for removed, this is 4.
SubscribeMethod - the method used to subscribe the member to the email list. For subscription forms, this is 0, for file imports, this is 1, for manually added, this is 2.
CustomFields - a list containing the custom fields of the new subscriber. Each custom field contains the following:
CustomFieldID - the ID of the custom field.
Name - the name of the custom field.
Value - the value of the custom field.
RemovedOn - the date-time the subscriber was removed from the email list.
Tags - a list containing the tags of the new subscriber.
Describes the request and response details of this Moosend API endpoint to add multiple subscribers to an email list in a single request.
POST /subscribers/{MailingListID}/subscribe_many.{Format}
Adds multiple subscribers to a specific email list in your Moosend account in a single request. Our API supports requests with up to 1000 records per batch.
If some subscribers with their specified email addresses already exist in the list, an update is done instead. If you add a subscriber with an invalid email address, it is ignored.
Request
Parameter
In
Type
Required
Description
Accept
header
string
true
Determines the expected format and data type to retrieve the response data.
Value: application/json
MailingListID
path
string
true
The ID of the email list where you want to add multiple subscribers.
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml.
apikey
query
string
true
The API key of your account.
HasExternalDoubleOptIn
body
Boolean
false
When true, it flags the added subscribers as having given their subscription consent by other means.
Subscribers
body
array
true
A list containing up to 1000 subscribers that you are adding to the email list. You must specify the Name, Email, and CustomFields for each subscriber.
Tags
body
object
false
The member tag you can use to filter members by when working with an email list.
Preferences
body
object
false
The member preferences you can user to segment or filter members by, when working with an email list.
Code - the response code. This is 0 if successful.
Errors - the response error message that shows how many and which emails are invalid. It is null if all emails are valid.
Context - an object that contains all the following information for each new subscriber added to the email list:
ID - the ID of the subscriber.
Name - the name of the subscriber.
Email - the email address of the subscriber.
CreatedOn - the date-time the subscriber was added to the email list.
UnsubscribedOn - the date-time the subscriber was unsubscribed from the email list. This is null if not unsubscribed from the list.
UnsubscribedFromID - the ID that the subscriber is unsubscribed from.
SubscribeType - the status of the subscriber. For subscribed, this is 1, for unsubscribed, this is 2, for bounced, this is 3 , and for removed, this is 4.
SubscribeMethod - the method used to subscribe the member to the email list. For subscription forms, this is 0, for file imports, this is 1, for manually added, this is 2.
CustomFields - a list containing the custom fields of the new subscriber. Each custom field contains the following:
CustomFieldID - the ID of the custom field.
Name - the name of the custom field.
Value - the value of the custom field.
RemovedOn - the date-time the subscriber was removed from the email list.
Tags - a list containing the tags of the new subscriber.
{"Code":0,"Error":"2 items with invalid email address were ignored: email@email, email2@email","Context":[{"ID":"ca506fc5-0967-4756-8848-74e9766bdbdd","Name":"test1Email","Email":"test1@test.com","CreatedOn":"/Date(1465377493907+0100)/","UpdatedOn":"/Date(1465381164389)/","UnsubscribedOn":null,"UnsubscribedFromID":null,"SubscribeType":1,"SubscribeMethod":1,"CustomFields":[{"CustomFieldID":"42acf2cf-1096-4c80-960b-051791d9a276","Name":"Country","Value":"UK"}],"RemovedOn":null,"Tags":["potential","repeater"]},{"ID":"b751f349-f6b3-4b14-8d75-c37dfafbe40a","Name":"test2133Email","Email":"test2133@test.com","CreatedOn":"/Date(1465377493907+0100)/","UpdatedOn":"/Date(1465381164389)/","UnsubscribedOn":null,"UnsubscribedFromID":null,"SubscribeType":1,"SubscribeMethod":1,"CustomFields":[{"CustomFieldID":"60d4e2b0-e5ae-4737-9ac5-ce071ab346fb","Name":"Age","Value":25},{"CustomFieldID":"42acf2cf-1096-4c80-960b-051791d9a276","Name":"Country","Value":"USA"}],"RemovedOn":null,"Tags":["potential","repeater"]}]}
Update a subscriber
Abstract
Describes the request and response details of this Moosend API endpoint to update a subscriber in your email list.
POST /subscribers/{MailingListID}/update/{SubscriberID}.{Format}
Updates the details of a subscriber in a specific email list in your Moosend account.
Request
Parameter
In
Type
Required
Description
Accept
header
string
true
Determines the expected format and data type to retrieve the response data.
Value: application/json
MailingListID
path
string
true
The ID of the email list that contains the subscriber.
SubscriberID
path
string
true
The ID of the subscriber that you want to update.
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml.
apikey
query
string
true
The API key of your account
Name
body
string
false
The name of the subscriber.
Email
body
string
true
The email address of the subscriber.
HasExternalDoubleOptIn
body
Boolean
false
When true, it flags the added subscriber as having given subscription consent by other means.
CustomFields
body
array
false
A list of name-value pairs that match the subscriber’s custom fields defined in the email list.
For example, if you have two custom fields for Age and Country, you must specify the values for these two fields.
Tags
body
object
false
The member tag you can use to filter members by when working with an email list.
Preferences
body
object
false
The member preferences you can user to segment or filter members by, when working with an email list.
Code - the response code. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - an object that contains all the following information for the updated subscriber:
ID - the ID of the subscriber.
Name - the name of the subscriber.
Email - the email address of the subscriber.
CreatedOn - the date-time the subscriber was added to the email list.
UnsubscribedOn - the date-time the subscriber was unsubscribed from the email list. This is null if not unsubscribed from the list.
UnsubscribedFromID - the ID that the subscriber is unsubscribed from.
SubscribeType - the status of the subscriber. For subscribed, this is 1, for unsubscribed, this is 2, for bounced, this is 3 , and for removed, this is 4.
SubscribeMethod - the method used to subscribe the member to the email list. For subscription forms, this is 0, for file imports, this is 1, for manually added, this is 2.
CustomFields - a list containing the custom fields of the new subscriber. Each custom field contains the following:
CustomFieldID - the ID of the custom field.
Name - the name of the custom field.
Value - the value of the custom field.
RemovedOn - the date-time the subscriber was removed from the email list.
Tags - a list containing the tags of the new subscriber.
Unsubscribe a subscriber from a mailing list and a campaign
Abstract
Describes the request and response details of this Moosend API endpoint to unsubscribe a subscriber from an email list and a campaign.
POST /subscribers/{MailingListID}/{CampaignID}/unsubscribe.{Format}
Unsubscribes a subscriber from a specific email list and campaign. This call considers the Unsubscribe settings in your Moosend account where you can specify whether to remove a subscriber from all other email lists.
Request
Parameter
In
Type
Required
Description
Accept
header
string
true
Determines the expected format and data type to retrieve the response data.
Value: application/json
MailingListID
path
string
true
The ID of the email list from which you want to unsubscribe a subscriber.
CampaignID
path
string
true
The ID of the campaign sent to the specific email list.
Describes the request and response details of this Moosend API endpoint to remove a subscriber from a specific email list.
POST /subscribers/{MailingListID}/remove.{Format}
Removes a subscriber from a specific email list permanently without moving the subscriber to the suppression list. The status of the subscriber is Archived.
Request
Parameter
In
Type
Required
Description
Accept
header
string
true
Determines the expected format and data type to retrieve the response data.
Value: application/json
MailingListID
path
string
true
The ID of the email list that contains the subscriber you want to remove.
Describes the request and response details of the Moosend API endpoint to remove multiple subscribers from a specific email list.
POST /subscribers/{MailingListID}/remove_many.{Format}
Removes multiple subscribers from a specific email list permanently without moving the subscribers to the suppression list. The status of each removed subscriber is Archived. Any invalid email addresses specified in the list are ignored.
Request
Parameter
In
Type
Required
Description
Accept
header
string
true
Determines the expected format and data type to retrieve the response data.
Value: application/json
MailingListID
path
string
true
The ID of the email list that contains the subscribers you want to remove.
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml.
apikey
query
string
true
The API key of your account.
Emails
body
object
true
A list of subscriber email addresses that you want to remove from the email list. Use a comma (,) to separate the email addresses.
Describes how to use the Moosend API to get, clone, update, delete, test, and send campaigns, including how to fetch campaign statistics.
Use the Moosend API to fetch your campaigns, get details about campaigns, fetch your campaign senders and their details, create, clone, update, delete, test, and send campaigns. The API also lets you fetch campaign statistics, activity by location, link activity, and campaign summaries.
Get all campaigns by page
Abstract
Describes the request and response details of this Moosend API endpoint to get all campaigns in your account with paging information.
GET /campaigns/{Page}.{Format}
Retrieves a list of all campaigns in your Moosend account with detailed information. Because the results for this call could be quite big, you can add paging information as input.
Code - the response code. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - an object that contains all the information for the requested campaigns:
Paging - an object that contains the following information:
PageSize - the page size of the results. This is 0 if not defined.
CurrentPage - the number of the result page. This is 1 if not defined.
Totalresults - the number of campaigns that are included in the response.
TotalPageCount - the number of all the available campaign pages for your account.
SortExpression - the sort expression associated with the column or columns being sorted.
SortIsAscending - this is false if the results are not displayed in ascending order based on the sort expression.
ID - the ID of the campaign.
Name - the name of the campaign.
Subject - the subject of the campaign.
SiteName - the site name of the account.
ConfirmationTo - the email address to which a confirmation message is sent when the campaign has been successfully sent.
CreatedOn - the date-time the requested campaign was created.
ABHoursToTest - specifies the total number of hours to test versions A and B of your campaign before sending the winning version. This is null if the campaign is not an A/B split test campaign.
ABCampaignType - specifies the type of the A/B split campaign test. Possible values are:
0 - for a campaign sender test.
1 - for a campaign content test.
2 - for a subject line test.
ABWinner - specifies if the winning campaign is A or B. This is null if the campaign is not an A/B split test campaign.
ABWinnerSelectionType - specifies the method to determine the winning version for the test. This is null if the given campaign is not an A/B split test campaign, or one of the following values if it is:
0 - the campaign version with the highest number of unique opens is selected to be sent to the rest of your list.
1 - the campaign version with the highest number of unique clicks is selected to be sent to the rest of your list.
Status - status of the campaign. Possible values are the following:
0 - draft
1 - queued for sending
3 - sent
4 - not enough credits
5 - awaiting delivery
6 - sending
10 - deleted
11 - selecting a winner
12 - archived
13 - subscription expired
14 - subscription limits exceeded
DeliveredOn - the date-time the campaign was delivered.
ScheduledFor - the date-time the campaign is scheduled to be delivered.
ScheduledForTimezone - the selected time zone for the scheduled campaign to be delivered.
CampaignType - the type of campaign which has been created or sent.
Regular
Digest - Rss or Repeatable
Transactional
Automation
MailingLists - a list of email lists selected for sending the campaign. It contains the following information for each email list:
Campaign - the campaign associated with this email list. This is null for this case.
MailingList - an object that contains the following information for each email list:
ID - the ID of the email list.
Name - the name of the email list.
ActiveMemberCount - the number of active members in the email list.
BouncedMemberCount - the number of bounced emails in the email list.
RemovedMemberCount - the number of removed emails in the email list.
UnsubscribedMemberCount - the number of unsubscribed emails in the email list.
Status - status of the email list. For created, this is 0, for imported, this is 1, for importing, this is 2 , and for deleted, this is 3.
CustomFieldsDefinition - an array containing the parameters of custom fields in the email list.
CreatedBy - the IP address used to create the email list.
CreatedOn - the date-time the email list was created.
UpdatedBy - the IP address used to update the email list.
UpdatedOn - the date-time that the email list was updated.
ImportOperation - an object that contains the details of the latest import operation performed in the email list.
Segment - a list of segments in the email list containing the following information for each segment. This is null if the campaign was not sent to any email list segment.
ID - the ID of the segment.
Name - the name of the segment.
MatchType - specifies how subscribers are returned by your segment based on matching criteria. Possible values are:
0 - for All. Returns subscribers that match all the given criteria.
1 - for Any. Returns subscribers that match any of the given criteria.
Criteria - contains a list with information for each selected criterion selected for the segment.
CreatedBy - the IP address used to create the segment.
CreatedOn - the date-time the requested segment was created.
UpdatedBy - the IP address used to update the segment.
UpdatedOn - the date-time the segment was updated.
FetchType - the selected fetch type for the selected segment criteria. Possible values are:
0 - for all segment criteria.
1 - for the top segment criteria.
2 - for the top percent segment criteria.
Description - contains a string representation of all the selected filters, MatchType criteria, and FetchType criteria.
TotalSent - the total number of campaign emails sent.
TotalOpens - the total number of emails opens.
UniqueOpens - the total number of unique email opens.
TotalBounces - the total number of email bounces.
TotalForwards - the total number of email forwards for the campaign using the Forward to a friend personalization tag.
UniqueForwards - the total number of unique forwards for the campaign using the Forward to a friend personalization tag.
TotalLinkClicks - the total number of link clicks.
UniqueLinkClicks - the total number of unique link clicks.
RecipientsCount - the total number of recipients.
IsTransactional - this is false for this case.
TotalComplaints - the total number of complaints.
TotalUnsubscribes - the total number of unsubscribed recipients for the campaign.
Request
GET https://{hostname}/v3/campaigns/{Page}.{Format}?apikey=
{"Code":0,"Error":null,"Context":{"Paging":{"PageSize":10,"CurrentPage":1,"TotalResults":2,"TotalPageCount":1,"SortExpression":null,"SortIsAscending":true},"Campaigns":[{"ID":"cbcb297d-52a8-4bed-ae85-640c37c92771","Name":"Test Release 1","Subject":"Test Release 1","SiteName":"mysite","ConfirmationTo":"andreas@email.com","CreatedOn":"/Date(1464952661697+0100)/","ABHoursToTest":null,"ABCampaignType":null,"ABWinner":null,"ABWinnerSelectionType":null,"Status":3,"DeliveredOn":"/Date(1464952817450+0100)/","ScheduledFor":null,"ScheduledForTimezone":"GTB Standard Time","MailingLists":[{"Campaign":null,"MailingList":{"ID":"dce99b7a-2619-4805-aaeb-7fecdcb3c71b","Name":"Some Name","ActiveMemberCount":0,"BouncedMemberCount":0,"RemovedMemberCount":0,"UnsubscribedMemberCount":0,"Status":0,"CustomFieldsDefinition":[],"CreatedBy":"212.205.224.198","CreatedOn":"/Date(1464952667680+0100)/","UpdatedBy":"212.205.224.198","UpdatedOn":"/Date(1464952667680+0100)/","ImportOperation":null},"Segment":null}],"TotalSent":1,"TotalOpens":1,"UniqueOpens":1,"TotalBounces":0,"TotalForwards":0,"UniqueForwards":0,"TotalLinkClicks":0,"UniqueLinkClicks":0,"RecipientsCount":1,"IsTransactional":false,"TotalComplaints":0,"TotalUnsubscribes":0,"CampaignSource":null,"CampaignType":"Digest"},{"ID":"ef2ab040-aec8-46bf-be54-3d8311093015","Name":"Performance Testing","Subject":"Performance Testing","SiteName":"mysite","ConfirmationTo":"info@northweb.biz","CreatedOn":"/Date(1464647633330+0100)/","ABHoursToTest":null,"ABCampaignType":null,"ABWinner":null,"ABWinnerSelectionType":null,"Status":3,"DeliveredOn":"/Date(1464647633207+0100)/","ScheduledFor":null,"ScheduledForTimezone":"GTB Standard Time","MailingLists":[{"Campaign":null,"MailingList":{"ID":"9b7611be-d395-4677-9983-697d261cca91","Name":"Performance Testing","ActiveMemberCount":0,"BouncedMemberCount":0,"RemovedMemberCount":0,"UnsubscribedMemberCount":0,"Status":0,"CustomFieldsDefinition":[],"CreatedBy":"127.0.0.1","CreatedOn":"/Date(1464647633220+0100)/","UpdatedBy":"127.0.0.1","UpdatedOn":"/Date(1464647633220+0100)/","ImportOperation":null},"Segment":null}],"TotalSent":0,"TotalOpens":0,"UniqueOpens":0,"TotalBounces":0,"TotalForwards":0,"UniqueForwards":0,"TotalLinkClicks":0,"UniqueLinkClicks":0,"RecipientsCount":18561,"IsTransactional":false,"TotalComplaints":0,"TotalUnsubscribes":0,"CampaignSource":null,"CampaignType":"Digest"}]}}
Get all campaigns by page and page size
Abstract
Describes the request and response details of this Moosend API endpoint to get all campaigns in your account with paging and page size information.
GET /campaigns/{Page}/{PageSize}.{Format}
Retrieves a list of all campaigns in your Moosend account with detailed information. Because the results for this call could be quite big, you can add paging and sorting information as inputs.
Request
Parameter
In
Type
Required
Description
Page
path
number
false
The page number to display results for. Returns the first page if not specified.
PageSize
path
number
false
The maximum number of results per page. This must be a positive integer up to 1000.
Returns 10 results per page if not specified. If a value greater than 1000 is specified, it is treated as 1000.
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml.
apikey
query
string
true
The API key of your account.
SortBy
query
string
false
The name of the campaign property to sort results by.
Possible values: Name, Subject, Status, DeliveredOn, and CreatedOn (Default).
SortMethod
query
any
false
Specifies the method to sort results.
Possible values: DESC for descending and ASC (Default) for ascending.
Code - the response code. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - an object that contains all the information for the requested campaigns:
Paging - an object that contains the following information:
PageSize - the page size of the results. This is 0 if not defined.
CurrentPage - the number of the result page. This is 1 if not defined.
Totalresults - the number of campaigns that are included in the response.
TotalPageCount - the number of all the available campaign pages for your account.
SortExpression - the sort expression associated with the column or columns being sorted.
SortIsAscending - this is false if the results are not displayed in ascending order based on the sort expression.
ID - the ID of the campaign.
Name - the name of the campaign.
Subject - the subject of the campaign.
SiteName - the site name of the account.
ConfirmationTo - the email address to which a confirmation message is sent when the campaign has been successfully sent.
CreatedOn - the date-time the requested campaign was created.
ABHoursToTest - specifies the total number of hours to test versions A and B of your campaign before sending the winning version. This is null if the campaign is not an A/B split test campaign.
ABCampaignType - specifies the type of the A/B split campaign test. Possible values are:
0 - for a campaign sender test.
1 - for a campaign content test.
2 - for a subject line test.
ABWinner - specifies if the winning campaign is A or B. This is null if the campaign is not an A/B split test campaign.
ABWinnerSelectionType - specifies the method to determine the winning version for the test. This is null if the given campaign is not an A/B split test campaign, or one of the following values if it is:
0 - the campaign version with the highest number of unique opens is selected to be sent to the rest of your list.
1 - the campaign version with the highest number of unique clicks is selected to be sent to the rest of your list.
Status - status of the campaign. Possible values are the following:
0 - draft
1 - queued for sending
3 - sent
4 - not enough credits
5 - awaiting delivery
6 - sending
10 - deleted
11 - selecting a winner
12 - archived
13 - subscription expired
14 - subscription limits exceeded
DeliveredOn - the date-time the campaign was delivered.
ScheduledFor - the date-time the campaign is scheduled to be delivered.
ScheduledForTimezone - the selected time zone for the scheduled campaign to be delivered.
CampaignType - the type of campaign which has been created or sent.
Regular
Digest - Rss or Repeatable
Transactional
Automation
MailingLists - a list of email lists selected for sending the campaign. It contains the following information for each email list:
Campaign - the campaign associated with this email list. This is null for this case.
MailingList - an object that contains the following information for each email list:
ID - the ID of the email list.
Name - the name of the email list.
ActiveMemberCount - the number of active members in the email list.
BouncedMemberCount - the number of bounced emails in the email list.
RemovedMemberCount - the number of removed emails in the email list.
UnsubscribedMemberCount - the number of unsubscribed emails in the email list.
Status - status of the email list. For created, this is 0, for imported, this is 1, for importing, this is 2 , and for deleted, this is 3.
CustomFieldsDefinition - an array containing the parameters of custom fields in the email list.
CreatedBy - the IP address used to create the email list.
CreatedOn - the date-time the email list was created.
UpdatedBy - the IP address used to update the email list.
UpdatedOn - the date-time that the email list was updated.
ImportOperation - an object that contains the details of the latest import operation performed in the email list.
Segment - a list of segments in the email list containing the following information for each segment. This is null if the campaign was not sent to any email list segment.
ID - the ID of the segment.
Name - the name of the segment.
MatchType - specifies how subscribers are returned by your segment based on matching criteria. Possible values are:
0 - for All. Returns subscribers that match all the given criteria.
1 - for Any. Returns subscribers that match any of the given criteria.
Criteria - contains a list with information for each selected criterion selected for the segment.
CreatedBy - the IP address used to create the segment.
CreatedOn - the date-time the requested segment was created.
UpdatedBy - the IP address used to update the segment.
UpdatedOn - the date-time the segment was updated.
FetchType - the selected fetch type for the selected segment criteria. Possible values are:
0 - for all segment criteria.
1 - for the top segment criteria.
2 - for the top percent segment criteria.
Description - contains a string representation of all the selected filters, MatchType criteria, and FetchType criteria.
TotalSent - the total number of campaign emails sent.
TotalOpens - the total number of emails opens.
UniqueOpens - the total number of unique email opens.
TotalBounces - the total number of email bounces.
TotalForwards - the total number of email forwards for the campaign using the Forward to a friend personalization tag.
UniqueForwards - the total number of unique forwards for the campaign using the Forward to a friend personalization tag.
TotalLinkClicks - the total number of link clicks.
UniqueLinkClicks - the total number of unique link clicks.
RecipientsCount - the total number of recipients.
IsTransactional - this is false for this case.
TotalComplaints - the total number of complaints.
TotalUnsubscribes - the total number of unsubscribed recipients for the campaign.
Request
GET https://{hostname}/v3/campaigns/{Page}/{PageSize}.{Format}?apikey=&SortBy=&SortMethod=
Code - the response code. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - an object that contains all the following information for the requested campaign:
ID - the ID of the campaign.
Name - the name of the campaign.
Subject - the subject of the campaign.
WebLocation - the web location of the HTML campaign.
HTMLContent - the HTML content of the campaign.
PlainContent - the content of the campaign in plain text.
Sender - a list that contains the following information about the campaign sender:
ID - the ID of the sender.
Name - the name of the sender.
Email - the email address of the sender.
CreatedOn - the date that the sender was created.
IsEnabled - this is true if the sender is enabled and false if it is not.
SpfVerified - this is true if the SPF record for the sender is enabled and false if it is not.
DkimVerified - this is true if the DKIM record for the sender is enabled and false if it is not.
DkimPublic - specifies the sender's email public DKIM.
DeliveredOn - the date-time the campaign was delivered. This is null for a cloned campaign.
ReplyToEmail - an object that contains details about the Reply to email address selected to receive replies from the campaign:
ID - the ID of the Reply to email receiver.
Name - the name of the Reply to email receiver.
Email - the email address of the Reply to email receiver.
CreatedOn - the date that the Reply to email receiver was created.
IsEnabled - this is true if the Reply to email receiver is enabled and false if it is not.
SpfVerified - this is true if the SPF record for the Reply to email receiver is enabled and false if it is not.
DkimVerified - this is true if the DKIM record for the Reply to email receiver is enabled and false if it is not.
DkimPublic - specifies the Reply to email receiver's email public DKIM.
CreatedOn - the date-time the campaign was created.
UpdatedOn - the date-time the campaign was updated.
ScheduledFor - the date-time the campaign is scheduled to be delivered. This is null for a cloned campaign.
TimeZone - the selected time zone for the account.
FormatType - the format type of the campaign. This is 0 for HTML, 1 for Template, and 2 for Plain Text.
ABCampaignData - this is null if the campaign is a regular campaign. If the campaign is an A/B split campaign, the object contains the following information :
ID - the four-digit integer ID of the ABCampaignData.
SubjectB - if the A/B split campaign is testing the subject, this is the subject line for campaign B.
PlainContentB - if the A/B split campaign is testing the content, this is the plain text content for campaign B.
HTMLContentB - if the A/B split campaign is testing the content, this is the HTML content for campaign B.
WebLocationB - if the A/B split campaign is testing the content, this is the web location for campaign B.
SenderB - if the A/B split campaign is testing the sender, this is campaign B's sender.
HoursToTest - the total number of hours to test campaigns A and B of your split test before sending the winning version.
ListPercentage - specifies the size of your test group in your list.
ABCampaignType - specifies the type of A/B split campaign. This is 0 for sender, 1 for content, and 2 for subject line
ABWinnerSelectionType - specifies the type of test that defines the winning version of the campaign. This is 0 for a unique opens test and 1 for a unique clicks test.
DeliveredOnA - the date-time campaign A was delivered. This is null for a cloned campaign.
DeliveredOnB - the date-time campaign B was delivered. This is null for a cloned campaign.
MailingLists - a list that contains the email lists or segments that that campaign is sent to.
MailingListID - the ID of the email list.
SegmentID - the ID of the selected segment. This is 0 if there is no segment selected.
ConfirmationTo - the email address to which a confirmation message is sent when the campaign has been successfully sent.
Status - status of the campaign.
IsTransactional - specifies whether the campaign was created using SMTP. This can be true or false.
Request
GET https://{hostname}/v3/campaigns/{CampaignID}/view.{Format}?apikey=
{"Code":0,"Error":null,"Context":{"ID":"2fa129d1-a0ab-467a-ab3e-e43fd9f6bfb","Name":"Test","Subject":"Test","WebLocation":null,"HTMLContent": someHtmlContent,"PlainContent": somePlainContent,"Sender":{"ID":"28a7ee75-034a-44e0-a946-fe28fc229d6e","Name":"Fanis","Email":"some@memail.com","CreatedOn":"/Date(1457684250090+0100)/","IsEnabled":true,"SpfVerified":false,"DkimVerified":true,"DkimPublic":"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDmO"},"DeliveredOn":"/Date(1464339959683+0100)/","ReplyToEmail":{"ID":"28a7ee75-034a-4110-a9116-fe34235re6e","Name":"Fanis","Email":"some@email.com","CreatedOn":"/Date(1457684250090+0100)/","IsEnabled":true,"SpfVerified":false,"DkimVerified":true,"DkimPublic":"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDmO"},"CreatedOn":"/Date(1464339921630+0100)/","UpdatedOn":"/Date(1464339949343+0100)/","ScheduledFor":null,"Timezone":"GTB Standard Time","FormatType":0,"ABCampaignData":null,"MailingLists":[{"MailingListID":"ad4b18-3sd0-4e1a-a110-481080fa94","SegmentID":0}],"ConfirmationTo":"some@email.com","Status":3,"IsTransactional":false}}
Get all senders
Abstract
Describes the request and response details of this Moosend API endpoint to get senders of a specific campaign.
GET /senders/find_all.{Format}
Retrieves a list of all the active campaign senders in your Moosend account.
Describes the request and response details of this Moosend API endpoint to create a draft campaign.
POST /campaigns/create.{Format}
Creates a new draft campaign in your account that is ready for sending or testing. You can create either a regular campaign or an A/B split campaign. The campaign content must be specified from a web location or by pasting the complete HTML body of your campaign. If you are creating a regular campaign, you can ignore the A/B split campaign parameters.
Request
Parameter
In
Type
Required
Description
Accept
header
string
true
Determines the expected format and data type to retrieve the response data.
Value: application/json
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml
apikey
query
string
true
The API key of your account.
Name
body
string
true
The name of the campaign.
Subject
body
string
true
The subject line of the campaign.
SenderEmail
body
string
true
The email address of the campaign sender.
ReplyToEmail
body
string
true
The email address selected to receive replies from the campaign. This must be one of your campaign senders. If not specified, the SenderEmail is assumed.
ConfirmationToEmail
body
string
false
The email address used to send a confirmation message when the campaign has been successfully sent. This can be any valid email address. If not specified, the SenderEmail is assumed.
HTMLContent
body
string
false
The complete HTML body of the campaign. You can use this parameter instead of using the WebLocation parameter.
WebLocation
body
string
false
The URL used to retrieve the HTML content of the campaign. Moosend automatically moves all CSS inline.
MailingLists
body
array
false
A list of email lists in your account that is used to send the campaign.
SegmentID
body
string
false
The ID of a segment in the selected email list. If not specified, the campaign is sent to all active subscribers of the email list.
IsAB
body
Boolean
true
A flag that defines if a campaign is an A/B split campaign. If true, you must fill out A/B split campaign parameters.
TrackInGoogleAnalytics
body
Boolean
false
Specifies if tracking is enabled for the campaign. You must have Google Analytics configured on your site to use this feature.
A/B split campaign parameters
Use these parameters when creating an A/B split campaign. If you specify any of the parameters below when creating a regular campaign, they are ignored in the request.
Parameter
In
Type
Required
Description
ABCampaignType
body
string
true
Specify the type of test to be performed in the AB split campaign to determine the winning version:
Subjectline - test two different versions of the subject line.
Content - test two different versions of the campaign content.
Sender - test two different versions of the campaign sender.
SubjectB
body
string
false
If testing A/B split campaigns with two subject line versions, this is the second subject version of the subject.
HTMLContentB
body
string
false
If testing A/B split campaigns with two HTML content versions, this is the complete HTML body of the second version.
WebLocationB
body
string
false
If testing A/B split campaigns with two HTML content versions, this is the web location of the second HTML content version.
SenderEmailB
body
string
false
If testing A/B split campaigns with two sender versions, this is the email address of the second campaign sender. This must be one of the senders defined in your account.
HoursToTest
body
integer
false
Specify how long the test runs, before determining the winning campaign version to be sent to the rest of the recipients.
This must be an integer between 1 and 24.
ListPercentage
body
integer
false
Specifies a portion of the target recipients to get the test campaign versions. For example, if you specify 10, then 10% of your recipients receive campaign A and another 10% receive the campaign B version.
This must be an integer between 5 and 40.
ABWinnerSelectionType
body
string
false
Specifies the method to determine the winning version for the test. If not set, OpenRate is assumed.
OpenRate - determine the winner based on the version that achieved more opens.
TotalUniqueClicks - determine the winner based on the version that achieved more unique link clicks.
Describes the request and response details of this Moosend API endpoint to create a transactional campaign.
Post https://{hostname}/v3/campaigns/transactional/send.{format}?apikey=
Sends a test for a existing transactional campaign or creates a new transactional campaign in your account that is ready for sending or testing. You can add content by either creating a campaign inside Moosend and designing the template in the editor (provide the template ID), by providing the HTML body in the API, or by providing a web location.
If a TemplateId is not provided and the TemplateName exists within the platform, the existing campaign will be sent. If the TemplateId is not provided and the TemplateName does not exist within the platform, a new transactional campaign will be created. The payload size provided per API call must be less than 20MB.
Request
Parameter
In
Type
Required
Description
Accept
header
string
true
Determines the expected format and data type to retrieve the response data.
Value: application/json
apikey
query
string
true
The API key of your account.
From
body
object
false
An array containing the parameters of the sender:
Email - the email address of a verified sender.
sendersName - the name of the sender name displayed in the recipient's inbox.
ReplyTo
body
object
false
An array containing the parameters of the sender the user can reply to:
Email - the email address of one of a verified sender.
sendersName - the name of the Reply to email displayed to the user when the user clicks Reply.
Subject
body
string
true
The subject line of the email message displayed to the recipient. It may contain parameters for personalization. When no value is provided, use the subject of the template.
TemplateId
body
GUID
false
Statistics will be registered to the campaign with this ID. If you have created a template id, you can find it in the user interface.
If the array content is empty or doesn’t exist, then the content for the email is taken from the template id provided.
TemplateName
body
string
false
The name of the transactional campaign that this message will be sent for. Transactional campaign names are unique.
If the array content is empty or doesn’t exist, then the content for the email is taken from the template name provided.
Content
body
array
false
Content types:
Type - the type of content to send.
Value - the format specified by content.type. It may contain parameters to be substituted for each recipient, according to the parameters given in the personalization property.
WebLocation - the URL that holds the content to use for this this message. To reuse it for the next requests and avoid re-downloading, cache it to S3 for 24 hours.
Only one content should exist in the payload for the call to be valid. If there is a content and template ID or name, then the content overrules and the template ID is kept to show the location of the statistics.
Personalizations
body
array
true
A list of recipients of the transactional message. It may contain personalization parameters.
To - an array containing the parameters of the receiver
Email - the recipient email address (text/plain).
Name - the recipient name (text/plain).
Substitutions - the values to substitute in the message content/subject for the current recipient, in the form of key/value pairs.
MailSettings
body
array
true
When set to true or omitted, the message will be delivered to the recipient, even if they have unsubscribed from the transactional email list.
Default: true
BypassUnsubscribeManagement
Enable - true (default) / false
attachments
body
object
false
An array containing the parameters of the attachments: -
Content - A base64 string that represents the file bytes of the attachment (Required).
Type - The MIME type of the attached content (e.g. application/pdf, image/PNG) (Required).
FileName - The file name of the attachment that the recipient will see (Required).
Code - the response code. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - an object that contains all the following information for the cloned campaign:
ID - the ID of the cloned campaign.
Name - the name of the campaign.
Subject- the subject of the campaign.
WebLocation - the web location of the HTML campaign.
HTMLContent - the HTML content of the campaign.
PlainContent - the content of the campaign in plain text.
Sender - a list that contains the following information about the campaign sender:
ID - the ID of the sender.
Name - the name of the sender.
Email - the email address of the sender.
CreatedOn - the date that the sender was created.
IsEnabled - this is true if the sender is enabled and false if it is not.
SpfVerified - this is true if the SPF record for the sender is enabled and false if it is not.
DkimVerified - this is true if the DKIM record for the sender is enabled and false if it is not.
DkimPublic - specifies the sender's email public DKIM.
DeliveredOn - the date-time the campaign was delivered. This is null for a cloned campaign.
ReplyToEmail - an object that contains details about the Reply to email address selected to receive replies from the campaign:
ID - the ID of the Reply to email receiver.
Name - the name of the Reply to email receiver.
Email - the email address of the Reply to email receiver.
CreatedOn - the date that the Reply to email receiver was created.
IsEnabled - this is true if the Reply to email receiver is enabled and false if it is not.
SpfVerified - this is true if the SPF record for the Reply to email receiver is enabled and false if it is not.
DkimVerified - this is true if the DKIM record for the Reply to email receiver is enabled and false if it is not.
DkimPublic - specifies the Reply to email receiver's email public DKIM.
CreatedOn - the date-time the campaign was created.
UpdatedOn - the date-time that the campaign was updated.
ScheduledFor - the date-time the campaign is scheduled to be delivered. This is null for a cloned campaign.
TimeZone - the selected time zone for the account.
FormatType - the format type of the campaign. This is 0 for HTML, 1 for Template, and 2 for Plain Text.
ABCampaignData : This is null if the cloned campaign is a regular campaign. If the cloned campaign is an A/B split campaign, the object contains the following information:
ID - the four-digit integer ID of the ABCampaignData.
SubjectB - if the A/B split campaign is testing the subject, this is the subject line for campaign B.
PlainContentB - if the A/B split campaign is testing the content, this is the plain text content for campaign B.
HTMLContentB - if the A/B split campaign is testing the content, this is the HTML content for campaign B.
WebLocationB - if the A/B split campaign is testing the content, this is the web location for campaign B.
SenderB - if the A/B split campaign is testing the sender, this is campaign B's sender.
HoursToTest - the total number of hours to test campaigns A and B of your split test before sending the winning version.
ListPercentage - specifies the size of your test group in your list.
ABCampaignType - specifies the type of A/B split campaign. This is 0 for sender, 1 for content, and 2 for subject line
ABWinnerSelectionType - specifies the type of test that defines the winning version of the campaign. This is 0 for a unique opens test and 1 for a unique clicks test.
DeliveredOnA - the date-time campaign A was delivered. This is null for a cloned campaign.
DeliveredOnB - the date-time campaign B was delivered. This is null for a cloned campaign.
MailingLists - a list that contains the email lists or segments that that campaign is sent to.
MailingListID - the ID of the email list.
SegmentID - the ID of the selected segment. This is 0 if there is no segment selected.
ConfirmationTo - the email address to which a confirmation message is sent when the campaign has been successfully sent.
Status - status of the campaign. The cloned campaign has 0 for status.
IsTransactional - specifies whether the campaign was created using SMTP. This can be true or false.
Request
POST https://{hostname}/v3/campaigns/{CampaignID}/clone.{Format}?apikey=
Request
curl --include \--request POST \'https://{hostname}/v3/campaigns/{CampaignID}/clone.{Format}?apikey='
Response
json
{"Code":0,"Error":null,"Context":{"ID":"248f97f5-1e5f-4e17-8fa8-818dc112be10","Name":"Test","Subject":"Test","WebLocation":"http://www.your-domain.com/newsletter","HTMLContent":"Some html content","PlainContent":"Plain context ... ","Sender":{"ID":"e9d2ed56-fc20-4337-bb6a-8b5884e8dfa6","Name":"Test","Email":"test@email.com","CreatedOn":"/Date(1457526079160+0100)/","IsEnabled":true,"SpfVerified":false,"DkimVerified":true,"DkimPublic":"sender email dkim public"},"DeliveredOn":null,"ReplyToEmail":{"ID":"21234a-cede-1234-1234-1bd8d7a46d2d","Name":"Andreas","Email":"andreas@email.com","CreatedOn":"/Date(1457526079160+0100)/","IsEnabled":true,"SpfVerified":false,"DkimVerified":true,"DkimPublic":"reply to email dkim public"},"CreatedOn":"/Date(1469541491211)/","UpdatedOn":"/Date(1469541491211)/","ScheduledFor":null,"Timezone":"Korea Standard Time","FormatType":0,"ABCampaignData":{"ID":4080,"SubjectB":"B Subject","PlainContentB":null,"HTMLContentB":null,"WebLocationB":null,"SenderB":null,"HoursToTest":3,"ListPercentage":19,"ABCampaignType":2,"ABWinnerSelectionType":1,"DeliveredOnA":null,"DeliveredOnB":null},"MailingLists":[{"MailingListID":"e9d2ed56-fc20-4337-bb6a-8b5884e8dfa6","SegmentID":0}],"ConfirmationTo":"test@email.com","Status":0,"IsTransactional":false}}
Delete a campaign
Abstract
Describes the request and response details of this Moosend API endpoint to delete a campaign.
DELETE /campaigns/{CampaignID}/delete.{Format}
Deletes a draft or a sent campaign from your Moosend account.
Request
Parameter
In
Type
Required
Description
CampaignID
path
string
true
The ID of the draft or sent campaign that you want to delete.
Describes the request and response details of this Moosend API endpoint to update a draft campaign.
POST /campaigns/{CampaignID}/update.{Format}
Updates the details of an existing draft campaign in your account. Non-draft campaigns cannot be updated. If you are updating a regular campaign, you can ignore the A/B split campaign parameters.
Request
Parameter
In
Type
Required
Description
Accept
header
string
true
Determines the expected format and data type to retrieve the response data.
Value: application/json
CampaignID
path
string
true
The ID of the campaign that you want to update.
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml
apikey
query
string
true
The API key of your account.
Name
body
string
true
The name of the campaign.
Subject
body
string
false
The subject line of the campaign.
SenderEmail
body
string
false
The email address of the campaign sender.
ReplyToEmail
body
string
false
The email address selected to receive replies from the campaign. This must be one of your campaign senders. If not specified, the SenderEmail is assumed.
ConfirmationToEmail
body
string
false
The email address used to send a confirmation message when the campaign has been successfully sent. This can be any valid email address. If not specified, the SenderEmail is assumed.
WebLocation
body
string
false
The URL used to retrieve the HTML content of the campaign. Moosend automatically moves all CSS inline.
MailingLists
body
array
false
A list of email lists in your account that is used to send the campaign.
SegmentID
body
string
false
The ID of a segment in the selected email list. If not specified, the campaign is sent to all active subscribers of the email list.
IsAB
body
Boolean
false
A flag that defines if a campaign is an A/B split campaign. If true, you must fill out A/B split campaign parameters.
TrackInGoogleAnalytics
body
Boolean
false
Specifies if tracking is enabled for the campaign. You must have Google Analytics configured on your site to use this feature.
A/B split campaign parameters
Use these parameters when updating an A/B split campaign. If you specify any of the parameters below when updating a regular campaign, they are ignored in the request.
Name
In
Type
Required
Description
ABCampaignType
body
string
true
Specify the type of test to be performed in the AB split campaign to determine the winning version:
Subjectline - test two different versions of the subject line.
Content - test two different versions of the campaign content.
Sender - test two different versions of the campaign sender.
SubjectB
body
string
false
If testing A/B split campaigns with two subject line versions, this is the second subject version of the subject.
WebLocationB
body
string
false
If testing A/B split campaigns with two HTML content versions, this is the web location of the second HTML content version.
SenderEmailB
body
string
false
If testing A/B split campaigns with two sender versions, this is the email address of the second campaign sender. This must be one of the senders defined in your account.
HoursToTest
body
integer
false
Specify how long the test runs, before determining the winning campaign version to be sent to the rest of the recipients.
This must be an integer between 1 and 24.
ListPercentage
body
integer
false
Specifies a portion of the target recipients to get the test campaign versions. For example, if you specify 10, then 10% of your recipients receive campaign A and another 10% receive the campaign B version.
This must be an integer between 5 and 40.
ABWinnerSelectionType
body
string
false
Specifies the method to determine the winning version for the test. If not set, OpenRate is assumed.
OpenRate -determine the winner based on the version that achieved more opens.
TotalUniqueClicks - determine the winner based on the version that achieved more unique link clicks.
Code - the response message. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - this is null if successful.
Request
POST https://{hostname}/v3/campaigns/{CampaignID}/unschedule.{Format}?apikey=
Request
curl --include \--request POST \'https://{hostname}/v3/campaigns/{CampaignID}/unschedule.{Format}?apikey='
Response
json
{"Code":0,"Error":null,"Context":null}
Get campaign statistics
Abstract
Describes the request and response details of this Moosend API endpoint to get campaign statistics.
GET /campaigns/{CampaignID}/stats/{Type}.{Format}
Retrieves a list of statistics for a specific campaign based on activity such as emails sent, opened, bounced, links clicked, and so on. You have the option to specify the date the activity occurred.
Request
Parameter
In
Type
Required
Description
CampaignID
path
string
true
The ID of the campaign that you are fetching statistics for.
Type
path
string
false
The type of activity used to get information and display statistics. Possible values are:
Sent - when and to which recipients the campaign was sent.
Opened - who opened the campaign.
LinkClicked - who clicked on which links in the campaign.
Forward - who forwarded the campaign using the relevant link in the email body and when.
Unsubscribed - who unsubscribed from the campaign by clicking the unsubscribe link and when.
Bounced - which email recipients failed to receive the campaign. If not specified, Sent value is used by default.
Complained - which email recipients reported your campaign as spam through their email service.
Activity - all types of activities for the campaign.
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml.
apikey
query
string
true
The API key of your account.
date
query
date
false
The specific year, month, and day the activity occurred. The date has a YYYY/MM/DD format.
Describes the request and response details of this Moosend API endpoint to get campaign statistics with paging and filter information.
GET /campaigns/{CampaignID}/stats/{Type}.{Format}
Retrieves a list of statistics for a specific campaign based on activity such as emails sent, opened, bounced, links clicked, and so on. Because this call can return a large number of results, you can add paging information as input. You have the option to filter the results within a date range.
Request
Parameter
In
Type
Required
Description
CampaignID
path
string
true
The ID of the campaign that you are fetching statistics for.
Type
path
string
false
The type of activity used to get information and display statistics. Possible values are:
Sent - when and to which recipients the campaign was sent.
Opened - who opened the campaign.
LinkClicked - who clicked on which links in the campaign.
Forward - who forwarded the campaign using the relevant link in the email body and when.
Unsubscribed - who unsubscribed from the campaign by clicking the unsubscribe link and when.
Bounced - which email recipients failed to receive the campaign. If not specified, Sent value is used by default.
Complained - which email recipients reported your campaign as spam through their email service.
Activity - all types of activities for the campaign.
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml.
apikey
query
string
true
The API key of your account.
Page
query
number
false
The page number to display results for. If not specified, the first page is returned.
PageSize
query
number
false
The maximum number of results per page. This must be a positive integer up to 1000.
Returns 50 results per page if not specified. If a value greater than 1000 is specified, it is treated as 1000.
From
query
date
false
The start date value to return results. If not specified, results are returned from the date the campaign was sent. From date has a DD-MM-YYYY format.
To
query
date
false
The end date value to return results. If not specified, results are returned up to the current date. To date has a DD-MM-YYYY format.
Describes the request and response details of this Moosend API endpoint to get a campaign summary
GET /campaigns/{CampaignID}/view_summary.{Format}
Retrieves a summary of results for a specific sent campaign. The summary includes information such as the number of recipients, opens, clicks, bounces, unsubscribes, forwards, and so on, to date.
Request
Parameter
In
Type
Required
Description
CampaignID
path
string
true
The ID of the campaign that you want to get a summary of.
Code - the response code. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - contains all the following information for the campaign:
CampaignID - the ID of the campaign.
ABVersion - if the campaign is an A/B split test campaign, this displays which campaign version was sent. This is null for a regular campaign.
CampaignName - the name of the campaign.
CampaignSubject - the subject line of the campaign.
MailingLists - a list that contains the email lists or segments that that campaign is sent to.
MailingListID - the ID of the email list.
SegmentID - the ID of the selected segment. This is 0 if there is no segment selected.
CampaignDeliveredOn - the date-time the campaign was delivered.
To - the date-time the measurement ended.
From - the date-time the measurement started.
TotalOpens - the total number of email opens.
UniqueOpens - the total number of unique email opens.
TotalBounces - the total number of email bounces.
TotalComplaints - the total number of complaints.
TotalForwards - the total number of email forwards for the campaign using the Forward to a friend personalization tag.
UniqueForwards - the total number of unique forwards for the campaign using the Forward to a friend personalization tag.
TotalUnsubscribes - the total number of unsubscribed recipients for the campaign.
TotalLinkClicks - the total number of link clicks.
UniqueLinkClicks - the total number of unique link clicks.
Sent - the total number of campaign emails sent.
CampaignIsArchived - specifies whether the campaign has been archived. A campaign older than three months gets archived and only high-level data about the campaign becomes available.
Request
GET https://{hostname}/v3/campaigns/{CampaignID}/view_summary.{Format}?apikey=
Describes the request and response details of this Moosend API endpoint to get a summary of an A/B campaign.
GET /campaigns/{CampaignID}/view_ab_summary.{Format}
Retrieves a summary of results of a specific sent A/B campaign. The summary includes separate results for campaign versions A and B information, and information such as the number of recipients, opens, clicks, bounces, unsubscribes, forwards, and so on, to date.
Request
Parameter
In
Type
Required
Description
CampaignID
path
string
true
The ID of the A/B campaign that you want to get a summary of.
Code - the response code. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - an object that contains all the following information for the A/B split test campaign:
CampaignID - the ID of the winning campaign version.
A - an object that contains the following information for campaign A:
CampaignID - the ID of campaign A.
ABVersion - the version of the campaign. This is 0 for campaign A and 1 for campaign B.
CampaignName - the name of the campaign.
CampaignSubject - the subject of the campaign.
MailingLists - a list that contains the details of email lists and any segments that that campaign is sent to:
Campaign - this is null for this case.
ID - the ID of the email list.
Name - the name of the email list.
ActiveMemberCount - the number of active members in the email list.
BouncedMemberCount - the number of bounced emails in the email list.
RemovedMemberCount - the number of members removed from the email list.
UnsubscribedMemberCount - the number of emails that unsubscribed from the email list.
Status - status of the email list. For created, this is 0, for imported, this is 1, for importing, this is 2, and for deleted, this is 3.
CustomFieldsDefinition - an array containing the parameters of custom fields in the email list. The parameters are:
ID - the ID of the custom field.
Name - the name of the custom field
Context - the context of the custom field. This is null if the field type is not SingleSelectDropDown.
IsRequired - this is true if the custom field is required and false if it is not.
Type - the data type of the custom field. Possible values: 0 for text, 1 for number, 2 for dateTime, 3 for SingleSelectDropDown, and 5 for checkbox.
CreatedBy - the IP address used to create the email list.
CreatedOn - the date-time the email list was created.
UpdatedBy - the IP address used to update the email list.
UpdatedOn - the date-time the requested email list was updated.
ImportOperation - an object that contains the details of the latest import operation performed in the requested email list. This is blank if there was no import done.
ID - the ID of the import operation.
DataHash - a globally unique identifier (GUID) for the import operation
Mappings - the data mappings used for the specific import operation.
EmailNotify - this is null if the import operation notification email was not selected to be sent
CreatedOn - the date-time when the import operation was created.
StartedOn - the date-time when the import operation was stated.
CompletedOn - the date-time when the import operation was completed.
TotalInserted - the total number of inserted emails.
TotalUpdated - the total number of updated emails.
TotalUnsubscribed - the total number of unsubscribed emails.
TotalInvalid - the total number of invalid emails.
TotalIgnored - the total number of ignored emails.
TotalDuplicate - the total number of duplicate emails.
TotalMembers - the total number of members that were selected to be imported.
Message - the message of the import operation. This is null if successful.
Success - this is true if successful.
SkipNewMembers - this is false if the skip new members option was not selected before the import operation began.
Segment - a list of segments containing all the following information for each segment. This is null if the campaign was not sent to a email list segment.
ID - the ID of the segment.
Name - the name of the segment.
MatchType - specifies how subscribers are returned by your segment based on matching criteria. Possible values are:
0 - for All. Returns subscribers that match all the given criteria.
1 - for Any. Returns subscribers that match any of the given criteria.
Criteria - contains a list with information for each selected criterion selected for the segment.
CreatedBy - the IP address used to create the segment.
CreatedOn - the date-time the requested segment was created.
UpdatedBy - the IP address used to update the segment.
UpdatedOn - the date-time the segment was updated.
FetchType - the selected fetch type for the selected segment criteria. Possible values are:
0 - for all segment criteria.
1 - for the top segment criteria.
2 - for the top percent segment criteria.
Description - contains a string representation of all the selected filters, MatchType criteria, and FetchType criteria.
CampaignDeliveredOn - the date-time the campaign was delivered.
To - the date-time the measurement ended.
From - the date-time the measurement started.
TotalOpens - the total number of email opens.
UniqueOpens - the total number of unique email opens.
TotalBounces - the total number of email bounces.
TotalComplaints - the total number of complaints.
TotalForwards - the total number of email forwards for the campaign using the Forward to a friend personalization tag.
UniqueForwards - the total number of unique forwards for the campaign using the Forward to a friend personalization tag.
TotalUnsubscribes - the total number of unsubscribed recipients for the campaign.
TotalLinkClicks - the total number of link clicks.
UniqueLinkClicks - the total number of unique link clicks.
Sent - the total number of campaign emails sent.
CampaignIsArchived - specifies whether the campaign has been archived. A campaign older than three months gets archived and only high-level data about the campaign becomes available.
Request
GET https://{hostname}/v3/campaigns/{CampaignID}/view_ab_summary.{Format}?apikey=
{"Code":0,"Error":null,"Context":{"CampaignID":"afdc4ef6-999f-4d74-905b-ec234789f9d6","A":{"CampaignID":"afdc4ef6-999f-4d74-905b-ec234789f9d6","ABVersion":0,"CampaignName":"Test AB content","CampaignSubject":"Test AB content","MailingLists":[{"Campaign":null,"MailingList":{"ID":"afdc4ef6-999f-4d74-905b-ec234789f9d6","Name":"Customers","ActiveMemberCount":1600,"BouncedMemberCount":0,"RemovedMemberCount":5,"UnsubscribedMemberCount":56,"Status":0,"CustomFieldsDefinition":[],"CreatedBy":"200.205.214.234","CreatedOn":"/Date(1454421389673+0000)/","UpdatedBy":"200.205.214.234","UpdatedOn":"/Date(1454421389673+0000)/","ImportOperation":null},"Segment":null},{"Campaign":null,"MailingList":{"ID":"a589366a-1a34-4965-ac50-f121234we9e","Name":"Customers2","ActiveMemberCount":0,"BouncedMemberCount":0,"RemovedMemberCount":0,"UnsubscribedMemberCount":0,"Status":0,"CustomFieldsDefinition":[],"CreatedBy":"000.205.214.234","CreatedOn":"/Date(1461777017163+0100)/","UpdatedBy":"000.205.214.234","UpdatedOn":"/Date(1461779935800+0100)/","ImportOperation":null},"Segment":null}],"CampaignDeliveredOn":"/Date(1461783674793+0100)/","To":"/Date(1465550745283+0100)/","From":"/Date(1461779880247+0100)/","TotalOpens":1834,"UniqueOpens":1111,"TotalBounces":0,"TotalComplaints":0,"TotalForwards":67,"UniqueForwards":44,"TotalUnsubscribes":6,"TotalLinkClicks":1444,"UniqueLinkClicks":1234,"Sent":1,"CampaignIsArchived":false},"B":{"CampaignID":"04d8677b-e87b-4489-99e6-5867b648e1be","ABVersion":1,"CampaignName":"Test AB content","CampaignSubject":"Test AB content","MailingLists":[{"Campaign":null,"MailingList":{"ID":"ba5ab5a8-391f-4e96-8a83-b6838af8683b","Name":"Andreas2323","ActiveMemberCount":0,"BouncedMemberCount":0,"RemovedMemberCount":0,"UnsubscribedMemberCount":0,"Status":0,"CustomFieldsDefinition":[],"CreatedBy":"212.205.224.198","CreatedOn":"/Date(1454421389673+0000)/","UpdatedBy":"212.205.224.198","UpdatedOn":"/Date(1454421389673+0000)/","ImportOperation":null},"Segment":null},{"Campaign":null,"MailingList":{"ID":"a589466a-12344-4965-ac50-f1299fe5979e","Name":"Customers","ActiveMemberCount":2030,"BouncedMemberCount":0,"RemovedMemberCount":12,"UnsubscribedMemberCount":33,"Status":0,"CustomFieldsDefinition":[],"CreatedBy":"2.11.710.201","CreatedOn":"/Date(1461777017163+0100)/","UpdatedBy":"2.11.70.209","UpdatedOn":"/Date(1461779935800+0100)/","ImportOperation":null},"Segment":null}],"CampaignDeliveredOn":"/Date(1461783674793+0100)/","To":"/Date(1465550745287+0100)/","From":"/Date(1461779880247+0100)/","TotalOpens":1234,"UniqueOpens":1111,"TotalBounces":0,"TotalComplaints":0,"TotalForwards":12,"UniqueForwards":12,"TotalUnsubscribes":5,"TotalLinkClicks":1222,"UniqueLinkClicks":999,"Sent":1,"CampaignIsArchived":false}}}
Segments
Abstract
Overview of segmentation and describes how to use the Moosend API to work with segments, subscribers, and criteria.
Use the Moosend API to fetch your segments, fetch subscribers in a segment, get details about segments, create, update, add or update criteria, and delete segments.
Get all segments
Abstract
Describes the request and response details of this Moosend API endpoint to get all segments created in a mailing list.
GET /lists/{MailingListID}/segments.{Format}
Retrieves a list of all segments including their criteria for a specific email list in your Moosend account.
Request
Parameter
In
Type
Required
Description
MailingListID
path
string
true
The ID of the email list that contains the segments.
{"Code":0,"Error":null,"Context":{"Paging":{"PageSize":100,"CurrentPage":1,"TotalResults":1,"TotalPageCount":1,"SortExpression":"CreatedOn","SortIsAscending":false},"Segments":[{"ID":7314,"Name":"City","MatchType":1,"Criteria":[{"ID":12244,"SegmentID":7314,"Field":2,"CustomFieldID":null,"Comparer":0,"Value":"test","DateFrom":null,"DateTo":null,"Properties":null,"Subscriteria":null},{"ID":12348,"SegmentID":7314,"Field":99,"CustomFieldID":"e4823107-d02d-48af-8190-d8694a33401e","Comparer":0,"Value":"UK","DateFrom":null,"DateTo":null,"Properties":null,"Subscriteria":null}],"CreatedBy":"211.11.111.11","CreatedOn":"/Date(1451490040010+0000)/","UpdatedBy":"211.11.111.11","UpdatedOn":"/Date(1451490040010+0000)/","FetchType":0,"FetchValue":0,"Description":"Fetch all where \"City\" is \"UK\" or \"Recipient Name\" is \"Test\"","SegmentType":1}]}}
Get segment details
Abstract
Describes the request and response details of this Moosend API endpoint to get the details of a specific segment.
GET /lists/{MailingListID}/segments/{SegmentID}/details.{Format}
Retrieves the details about a specific segment in a specific email list in your account. It includes the segment criteria but not the subscribers included in the segment.
Request
Parameter
In
Type
Required
Description
MailingListID
path
string
true
The ID of the email list that contains the segment.
SegmentID
path
string
true
The ID of the segment that contains the details you are requesting.
{"Code":0,"Error":null,"Context":{"ID":10198,"Name":"test","MatchType":0,"Criteria":[{"ID":15778,"SegmentID":10198,"Field":2,"CustomFieldID":null,"Comparer":0,"Value":"Paul","DateFrom":null,"DateTo":null,"Properties":null,"Subscriteria":null},{"ID":15779,"SegmentID":10198,"Field":4,"CustomFieldID":null,"Comparer":8,"Value":"5","DateFrom":"/Date(1465167600000+0100)/","DateTo":"/Date(1465945200000+0100)/","Properties":null,"Subscriteria":null}],"CreatedBy":"212.123.123.112","CreatedOn":"/Date(1465806037033+0100)/","UpdatedBy":"212.123.123.112","UpdatedOn":"/Date(1465806269980+0100)/","FetchType":0,"FetchValue":0,"Description":"Fetch all where \"Recipient Name\" is \"Paul\" and \"Campaigns Opened\" is greater than \"5\""}}
Get segment subscribers
Abstract
Describes the request and response details of this Moosend API endpoint to get the subscribers of a specific segment.
GET /lists/{MailingListID}/segments/{SegmentID}/members.{Format}
Retrieves a list of subscribers that match the criteria of a specific segment.
Request
Parameter
In
Type
Required
Description
MailingListID
path
string
true
The ID of the email list that contains the segment.
SegmentID
path
string
true
The ID of the segment that contains the subscribers you are requesting.
Code - the response code. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - an object that contains all the following information for the requested segment:
Paging - an object that contains the following information:
PageSize - the page size of the results. This is 0 if not defined.
CurrentPage - the number of the result page. This is 1 if not defined.
Totalresults - the number of segment subscribers that are included in the response.
TotalPageCount - the total number of available segment subscriber pages for your account.
SortExpression - the sort expression associated with the column or columns being sorted.
SortIsAscending - this is false if the results are not displayed in ascending order based on the sort expression.
Subscribers - a list of subscribers included in the segment containing the following information for each subscriber:
ID - the ID of the subscriber.
Name - the name of the subscriber.
Email - the email address of the subscriber.
CreatedOn - the date-time the subscriber was added to the email list.
UpdatedOn - the date-time the subscriber was updated in the email list.
UnsubscribedOn - the date-time the subscriber was unsubscribed from the email list.
UnsubscribedFromID - the ID that the subscriber is unsubscribed from.
SubscribeType - the status of the subscriber. For subscribed, this is 1, for unsubscribed, this is 2, for bounced, this is 3, and for removed, this is 4.
CustomFields - a list containing the custom fields of the subscriber. Each custom field includes the following:
CustomFieldID - the ID of the custom field.
Name - the name of the custom field.
Value - the value of the custom field.
RemovedOn - the date-time the subscriber was removed from the email list.
Request
GET https://{hostname}/v3/lists/{MailingListID}/segments/{SegmentID}/members.{Format}?apikey=
{"Code":0,"Error":null,"Context":{"Paging":{"PageSize":500,"CurrentPage":1,"TotalResults":2,"TotalPageCount":1,"SortExpression":null,"SortIsAscending":false},"Subscribers":[{"ID":"07111755-8ee4-1111-ad2b-1111899c6f","Name":"Paul","Email":"paul@email.com","CreatedOn":"/Date(1461777177393+0100)/","UpdatedOn":"/Date(1461777177393+0100)/","UnsubscribedOn":null,"UnsubscribedFromID":null,"SubscribeType":1,"SubscribeMethod":2,"CustomFields":[{"CustomFieldID":"63705cf2-7cbb-4ac1-a246-1a8c1b416026","Name":"CheckBox","Value":"True"},{"CustomFieldID":"63705cf2-7cbb-4ac1-a246-1a8c1b416026","Name":"Date","Value":"4/12/2016 12:00:00 AM"},{"CustomFieldID":"9df6dcc4-bef2-47e7-93af-86889b6b6d6a","Name":"Age","Value":"25"},{"CustomFieldID":"0d2199aa-65fc-448c-b9fe-199e3b72ebc5","Name":"Some custom field","Value":"Something2"},{"CustomFieldID":"46721a6b-09aa-46ff-bab1-a0b75dea24cf","Name":"Some custom field 2","Value":"Text2"}],"RemovedOn":null},{"ID":"0bb00735-7ec7-41de-ab04-d622f67340c4","Name":"John","Email":"john@email.com","CreatedOn":"/Date(1461777334373+0100)/","UpdatedOn":"/Date(1461783253670+0100)/","UnsubscribedOn":null,"UnsubscribedFromID":null,"SubscribeType":1,"SubscribeMethod":0,"CustomFields":[{"CustomFieldID":"0bb00735-7ec7-41de-ab04-d622f67340c4","Name":"Country","Value":"UK"},{"CustomFieldID":"46721a6b-09aa-46ff-bab1-a0b75dea24cf","Name":"Status","Value":"single"}],"RemovedOn":null}]}}
Create an empty segment
Abstract
Describes the request and response details of this Moosend API endpoint to create an empty segment in a specific email list.
POST /lists/{MailingListID}/segments/create.{Format}
Creates a new empty segment without criteria in a specific email list.
Request
Parameter
In
Type
Required
Description
Accept
header
string
true
Determines the expected format and data type to retrieve the response data.
Value: application/json
MailingListID
path
string
true
The ID of the email list where the segment is created.
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml.
apikey
query
string
true
The API key of your account.
Name
body
string
true
The name of the segment.
MatchType
body
string
false
Specifies how subscribers are returned by your segment based on matching criteria:
All (Default) - returns subscribers that match all the given criteria.
Any - returns subscribers that match any of the given criteria.
FetchType
body
string
false
Specifies how many criteria-matching subscribers are contained in your segment:
All - returns all criteria matching subscribers.
Top - returns only a maximum number of subscribers defined in FetchValue.
TopPercent - returns only a percentage of subscribers defined in FetchValue.
FetchValue
body
integer
false
Specifies the maximum number for FetchType:Top or percentage for FetchType:TopPercent of members to be contained in the created segment. If not specified, 0 is assumed.
Describes the request and response details of this Moosend API endpoint to create a segment with criteria in a specific email list.
POST /lists/{MailingListID}/segments/create.{Format}
Creates a new segment with criteria in a specific email list. You must specify how many subscribers are returned based on the criteria that you defined to segment your list.
Request
Parameter
In
Type
Required
Description
Accept
header
string
true
Determines the expected format and data type to retrieve the response data.
Value: application/json
MailingListID
path
string
true
The ID of the email list where the segment is created.
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml.
apikey
query
string
true
The API key of your account.
Name
body
string
true
The name of the segment.
MatchType
body
string
false
Specifies how subscribers are returned by your segment based on matching criteria:
All (Default) - returns subscribers that match all the given criteria.
Any - returns subscribers that match any of the given criteria.
FetchType
body
string
false
Specifies how many criteria-matching subscribers are contained in your segment:
All - returns all criteria matching subscribers.
Top - returns only a maximum number of subscribers defined in FetchValue.
TopPercent - returns only a percentage of subscribers defined in FetchValue.
FetchValue
body
integer
false
Specifies the maximum number for FetchType:Top or percentage for FetchType:TopPercent of members to be contained in the created segment. If not specified, 0 is assumed.
Criteria
body
array
true
An array containing the criteria parameters used to filter the email list:
Field - the criterion used to filter the email list. See Field values.
Comparer - the operator that defines how to compare a Field with its Value. See Comparer values.
Value - the search term used to filter the specified Field.
LastXMinutes - constrains the results by the time that has elapsed.
DateFrom to DateTo - constrains the results by a date span.
Date Function - the value used with custom fields of dateTime data type. See DateFunction values.
Field values
Select one of the following Field values to filter the email list:
DateAdded - filters subscribers by the date they were added to the email list.
DateUpdated - filters subscribers by the date they were last updated in the email list.
RecipientName - filters subscribers by name.
RecipientEmail - filters subscribers by their email address.
SubscribeMethod - filters subscribers by their subscription method.
CustomField - filters subscribers by the value of a custom field.
MailingListIncluded - filters subscribers by checking if they belong to another mailing list.
CampaignsOpened - filters subscribers by the number of campaigns they have opened within the past 60 days.
LinksClicked - filters subscribers by the number of links they have clicked from the campaigns sent to them within the past 60 days.
CampaignName - filters subscribers by the name of the campaign they have opened.
LinkURL - filters subscribers by the URL of the link they have clicked.
CampaignSent - filters subscribers by the campaign they have received or not received.
Platform - filters subscribers by the platform they use.
OperatingSystems - filters subscribers by the operating system they use.
EmailClient - filters subscribers by the email client they use.
WebBrowser - filters subscribers by the web browser they use.
MobileBrowser - filters subscribers by the mobile browser they use.
AddedAnythingToCart - filters subscribers by their cart history in a tracked website.
ViewedProduct - filters subscribers by their browsing history in a tracked website.
PurchasedProduct - filters subscribers by their purchase history in a tracked website.
ViewedProductCategory - filters recipients based on their browsing history in a tracked website.
PurchasedProductCategory - filters recipients based on their purchase history in a tracked website.
ViewedProductBrand - filters recipients based on their browsing history in a tracked website.
PurchasedProductBrand - filters recipients based on their purchase history in a tracked website.
Preference - filters subscribers by their preferences.
Comparer values
Select one of the following Comparer operators to compare a criterion field with its value:
Is - finds subscribers where the Field is exactly equal to the specified Value.
IsNot - finds subscribers where the Field is not equal to the specified Value
Contains - finds subscribers where the Field contains the specified Value.
DoesNotContain - finds subscribers where the Field does not contain the specified Value.
StartsWith - finds subscribers where the Field starts with the specified Value.
DoesNotStartWith - finds subscribers where the Field does not start with the specified Value.
EndsWith - finds subscribers where the Field ends with the specified Value.
DoesNotEndWith - finds subscribers where the Field does not end with the specified Value.
IsGreaterThan - finds subscribers where the Field is greater than the specified Value.
IsGreaterThanOrEqualTo - finds subscribers where the Field is greater than or equal to the specified Value.
IsLessThan - finds subscribers where the Field is less than the specified Value.
IsLessThanOrEqualTo - finds subscribers where the Field is less than or equal to the specified Value.
IsBefore - finds subscribers where the Field is before the specified Value.
IsAfter - finds subscribers where the Field is after the specified Value.
IsEmpty - finds subscribers where the Field has no Value.
IsNotEmpty - finds subscribers where the Field contains a Value.
IsTrue - finds subscribers where the condition defined by the Field is true.
IsFalse - finds subscribers where the condition defined by the Field is false.
DateFunction values
Select one of the following to use with fields of DateTime data type.
Year - the four-digit year part of the date.
Month - the month part of the date from 1 to 12.
Day - the day part of the date from 1 to 31.
WeekDay - the day of the week from 1 to 7. For example, 1 for Sunday, 2 for Monday, and so on.
DaysPassed - the number of days that have passed until now.
HoursPassed - the number of hours that have passed until now.
MinutesPassed - the number of minutes that have passed until now.
Describes the request and response details of this Moosend API endpoint to update a segment in a specific email list.
POST /lists/{MailingListID}/segments/{SegmentID}/update.{Format}
Updates the properties and criteria of an existing segment. You can update the segment's name and match type. If criteria are included in the segment, you can update the criteria but the existing name and settings are retained.
Request
Parameter
In
Type
Required
Description
Accept
header
string
true
Determines the expected format and data type to retrieve the response data.
Value: application/json
MailingListID
path
string
true
The ID of the email list that contains the segment.
SegmentID
path
string
true
The ID of the segment to be updated.
Format
path
string
true
The supported file format for getting a response.
Possible values: json and xml.
apikey
query
string
true
The API key of your account.
Name
body
string
false
The name of the segment.
If not specified, the existing name is retained.
MatchType
body
string
false
Specifies how subscribers are returned by your segment based on matching criteria.
If not specified, All is assumed.
All (Default) - returns subscribers that match all the given criteria.
Any - returns subscribers that match any of the given criteria.
FetchType
body
string
false
Specifies how many criteria-matching subscribers are contained in your segment.
If not specified, All is assumed.
All - returns all criteria matching subscribers.
Top - returns only a maximum number of subscribers defined in FetchValue.
TopPercent - returns only a percentage of subscribers defined in FetchValue.
FetchValue
body
integer
false
Specifies the maximum number for FetchType:Top or percentage for FetchType:TopPercent of members to be contained in the created segment.
If not specified, 0 is assumed.
Criteria
body
array
false
An array containing the criteria parameters used to filter the email list.
If not specified, existing criteria are retained.
Field - the criterion used to filter the email list. See Field values.
Comparer - the operator that defines how to compare a Field with its Value. See Comparer values.
Value - the search term used to filter the specified Field.
LastXMinutes - constrains the results by the time that has elapsed.
DateFrom toDateTo - constrains the results by a date span.
Date Function - the value used with custom fields of dateTime data type. See DateFunction values.
Field values
Select one of the following Field values to filter the email list:
DateAdded - filters subscribers by the date they were added to the email list.
DateUpdated - filters subscribers by the date they were last updated in the email list.
RecipientName - filters subscribers by name.
RecipientEmail - filters subscribers by their email address.
SubscribeMethod - filters subscribers by their subscription method.
CustomField - filters subscribers by the value of a custom field.
MailingListIncluded - filters subscribers by checking if they belong to another mailing list.
CampaignsOpened - filters subscribers by the number of campaigns they have opened within the past 60 days.
LinksClicked - filters subscribers by the number of links they have clicked from the campaigns sent to them within the past 60 days.
CampaignName - filters subscribers by the name of the campaign they have opened.
LinkURL - filters subscribers by the URL of the link they have clicked.
CampaignSent - filters subscribers by the campaign they have received or not received.
Platform - filters subscribers by the platform they use.
OperatingSystems - filters subscribers by the operating system they use.
EmailClient - filters subscribers by the email client they use.
WebBrowser - filters subscribers by the web browser they use.
MobileBrowser - filters subscribers by the mobile browser they use.
AddedAnythingToCart - filters subscribers by their cart history in a tracked website.
ViewedProduct - filters subscribers by their browsing history in a tracked website.
PurchasedProduct - filters subscribers by their purchase history in a tracked website.
ViewedProductCategory - filters subscribers by their browsing history in a tracked website.
PurchasedProductCategory - filters subscribers by their purchase history in a tracked website.
ViewedProductBrand - filters subscribers by their browsing history in a tracked website.
PurchasedProductBrand - filters subscribers by their purchase history in a tracked website.
Preference - filters subscribers by their preferences.
Comparer values
Select one of the following Comparer operators to compare a criterion field with its value:
Is - finds subscribers where the Field is exactly equal to the specified Value.
IsNot - finds subscribers where the Field is not equal to the specified Value
Contains - finds subscribers where the Field contains the specified Value.
DoesNotContain - finds subscribers where the Field does not contain the specified Value.
StartsWith - finds subscribers where the Field starts with the specified Value.
DoesNotStartWith - finds subscribers where the Field does not start with the specified Value.
EndsWith - finds subscribers where the Field ends with the specified Value.
DoesNotEndWith - finds subscribers where the Field does not end with the specified Value.
IsGreaterThan - finds subscribers where the Field is greater than the specified Value.
IsGreaterThanOrEqualTo - finds subscribers where the Field is greater than or equal to the specified Value.
IsLessThan - finds subscribers where the Field is less than the specified Value.
IsLessThanOrEqualTo - finds subscribers where the Field is less than or equal to the specified Value.
IsBefore - finds subscribers where the Field is before the specified Value.
IsAfter - finds subscribers where the Field is after the specified Value.
IsEmpty - finds subscribers where the Field has no Value.
IsNotEmpty - finds subscribers where the Field contains a Value.
IsTrue - finds subscribers where the condition defined by the Field is true.
IsFalse - finds subscribers where the condition defined by the Field is false.
DateFunction values
Select one of the following to use with fields of DateTime data type.
Year - the four-digit year part of the date.
Month - the month part of the date from 1 to 12.
Day - the day part of the date from 1 to 31.
WeekDay - the day of the week from 1 to 7. For example, 1 for Sunday, 2 for Monday, and so on.
DaysPassed - the number of days that have passed until now.
HoursPassed - the number of hours that have passed until now.
MinutesPassed - the number of minutes that have passed until now.