Introduction to the Moosend API

Abstract

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:

  1. Log in to your account.

  2. On the menu bar, click More > Settings.

  3. Click API key.

  4. 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:

curl --include \
'https://{hostname}/v3/campaigns.{Format}?apikey=bafe55f4-e53e-4651-8164-c6d6ff05081b'

HTTP methods

Abstract

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.

    curl --include \
'https://{hostname}/v3/campaigns.{Format}?apikey='

  • DELETE - you can use this method to remove information from your account.

    curl --include \
     --request DELETE \
'https://{hostname}/v3/campaigns/{CampaignID}/delete.{Format}?apikey='

  • 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:

    curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data-binary "{
    \"Name\":\"Test campaign\",
    \"Subject\":\"Some subject\",
    \"SenderEmail\":\"something@email.com\",
    \"ReplyToEmail\":\"something@email.com\",
    \"ConfirmationToEmail\":\"something@email.com\",
    \"HTMLContent\":\"Some HTML body\",      
    \"MailingLists\": [
        {
            \"MailingListID\":\"adaf2fe1-55db-42dc-aaf8-56d8f502138d\",
            \"SegmentID\":\"10166\"
        },
        {
            \"MailingListID\":\"dce99b7a-2619-4805-aaeb-7fecdcb3c71b\"
        }
    ],
    \"IsAB\":\"true\",
    \"ABCampaignType\":\"Content\",
    \"WebLocationB\":\"http://www.mysite.gr/newsletter/index\",
    \"HoursToTest\":\"2\",
    \"ListPercentage\":\"20\",
    \"ABWinnerSelectionType\":\"OpenRate\"
}" \
'https://{hostname}/v3/campaigns/create.{Format}?apikey='

Request and response parameters

Abstract

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.

curl --include \
'https://{hostname}/v3/lists.{Format}?apikey=value1&&WithStatitiscs=value2&SortMethod=value3'

When you have an API request that uses query parameters, you must add the actual value of each parameter after the =. For example:

curl --include \
'https://{hostname}/v3/campaigns.{Format}?apikey=bafe55f4-e53e-4651-8164-c6d6ff05081b'

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:

curl --include \
'https://{hostname}/v3/lists/{Page}/{PageSize}.{Format}?'

When you have an API request that uses path parameters, you must replace the path parameter with their actual values in your request. For example:

curl --include \
'https://{hostname}/v3/lists/1/100.json?'

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:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data-binary "{
    \"Name\":\"New List\",
    \"ConfirmationPage\":\"www.someUrl.com\",
    \"RedirectAfterUnsubscribePage\":\"www.someUrl.com\"
}" \
'https://{hostname}/v3/lists/create.{Format}?apikey='

Response body 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:

{
  "Code": 0,
  "Error": null,
  "Context": "e5f6c0a3-1fe6-4d89-951e-eafae0b01368"
}

HTTP status codes

Abstract

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):

Resource

Method

Endpoint path

Rate limit

Add subscribers

POST

/subscribers/{MailingListID}/subscribe.{Format}

10

Add multiple subscribers

POST

/subscribers/{MailingListID}/subscribe_many.{Format}

2

Unsubscribe a subscriber from an account

POST

/subscribers/unsubscribe.{Format}

20

Unsubscribe a subscriber from an email list

POST

/subscribers/{MailingListID}/unsubscribe.{Format}

20

Unsubscribe a subscriber from an email list and a campaign

POST

/subscribers/{MailingListID}/{CampaignID}/unsubscribe.{Format}

20

Example response

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.

{
  "Code": 429,
  "Error": "RATE_LIMITING",
  "Context": null
}

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.

This walkthrough describes how to:

Create a new email list using the API

To create a new email list using the API:

  1. Go to the Create a mailing list endpoint reference.

  2. Create a POST request using /lists/create.{Format}.

  3. Add your request header. You can use the following value: Content-Type:application/json.

  4. Add the required Format in the request URL path. Possible values are json or xml.

    For example, if you select a JSON format, you can edit the URL as: https://{hostname}/v3/lists/create.json.

  5. Add the required apikey parameter in the request URL after the ?.

    For example, you can add your API key as https://{hostname}/v3/lists/create.json?apikey=bafe55f4-e53e-4651-8164-c6d6ff05081b.

  6. Add the required request body parameter for Name. Optionally, you can add the ConfirmationPage, and RedirectAfterUnsubscribePage parameters.

    curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data-binary "{
    \"Name\":\"New List\",
    \"ConfirmationPage\":\"www.someUrl.com\",
    \"RedirectAfterUnsubscribePage\":\"www.someUrl.com\"
}" \
'https://{hostname}/v3/lists/create.json?apikey=bafe55f4-e53e-4651-8164-c6d6ff05081b'

  7. 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": null,
  "Context": "6ca52d31-765c-4760-a78e-91e511e49d76"
}

    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

To add subscribers to your new email list:

  1. Go to the Add multiple subscribers endpoint reference.

  2. Create a POST request using /subscribers/{MailingListID}/subscribe_many.{Format}.

  3. Add your request header. You can use the following value: Content-Type:application/json.

  4. 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:

    https://{hostname}/v3/subscribers/6ca52d31-765c-4760-a78e-91e511e49d76/subscribe_many.json

  5. 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

  6. 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.

    curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data-binary "{  
    \"HasExternalDoubleOptIn\": false,
    \"Subscribers\":[  
      {  
         \"Name\":\"test1Email\",
         \"Email\":\"test1@test.com\",
         \"CustomFields\":[  
            \"Country=UK\"
         ]
      },
      {  
         \"Name\":\"test2133Email\",
         \"Email\":\"test2133@test.com\",
         \"CustomFields\":[  
            \"Age=25\",
            \"Country=USA\"
         ]
      }
   ]
}" \
'https://{hostname}/v3/subscribers/6ca52d31-765c-4760-a78e-91e511e49d76/subscribe_many.json?apikey=bafe55f4-e53e-4651-8164-c6d6ff05081b'

  7. 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:

  • Field - the criterion used to filter the email list. See list of segmentation fields.

  • 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:

Mailing lists

Abstract

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • 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=
Request
curl --include \
'https://{hostname}/v3/lists.{Format}?apikey=&WithStatistics=&SortBy=&SortMethod='
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "Paging": {
      "PageSize": 0,
      "CurrentPage": 1,
      "TotalResults": 90,
      "TotalPageCount": 9,
      "SortExpression": null,
      "SortIsAscending": false
    },
    "MailingLists": [
      {
        "ID": "04fad8e2-2b35-4302-a887-58f14a1152ab",
        "Name": "Your List Name",
        "ActiveMemberCount": 1024,
        "BouncedMemberCount": 16,
        "RemovedMemberCount": 32,
        "UnsubscribedMemberCount": 24,
        "Status": 0,
        "CustomFieldsDefinition": [
          {
            "ID": "dd4fb545-ba00-4afe-bc39-5ed2462fd1d3",
            "Name": "City",
            "Context": null,
            "IsRequired": false,
            "Type": 0
          },
          {
            "ID": "ae8500d7-d1df-4118-9a2c-6654a7d6a6db",
            "Name": "Age",
            "Context": null,
            "IsRequired": true,
            "Type": 1
          }
        ],
        "CreatedBy": "127.0.0.1",
        "CreatedOn": "/Date(1368710504000+0300)/",
        "UpdatedBy": "127.0.0.1",
        "UpdatedOn": "/Date(1368710923000+0300)/",
        "ImportOperation": {
          "ID": 0,
          "DataHash": "97de8bcb-ca1c-4a4b-bf02-3f639952e093",
          "Mappings": "Some Mappings",
          "EmailNotify": "Some EmailNotify",
          "CreatedOn": "/Date(1400765707431)/",
          "StartedOn": "/Date(1400765707431)/",
          "CompletedOn": "/Date(1400765707432)/",
          "TotalInserted": 0,
          "TotalUpdated": 0,
          "TotalUnsubscribed": 0,
          "TotalInvalid": 0,
          "TotalDuplicate": 0,
          "TotalMembers": 0,
          "Message": "Some Message",
          "Success": false
        },
        "Preferences": {
          "FallbackValue": "",
          "IsRequired": false,
          "Options": [
            "option 1",
            "option 2",
            "option 3"
          ],
          "SelectType": 0
        }
      },
      {
        "ID": "4d90a60c-fad2-4f29-b541-318f0ea82be6",
        "Name": "Some Name",
        "ActiveMemberCount": 0,
        "BouncedMemberCount": 0,
        "RemovedMemberCount": 0,
        "UnsubscribedMemberCount": 0,
        "Status": 0,
        "CustomFieldsDefinition": [
          {
            "ID": "c0adddda-12c1-4109-b7db-9a997f70c81f",
            "Name": "Some Name",
            "Context": "Some Context",
            "IsRequired": false,
            "Type": 0
          },
          {
            "ID": "da5bdc1c-08b2-4b3e-b44b-d56ede6d1a31",
            "Name": "Some Name",
            "Context": "Some Context",
            "IsRequired": false,
            "Type": 0
          }
        ],
        "CreatedBy": "Some CreatedBy",
        "CreatedOn": "/Date(1400765707432)/",
        "UpdatedBy": "Some UpdatedBy",
        "UpdatedOn": "/Date(1400765707432)/",
        "ImportOperation": {
          "ID": 0,
          "DataHash": "7ec702c2-0481-45cc-bf92-72bb4912c60d",
          "Mappings": "Some Mappings",
          "EmailNotify": "Some EmailNotify",
          "CreatedOn": "/Date(1400765707432)/",
          "StartedOn": "/Date(1400765707432)/",
          "CompletedOn": "/Date(1400765707432)/",
          "TotalInserted": 0,
          "TotalUpdated": 0,
          "TotalUnsubscribed": 0,
          "TotalInvalid": 0,
          "TotalDuplicate": 0,
          "TotalMembers": 0,
          "Message": "Some Message",
          "Success": false
        },
        "Preferences": {
          "FallbackValue": "",
          "IsRequired": false,
          "Options": [
            "option 1",
            "option 2",
            "option 3"
          ],
          "SelectType": 0
        }
      }
    ]
  }
}

Get mailing list details

Abstract

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.

Possible values: true (Default) and false.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • 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=
Request
curl --include \
'https://{hostname}/v3/lists/{MailingListID}/details.{Format}?apikey=&WithStatistics='
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "ID": "2813225704fad8e2-f6552b35-49a44302-8af7a887-6fbf3164564158f14a1152ab",
    "Name": "test autoYour List Name",
    "ActiveMemberCount": 199991024,
    "BouncedMemberCount": 016,
    "RemovedMemberCount": 032,
    "UnsubscribedMemberCount": 024,
    "Status": 10,
    "CustomFieldsDefinition": [
      {
        "ID": "c3226ccdd4fb545-8a18ba00-4f224afe-907bbc39-8422d61a53a15ed2462fd1d3",
        "Name": "GenderCity",
        "Context": "<items><item><name>Male</name><value>Male</value></item><item><name>Female</name><value>Female</value></item></items>",
        "IsRequired": true,
        "Type": 3
      },
      {
        "ID": "bf14b37c-3c47-412d-baf1-c6850b8cf2af",
        "Name": "Town",
        "Context": null,
        "IsRequired": false,
        "Type": 0
      },
      {
        "ID": "ae8500d7-d1df-4118-9a2c-6654a7d6a6db",
        "Name": "Age",
        "Context": null,
        "IsRequired": true,
        "Type": 1
      }
    ],
    "CreatedBy": "223.16.165.23127.0.0.1",
    "CreatedOn": "/Date(14431743873271368710504000+01000300)/",
    "UpdatedBy": "223.16.165.23127.0.0.1",
    "UpdatedOn": "/Date(14431743873271368710923000+01000300)/",
    "ImportOperation": {
      "ID": 37060,
      "DataHash": "2490c26c97de8bcb-79f6ca1c-a52c4a4b-4afbbf02-852f624a91b03f639952e093",
      "Mappings": "EmailSome Mappings",
      "EmailNotify": null"Some EmailNotify",
      "CreatedOn": "/Date(1443181931130+01001400765707431)/",
      "StartedOn": "/Date(1443181958330+01001400765707431)/",
      "CompletedOn": "/Date(1443182730673+01001400765707432)/",
      "TotalInserted": 199990,
      "TotalUpdated": 0,
      "TotalUnsubscribed": 10,
      "TotalInvalid": 0,
      "TotalIgnored": 0,
      "TotalDuplicate": 0,
      "TotalMembers": 200000,
      "Message": null"Some Message",
      "Success": truefalse,
      "SkipNewMembers": false 
       },
    "Preferences": {
      "FallbackValue": "",
      "IsRequired": false,
      "Options": [
          "option 1",
          "option 2",
          "option 3"
          ],
      "SelectType": 0
    }
  }
}

Get all active mailing lists with paging

Abstract

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • 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=
Request
curl --include \
'https://{hostname}/v3/lists/{Page}/{PageSize}.{Format}?apikey=&SortBy=&SortMethod='
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "Paging": {
      "PageSize": 200,
      "CurrentPage": 1,
      "TotalResults": 9290,
      "TotalPageCount": 59,
      "SortExpression": null,
      "SortIsAscending": false
    },
    "MailingLists": [
      {
        "ID": "04fad8e2-2b35-4302-a887-58f14a1152ab",
        "Name": "Your List Name",
        "ActiveMemberCount": 1024,
        "BouncedMemberCount": 16,
        "RemovedMemberCount": 32,
        "UnsubscribedMemberCount": 24,
        "Status": 0,
        "CustomFieldsDefinition": [
          {
            "ID": "dd4fb545-ba00-4afe-bc39-5ed2462fd1d3",
            "Name": "City",
            "Context": null,
            "IsRequired": false,
            "Type": 0
          },
          {
            "ID": "ae8500d7-d1df-4118-9a2c-6654a7d6a6db",
            "Name": "Age",
            "Context": null,
            "IsRequired": true,
            "Type": 1
          }
        ],
        "CreatedBy": "127.0.0.1",
        "CreatedOn": "/Date(1368710504000+0300)/",
        "UpdatedBy": "127.0.0.1",
        "UpdatedOn": "/Date(1368710923000+0300)/",
        "ImportOperation": {
          "ID": 0,
          "DataHash": "97de8bcb-ca1c-4a4b-bf02-3f639952e093",
          "Mappings": "Some Mappings",
          "EmailNotify": "Some EmailNotify",
          "CreatedOn": "/Date(1400765707431)/",
          "StartedOn": "/Date(1400765707431)/",
          "CompletedOn": "/Date(1400765707432)/",
          "TotalInserted": 0,
          "TotalUpdated": 0,
          "TotalUnsubscribed": 0,
          "TotalInvalid": 0,
          "TotalDuplicate": 0,
          "TotalMembers": 0,
          "Message": "Some Message",
          "Success": false
        },
        "Preferences": {
          "FallbackValue": "",
          "IsRequired": false,
          "Options": [
            "option 1",
            "option 2",
            "option 3"
          ],
          "SelectType": 0
        }
      },
      {
        "ID": "4d90a60c-fad2-4f29-b541-318f0ea82be6",
        "Name": "Some Name",
        "ActiveMemberCount": 0,
        "BouncedMemberCount": 0,
        "RemovedMemberCount": 0,
        "UnsubscribedMemberCount": 0,
        "Status": 0,
        "CustomFieldsDefinition": [],
          {
            "ID": "c0adddda-12c1-4109-b7db-9a997f70c81f",
            "Name": "Some Name",
            "Context": "Some Context",
            "IsRequired": false,
            "Type": 0
          },
          {
            "ID": "da5bdc1c-08b2-4b3e-b44b-d56ede6d1a31",
            "Name": "Some Name",
            "Context": "Some Context",
            "IsRequired": false,
            "Type": 0
          }
        ],
        "CreatedBy": "192.168.1.1Some CreatedBy",
        "CreatedOn": "/Date(1400765707432)/",
        "UpdatedBy": "192.168.1.1Some UpdatedBy",
        "UpdatedOn": "/Date(1400765707432)/",
        "ImportOperation": {
          "ID": 0,
          "DataHash": "7ec702c2-0481-45cc-bf92-72bb4912c60d",
          "Mappings": "Some Mappings",
          "EmailNotify": "Some EmailNotify",
          "CreatedOn": "/Date(1400765707432)/",
          "StartedOn": "/Date(1400765707432)/",
          "CompletedOn": "/Date(1400765707432)/",
          "TotalInserted": 0,
          "TotalUpdated": 0,
          "TotalUnsubscribed": 0,
          "TotalInvalid": 0,
          "TotalDuplicate": 0,
          "TotalMembers": 0,
          "Message": "Some Message",
          "Success": false
        },
        "Preferences": {
          "FallbackValue": "",
          "IsRequired": false,
          "Options": [
            "option 1",
            "option 2",
            "option 3"
          ],
          "SelectType": 0
        }
      }
    ]
  }
}

Create a mailing list

Abstract

Describes the request and response details of this Moosend API endpoint to create an email list.

POST /lists/create.{Format}

Creates a new empty email list in your 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

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 email list.

ConfirmationPage

body

string

false

The URL of the page displayed at the end of the subscription process.

RedirectAfterUnsubscribePage

body

string

false

The URL of the redirect page when users unsubscribe from your email list.

Preferences

body

array

true

The Preferences field options.

SelectType The data type of the field.

Possible values can be SingleSelect or MultiSelect. Required field.

Options Max options 10

IsRequired If the field is required. Default value false.

PreferencePageId

body

string

false

The preference page id.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • Code - the response code. This is 0 if successful.

  • Error - the response error message. This is null if successful.

  • Context - the ID of the email list created.

Request
POST https://{hostname}/v3/lists/create.{Format}?apikey= 
Request body: 

{
    "Name":"New List",
    "ConfirmationPage":"www.someUrl.com",
    "RedirectAfterUnsubscribePage":"www.someUrl.com",
    "Preferences": {
        "SelectType": "SingleSelect",
        "Options": [
            "option a",
            "option b"
        ]
    },
    "PreferencePageId" : null
}
Request
curl --include --globoff --location --request POST 'https://{hostname}/v3/lists/create.{Format}?apikey=' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "Name": "New List",
    "ConfirmationPage": "www.someUrl.com",
    "RedirectAfterUnsubscribePage": "www.someUrl.com",
    "Preferences": {
        "SelectType": "SingleSelect",
        "Options": [
            "option a",
            "option b"
        ]
    },
    "PreferencePageId": null
}'
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": "6ca52d31-765c-4760-a78e-91e511e49d76"
}

Update a mailing list

Abstract

Describes the request and response details of this Moosend API endpoint to update an email list.

POST /lists/{MailingListID}/update.{Format}

Updates the properties of an existing email list in your account. You can update the email list name, confirmation page, and redirect page URLs.

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 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 email list.

ConfirmationPage

body

string

false

The URL of the page displayed at the end of the subscription process.

RedirectAfterUnsubscribePage

body

string

false

The URL of the redirect page when users unsubscribe from your email list.

Preferences

body

array

true

The Preferences field options.

SelectType The data type of the field.

Possible values can be SingleSelect or MultiSelect. Required field.

Options Max options 10

IsRequired If the field is required. Default value false.

PreferencePageId

body

string

false

The preference page id.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • Code - the response code. This is 0 if successful.

  • Error - the response error message. This is null if successful.

  • Context - the ID of the updated email list.

Request
POST https://{hostname}/v3/lists/{MailingListID}/update.{Format}?apikey=

Request body: 
{
    "Name":"New List",
    "ConfirmationPage":"www.someUrl.com",
    "RedirectAfterUnsubscribePage":"www.someUrl.com",
    "Preferences": {
        "SelectType": "SingleSelect",
        "Options": [
            "option a",
            "option b"
        ]
    },
    "PreferencePageId" : null
}
Request
curl --include --globoff --location --request
POST https://{hostname}/v3/lists/{MailingListID}/update.{Format}?apikey=

{
    "Name": "New List Name",
    "ConfirmationPage": "www.someotherUrl.com",
    "RedirectAfterUnsubscribePage": "www.someUrl.com",
    "Preferences": {
        "SelectType": "SingleSelect",
        "Options": [
            "option a",
            "option b"
        ]
    },
    "PreferencePageId": null
}
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": "e5f6c0a3-1fe6-4d89-951e-eafae0b01368"
}

Delete a mailing list

Abstract

Describes the request and response details of this Moosend API endpoint to delete an email list.

DELETE /lists/{MailingListID}/delete.{Format}

Deletes an email list from your Moosend account.

Request

Parameter

In

Type

Required

Description

MailingListID

path

string

true

The ID of the email list to be deleted.

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • Code - the response error message. This is 0 if successful.

  • Error - the response error message. This is null if successful.

  • Context - this is null if successful.

Request
DELETE https://{hostname}/v3/lists/{MailingListID}/delete.{Format}?apikey=
Request
curl --include \
     --request DELETE \
'https://{hostname}/v3/lists/{MailingListID}/delete.{Format}?apikey='
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": null
}

Create a custom field

Abstract

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).

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • Code - the response code. This is 0 if successful.

  • Error - the response error message. This is null if successful.

  • Context - the ID of the custom field created.

Request
POST https://{hostname}/v3/lists/{MailingListID}/customfields/create.{Format}?apikey=

Request body:
{
  "Name": "Town",
  "CustomFieldType": "SingleSelectDropdown",
  "Options": "Athens,London,New York"
}
Request
curl --include \
     --request POST \
https://{hostname}/v3/lists/{MailingListID}/customfields/create.{Format}?apikey=

   {
    \"Name\": \"Town\",
    \"CustomFieldType\":\"SingleSelectDropdown\",
    \"Options\":\"Athens,London,New York\"
}
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": "b42b4e0f-ca2f-403d-8231-32a2405651af"
}

Update a custom field

Abstract

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).

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • Code - the response code. 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/lists/{MailingListID}/customfields/{CustomFieldID}/update.{Format}?apikey=

Request body:
{
  "Name": "City",
  "CustomFieldType": "SingleSelectDropdown",
  "Options": "Frankfurt,London,Paris,Rome"
}
Request
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data-binary "{
    \"Name\": \"City\",
    \"CustomFieldType\":\"SingleSelectDropdown\",
    \"Options\":\"Frankfurt,London,Paris,Rome\"
}" \
'https://{hostname}/v3/lists/{MailingListID}/customfields/{CustomFieldID}/update.{Format}?apikey='
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": "null"
}

Remove a custom field

Abstract

Describes the request and response details of this Moosend API endpoint to remove a custom field.

DELETE /lists/{MailingListID}/customfields/{CustomFieldID}/delete.{Format}

Removes a custom field from a specific email list.

Request

Parameter

In

Type

Required

Description

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 deleted.

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • Code - the response code. This is 0 if successful.

  • Error - the response error message. This is null if successful.

  • Context - this is null if successful.

Request
DELETE https://{hostname}/v3/lists/{MailingListID}/customfields/{CustomFieldID}/delete.{Format}?apikey=
Request
curl --include \
     --request DELETE \
'https://{hostname}/v3/lists/{MailingListID}/customfields/{CustomFieldID}/delete.{Format}?apikey='
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": null
}

Subscribers

Abstract

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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=
Request
curl --include \
https://{hostname}/v3/lists/{MailingListID}/subscribers/{Status}.{Format}?apikey=&Page=&PageSize=
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "Paging": {
      "PageSize": 500,
      "CurrentPage": 1,
      "TotalResults": 2,
      "TotalPageCount": 1,
      "SortExpression": "CreatedOn",
      "SortIsAscending": false
    },
    "Subscribers": [
      {
        "ID": "4d03536e-7263-4a45-add0-8fe9568d7481",
        "Name": "Maria",
        "Email": "maria@email.com",
        "CreatedOn": "/Date(1456236266953+0000)/",
        "UpdatedOn": "/Date(1465286948363+0100)/",
        "UnsubscribedOn": null,
        "UnsubscribedFromID": null,
        "SubscribeType": 1,
        "SubscribeMethod": 2,
        "CustomFields": [
          {
            "CustomFieldID": "dbc599a6-3ac0-4843-830c-31fa78699fcc",
            "Name": "ID",
            "Value": "1233"
          },
          {
            "CustomFieldID": "bfe484f1-030f-4f8d-bdfa-93abc3b227c0",
            "Name": "City",
            "Value": "Athens"
          }
        ],
        "RemovedOn": null,
        "Tags": [
                      "potential",
                      "repeater"
        ],
        "Preferences": [
          "option a",
          "option b"
        ]
      },
      {
        "ID": "83485f6c-569c-4012-ab2e-f91d3f888995",
        "Name": "Andreas",
        "Email": "andreas@email.com",
        "CreatedOn": "/Date(1454421397847+0000)/",
        "UpdatedOn": "/Date(1465286972657+0100)/",
        "UnsubscribedOn": null,
        "UnsubscribedFromID": null,
        "SubscribeType": 1,
        "SubscribeMethod": 2,
        "CustomFields": [
          {
            "CustomFieldID": "dbc599a6-3ac0-4843-830c-31fa78699fcc",
            "Name": "ID",
            "Value": "1333"
          },
          {
            "CustomFieldID": "bfe484f1-030f-4f8d-bdfa-93abc3b227c0",
            "Name": "City",
            "Value": "Liverpool"
          }
        ],
        "RemovedOn": null,
        "Tags": [
                      "potential",
                      "repeater"
        ],
        "Preferences": [
          "option a",
          "option b"
        ]
      }
    ]
  }
}

Get subscriber by email address

Abstract

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.

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.

Email

query

string

true

The email address of the subscriber.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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=
Request
curl --include \
https://{hostname}/v3/subscribers/{MailingListID}/view.{Format}?apikey=&Email=
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "ID": "9bef1735-f04d-4472-b029-68eb7fa2cfe7",
    "Name": "Andreas",
    "Email": "andreas@email.com",
    "CreatedOn": "/Date(1461777152597+0100)/",
    "UpdatedOn": "/Date(1461777152597+0100)/",
    "UnsubscribedOn": null,
    "UnsubscribedFromID": null,
    "SubscribeType": 1,
    "SubscribeMethod": 2,
    "CustomFields": [
      {
        "CustomFieldID": "b7e68e81-b6ab-4caa-8d13-e65871b32386",
        "Name": "Registered",
        "Value": "4/21/2016 12:00:00 AM"
      },
      {
        "CustomFieldID": "9df6dcc4-bef2-47e7-93af-86889b6b6d6a",
        "Name": "Age",
        "Value": "24"
      },
      {
        "CustomFieldID": "0d2199aa-65fc-448c-b9fe-199e3b72ebc5",
        "Name": "Some custom field",
        "Value": "Something"
      },
      {
        "CustomFieldID": "46721a6b-09aa-46ff-bab1-a0b75dea24cf",
        "Name": "Some custom field",
        "Value": "Text1"
      }
    ],
    "RemovedOn": null,
    "Tags": [
                  "potential",
                  "repeater"
    ],
    "Preferences": [
      "option a",
      "option b"
            ]
  }
}

Get subscriber by ID

Abstract

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.

SubscriberID

path

string

true

The ID of the 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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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=
Request
curl --include \
https://{hostname}/v3/subscribers/{MailingListID}/find/{SubscriberID}.{Format}?apikey=
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "ID": "118e41dc9bef1735-bb9ef04d-435d4472-a86ab029-e5bd374668a868eb7fa2cfe7",
    "Name": "Some nameAndreas",
    "Email": "getmoocampaigns+1andreas@gmail.comemail.com",
    "CreatedOn": "/Date(14649526837731461777152597+0100)/",
    "UpdatedOn": "/Date(14653803283901461777152597+0100)/",
    "UnsubscribedOn": null,
    "UnsubscribedFromID": null,
    "SubscribeType": 41,
    "SubscribeMethod": 2,
    "CustomFields": [],
    "RemovedOn": "/Date(1465381597743+0100)/",      {
        "CustomFieldID": "b7e68e81-b6ab-4caa-8d13-e65871b32386",
        "Name": "Registered",
        "Value": "4/21/2016 12:00:00 AM"
      },
      {
        "CustomFieldID": "9df6dcc4-bef2-47e7-93af-86889b6b6d6a",
        "Name": "Age",
        "Value": "24"
      },
      {
        "CustomFieldID": "0d2199aa-65fc-448c-b9fe-199e3b72ebc5",
        "Name": "Some custom field",
        "Value": "Something"
      },
      {
        "CustomFieldID": "46721a6b-09aa-46ff-bab1-a0b75dea24cf",
        "Name": "Some custom field",
        "Value": "Text1"
      }
    ],
    "RemovedOn": null,
    "Tags": []
      "potential",
      "repeater"
    ],
    "Preferences": [
      "option a",
      "option b"
    ]
  }
}

Add a new subscriber

Abstract

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • 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.

Request
POST /v3/subscribers/{MailingListID}/subscribe.{Format}?apikey=

{
    "Name" : "Paul",
    "Email" : "someEmail@email.com",
    "HasExternalDoubleOptIn": false,
    "CustomFields": [
        "Age=25",
        "Country=USA"
    ],
    "Tags": [
        "repeater"
    ],
    "Preferences": [
      "option a",
      "option b",
      "option c"
    ]
}
Request
curl --include \
     --request POST \
https://{hostname}/v3/subscribers/{MailingListID}/subscribe.{Format}?apikey=

 {
    \"Name\" : \"Paul\",
    \"Email\" : \"someEmail@email.com\",
    \"HasExternalDoubleOptIn\": false,
    \"CustomFields\": [
        \"Age=25\",
        \"Country=USA\"
    ],
    \"Tags\": [  
        \"repeater\"
    ],
       \"Preferences\":[  
        \"option a\",
        \"option b\",
        \"option c\"
]
}
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "ID": "f582c388-7916-4890-a9ab-b592615ef095",
    "Name": "Paul",
    "Email": "someemail@email.com",
    "CreatedOn": "/Date(1465379934028)/",
    "UpdatedOn": "/Date(1465379934028)/",
    "UnsubscribedOn": null,
    "UnsubscribedFromID": null,
    "SubscribeType": 1,
    "SubscribeMethod": 2,
    "CustomFields": [
      {
        "CustomFieldID": "728f6774-37ea-4d81-8607-ce8308136760",
        "Name": "Age",
        "Value": "25"
      },
      {
        "CustomFieldID": "b6380e04-c3a6-425b-9931-d25897fa4752",
        "Name": "Country",
        "Value": "USA"
      }
    ],
    "RemovedOn": null,
    "Tags": [
       "potential",
       "repeater"
    ]  
    }
}

Add multiple subscribers

Abstract

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • 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.

Request
POST /v3/subscribers/{MailingListID}/subscribe_many.{Format}?apikey= 

{
    "HasExternalDoubleOptIn": false,
    "Subscribers": [
        {
            "Name": "test1Email",
            "Email": "test1@test.com",
            "CustomFields": [
                "Country=UK"
            ],
            "Tags": [
                "repeater"
            ],
            "Preferences": [
                "option a",
                "option b",
                "option c"
            ]
        },
        {
            "Name": "test2133Email",
            "Email": "test2133@test.com",
            "CustomFields": [
                "Age=25",
                "Country=USA"
            ],
            "Tags": [
                "repeater"
            ],
            "Preferences": [
                "option a",
                "option b",
                "option c"
            ]
        }
    ]
}
Request
curl --include \
     --request POST \
https://{hostname}/v3/subscribers/{MailingListID}/subscribe_many.{Format}?apikey=

     {  
    \"HasExternalDoubleOptIn\": false,
    \"Subscribers\":[  {  
      {  
         \"Name\":\"test1Email\",
         \"Email\":\"test1@test.com\",
         \"CustomFields\":[  
            \"Country=UK\"
         ]
      },
      {  ],
         \"Tags\": [
            \"repeater\"
],
        \"Preferences\":[  
            \"option a\",
            \"option b\",
            \"option c\"
]
},
{  
         \"Name\":\"test2133Email\",
         \"Email\":\"test2133@test.com\",
         \"CustomFields\":[  
            \"Age=25\",
            \"Country=USA\"
         ],
         \"Tags\": [
            \"repeater\"
         ]
      }
   ],
         \"Preferences\":[  
            \"option a\",
            \"option b\",
            \"option c\"
]
}
]
}"
Response
json
{
  "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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • 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.

Request
POST https://{hostname}/v3/subscribers/{MailingListID}/update/{SubscriberID}subscribe.{Format}?apikey=

Request body:
{
    "Name": "Some NamePaul",
    "Email": "someEmail@email.com",
    "HasExternalDoubleOptIn": false,
    "Email": "someEmail@email.com",
    "CustomFields": [
        "Age=25",
        "Country=USA"
    ],
    "Tags": [
        "repeater"
    ],
    "Preferences": [
      "option a",
      "option b",
      "option c"
    ]
}
Request
curl --include \
     --request POST \
https://{hostname}/v3/subscribers/{MailingListID}/update/{SubscriberID}subscribe.{Format}?apikey=

    {
    \"Name\" : \"Some NamePaul\",
    \"HasExternalDoubleOptIn\": false,
    \"Email\" : \"someEmail@email.com\",
    \"HasExternalDoubleOptIn\": false,
    \"CustomFields\": [
        \"Age=25\",
        \"Country=USA\",
],
    \"Tags\": [  
        \"repeater\"
    ]
    ],
       \"Preferences\":[  
        \"option a\",
        \"option b\",
        \"option c\"
]
}
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "ID": "d75fca65-a2bc-4474-bd4d-307f9cf63a57",
    "Name": "Some name",
    "Email": "someEmail@email.com",
    "CreatedOn": "/Date(1465380655880+0100)/",
    "UpdatedOn": "/Date(1465388373874)/",
    "UnsubscribedOn": null,
    "UnsubscribedFromID": null,
    "SubscribeType": 1,
    "SubscribeMethod": 2,
    "CustomFields": [
      {
        "CustomFieldID": "b9a6cb39-ec8f-4e5e-a41a-b64b9b3fc190",
        "Name": "Age",
        "Value": 25
      },
      {
        "CustomFieldID": "1c4ff8dc-48e3-4af1-ae4f-2b1b81a44d17",
        "Name": "Country",
        "Value": "USA"
      }
    ],
    "RemovedOn": null,
    "Tags": [
       "potential",
       "repeater"
    ]  
  }
}

Unsubscribe a subscriber from an account

Abstract

Describes the request and response details of this Moosend API endpoint to unsubscribe a subscriber from all email lists in an account.

POST /subscribers/unsubscribe.{Format}

Unsubscribes a specific subscriber from all email lists they belong to 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

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.

Email

body

string

true

The email address of the subscriber.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • Code - the response code. 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/subscribers/unsubscribe.{Format}?apikey=

Request body:
{
  "Email": "test1@test.com"
}
Request
curl --include \
     --request POST \
https://{hostname}/v3/subscribers/unsubscribe.{Format}?apikey=

    {
    \"Email\":\"test1@test.com\"
}
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": null
}

Unsubscribe a subscriber from a mailing list

Abstract

Describes the request and response details of this Moosend API endpoint to unsubscribe a subscriber from an email list.

POST /subscribers/{MailingListID}/unsubscribe.{Format}

Unsubscribes a subscriber from 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 from which you want to unsubscribe a 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.

Email

body

string

true

The email address of the subscriber.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • Code - the response code. 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/subscribers/{MailingListID}/unsubscribe.{Format}?apikey=

Request body:
{
  "Email": "test1@test.com"
}
Request
curl --include \
     --request POST \
https://{hostname}/v3/subscribers/{MailingListID}/unsubscribe.{Format}?apikey=

   {
    \"Email\":\"test1@test.com\"
}
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": null
}

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.

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.

Email

body

string

true

The email address of the subscriber.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • Code - the response code. 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/subscribers/{MailingListID}/{CampaignID}/unsubscribe.{Format}?apikey=

Request body:
{
  "Email": "test1@test.com"
}
Request
curl --include \
     --request POST \
https://{hostname}/v3/subscribers/{MailingListID}/{CampaignID}/unsubscribe.{Format}?apikey=

   {
    \"Email\":\"test1@test.com\"
}
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": null
}

Remove a subscriber

Abstract

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.

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.

Email

body

string

true

The email address of the subscriber.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • Code - the response code. 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/subscribers/{MailingListID}/remove.{Format}?apikey=

Request body:
{
  "Email": "test1@test.com"
}
Request
curl --include \
     --request POST \
https://{hostname}/v3/subscribers/{MailingListID}/remove.{Format}?apikey=

     {
    \"Email\":\"test1@test.com\"
}
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": null
}

Remove multiple subscribers

Abstract

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • Code - the response code. This is 0 if successful.

  • Error - the response error message. This is null if successful.

  • Context - an object that contains the following information:

    • EmailsIgnored - the number of ignored email addresses.

    • EmailsProcessed - the number of processed email addresses.

Request
POST https://{hostname}/v3/subscribers/{MailingListID}/remove_many.{Format}?apikey=

Request body:
{
  "Emails": "someEmail@email.com,someEmail2@email.com,someEmail3@email.com"
}
Request
curl --include \
     --request POST \
https://{hostname}/v3/subscribers/{MailingListID}/remove_many.{Format}?apikey=

    {  
   \"Emails\":\"someEmail@email.com,someEmail2@email.com,someEmail3@email.com\"
}
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "EmailsIgnored": 0,
    "EmailsProcessed": 3
  }
}

Delete a subscriber

Abstract

Describes the request and response details of this Moosend API endpoint to delete a subscriber from a specific email list permanently.

POST /subscribers/{MailingListID}/delete.{Format}

Deletes a subscriber from the specified mailing list permanently without moving them to the suppression 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 mailing list from which the subscriber should be deleted.

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.

Email

body

string

true

The email address of the subscriber.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • Code - the response code. 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/subscribers/{MailingListID}/delete.{format}?apikey=
Request body:
{
  "Email": "subscriber@example.com"
}
Request
curl --location --globoff --request GET 'https://{hostname}/v3/subscribers/{MailingListID}/delete.{Format}?apikey=' \
--header 'Content-Type: application/json' \
--data-raw '{
  "Emails": "subscriber@example.com"
}'
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": null
}

Delete multiple subscribers from a specific mailing list

Abstract

Describes the request and response details of the Moosend API endpoint to delete multiple subscribers from a specific email list permanently.

POST /subscribers/{MailingListID}/delete_many.{Format}

Deletes multiple subscribers from the specified email list permanently without moving them to the suppression list. Invalid email addresses 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 delete.

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 delete from the email list. Use a comma (,) to separate the email addresses.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • Code - the response code. This is 0 if successful.

  • Error - the response error message. This is null if successful.

    • VALIDATION_ERROR - input validation error occurred.

    • LIST_NOT_FOUND - the specified email list does not exist.

    • MEMBER_NOT_FOUND - a specified email address was not found in the email list.

    • MEMBER_DELETION_FAILED - failed to delete one or more members.

  • Context - an object that contains the following information:

    • EmailsIgnored - the number of ignored email addresses.

    • EmailsProcessed - the number of processed email addresses.

Request
POST https://{hostname}/v3/subscribers/{MailingListID}/delete_many.{Format}?apikey=
Request body:
{
  "Emails": [
    "subscriber@example.com",
    "subscriber2@example.com",
    "subscriber3@example.com"
  ]
}
Request
curl --location --globoff --request GET 'https://{hostname}/v3/subscribers/{MailingListID}/delete_many.{Format}?apikey=' \
--header 'Content-Type: application/json' \
--data-raw '{
  "Emails": [
    "subscriber@example.com",
    "subscriber2@example.com",
    "subscriber3@example.com"
  ]
}'
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "EmailsIgnored": 0,
    "EmailsProcessed": 3
  }
}

Delete a subscriber from an account

Abstract

Describes the request and response details of this Moosend API endpoint to delete a subscriber from the entire account.

POST /subscribers/delete.{Format}

Deletes a subscriber from the entire 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

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.

Email

body

string

true

The email address of the subscriber.

IncludeAllSubAccounts

body

boolean

false

Determines whether to delete the subscriber from all subaccounts.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

N/A

  • Code - the response code. This is 0 if successful.

  • Error - the response error message. This is null if successful.

    • VALIDATION_ERROR - input validation error occurred.

    • MEMBER_NOT_FOUND - a specified email address was not found in the email list.

    • MEMBER_DELETION_FAILED - failed to delete one or more members.

  • Context - this is null if successful.

Request
POST https://{hostname}/v3/subscribers/delete.{format}?apikey=
Request body:
{
  "Email": "subscriber@example.com",
  "IncludeAllSubAccounts": true
}
Request
curl --location --globoff --request GET 'https://{hostname}/v3/subscribers/delete.{Format}?apikey=' \
--header 'Content-Type: application/json' \
--data-raw '{
  "Emails": "subscriber@example.com",
  "IncludeAllSubAccounts": true
}'
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": null
}

Campaigns

Abstract

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.

Request

Parameter

In

Type

Required

Description

Page

path

number

false

The page number to display results for.

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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

      • 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=
Request
curl --include \
https://{hostname}/v3/campaigns/{Page}.{Format}?apikey=
Response
json
{
  "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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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

      • 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=
Request
curl --include \
https://{hostname}/v3/campaigns/{Page}/{PageSize}.{Format}?apikey=&SortBy=&SortMethod=
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "Paging": {
      "PageSize": 5,
      "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-4637-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 campaign details

Abstract

Describes the request and response details of this Moosend API endpoint to get details of a specific campaign.

Request

Parameter

In

Type

Required

Description

CampaignID

path

string

true

The ID of the campaign that contains the details you are requesting.

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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=
Request
curl --include \
https://{hostname}/v3/campaigns/{CampaignID}/view.{Format}?apikey=
Response
json
{
  "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.

Request

Parameter

In

Type

Required

Description

Format

path

string

true

The supported file format for getting a response.

Possible values: jsonand xml.

apikey

query

string

true

The API key of your account.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • Code - the response code for this call. This is 0 if successful.

  • Error - the response error message. This is null if successful.

  • Context - a list of campaign senders in your account containing the following information for each 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.

Request
GET https://{hostname}/v3/senders/find_all.{Format}?apikey=
Request
curl --include \
https://{hostname}/v3/senders/find_all.{Format}?apikey=
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": [
    {
      "ID": "01234567-89ab-cdef-0123-456789abcdef",
      "Name": "Your Name",
      "Email": "sender@example.com",
      "CreatedOn": "/Date(1323857838000+0200)/",
      "IsEnabled": true,
      "SpfVerified": false,
      "DkimVerified": false,
      "DkimPublic": "Some DkimPublic"
    },
    {
      "ID": "e57c96b7-5786-489b-b3a2-bac3e30dd6bd",
      "Name": "Some Name",
      "Email": "Some Email",
      "CreatedOn": "/Date(1400765125478)/",
      "IsEnabled": false,
      "SpfVerified": false,
      "DkimVerified": false,
      "DkimPublic": "Some DkimPublic"
    }
  ]
}

Get sender details

Abstract

Describes the request and response details of this Moosend API endpoint to get details of a specific sender.

GET /senders/find_one.{Format}

Retrieves the details about a specific campaign sender using the sender's email address.

Request

Parameter

In

Type

Required

Description

Format

path

string

true

The supported file format for getting a response.

Possible values: jsonand xml.

Email

query

string

true

The email address of the sender that contains the details you are requesting.

apikey

query

string

true

The API key of your account.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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 about the 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.

Request
GET https://{hostname}/v3/senders/find_one.{Format}?Email=&apikey=
Request
curl --include \
https://{hostname}/v3/senders/find_one.{Format}?Email=&apikey=
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "ID": "01234567-89ab-cdef-0123-456789abcdef",
    "Name": "Your Name",
    "Email": "sender@example.com",
    "CreatedOn": "/Date(1323857838000+0200)/",
    "IsEnabled": true,
    "SpfVerified": false,
    "DkimVerified": false,
    "DkimPublic": "Some DkimPublic"
  }
}

Create a draft campaign

Abstract

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • Code - the response code. This is 0 if successful.

  • Error - the response error message. This is null if successful.

  • Context - the ID of the campaign created.

Request
POST https://{hostname}/v3/campaigns/create.{Format}?apikey=

Request body:
{
  "Name": "Test campaign",
  "Subject": "Some subject",
  "SenderEmail": "something@email.com",
  "ReplyToEmail": "something@email.com",
  "ConfirmationToEmail": "something@email.com",
  "HTMLContent": "Some HTML body",  
  "MailingLists": [
    {
      "MailingListID": "adaf2fe1-55db-42dc-aaf8-56d8f502138d",
      "SegmentID": "10166"
    },
    {
      "MailingListID": "dce99b7a-2619-4805-aaeb-7fecdcb3c71b"
    }
  ],
  "IsAB": "true",
  "ABCampaignType": "Content",
  "WebLocationB": "http://www.mysite.gr/newsletter/index",
  "HoursToTest": "2",
  "ListPercentage": "20",
  "ABWinnerSelectionType": "OpenRate"
}
Request
curl --include \
     --request POST \ 
https://{hostname}/v3/campaigns/create.{Format}?apikey=
{
    \"Name\":\"Test campaign\",
    \"Subject\":\"Some subject\",
    \"SenderEmail\":\"something@email.com\",
    \"ReplyToEmail\":\"something@email.com\",
    \"ConfirmationToEmail\":\"something@email.com\",
    \"HTMLContent\":\"Some HTML body\",      
    \"MailingLists\": [
        {
            \"MailingListID\":\"adaf2fe1-55db-42dc-aaf8-56d8f502138d\",
            \"SegmentID\":\"10166\"
        },
        {
            \"MailingListID\":\"dce99b7a-2619-4805-aaeb-7fecdcb3c71b\"
        }
    ],
    \"IsAB\":\"true\",
    \"ABCampaignType\":\"Content\",
    \"WebLocationB\":\"http://www.mysite.gr/newsletter/index\",
    \"HoursToTest\":\"2\",
    \"ListPercentage\":\"20\",
    \"ABWinnerSelectionType\":\"OpenRate\"
}"
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": "afdc4ef6-999f-4d74-905b-ec234789f9d6"
}

Manage a transactional campaign

Abstract

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 transactional campaign to your recipients. 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

false

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. There are some restricted keywords implemented, see note below.

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).

Disposition - Allowed values are: “inline”, “attachment” (Required).

ContentId - A user-defined string that maps an embedded image to an attachment. (Required only for inline disposition).

Note

Restricted keywords for substitutions: datetime, ab, appDomain, appDomainProtocol, trackingDomain, doubleOptInDomain, utilitiesDomain, updatePreferences, emailSentTo, forwardToFriendLink, updateProfileLink, verificationLink, unsubscribeLink.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

POST /v3/campaigns/transactional/send.json?apikey=

Request body:

{ 
    "From": { 
        "Email": "orders@example.com", 
        "Name": "Example Order Confirmation" 
    }, 
    "ReplyTo": { 
        "Email": "customer_service@example.com", 
        "Name": "Example Customer Service Team" 
    }, 
    "Subject": "Your Example Order Confirmation", 
    "TemplateId": "d59b39d5-da76-4797-8f24-c1265bb903b8", 
    "TemplateName": "My Sending Template", 
    "Content": [ 
        { 
            "Type": "text/html", 
            "Value": "<p>Hello world</p>", 
            "WebLocation": "https://mycompany.com/template.html" 
        } 
    ], 
    "Personalizations": [ 
        { 
            "To": [ 
                { 
                    "Email": "john_doe@example.com", 
                    "Name": "John Doe" 
                } 
            ], 
            "Substitutions": { 
                    "key1": "value1", 
                    "key2": "value2" 
                } 
        }, 
        { 
            "To": [ 
                { 
                    "Email": "julia_doe@example.com", 
                    "Name": "Julia Doe" 
                } 
            ], 
            "Substitutions": { 
                    "key1": "value1", 
                    "key2": "value2" 
                } 
        } 
    ], 
    "MailSettings": { 
        "BypassUnsubscribeManagement": { 
            "Enable": true 
        } 
    },
  "attachments": [
    {
      "content": "iVBORw0KGgoAAAANSUhEUgAABYMAAAOgCAYAAABvGmkhAAAABGdBTUEAAwAAAAA0AeMwQAAAAAAfcAYDAAAAADQB4zBAAAAAAB9wBgMAAAAANAHjMEAAAAAAH3AGAwAAAAA0AeMwQAAAAAAPe+T+J/nnNIPnRqhbwAAAABJRU5ErkJggg==",
      "Type": "application/pdf",
      "FileName": "attachementexample.pdf",
      "disposition": "attachment",
      "ContentId": "attachment-a"
    },
    {
      "content": "iVBORw0KGgoAAAAAfcAYDAAAAADQB4zBAAAAAAB9wBgMAAAAANAHjMEAAAAAAH3AGAwAAAAA0AeMwQAAAAAAfcAYDAAAAADQB4zBAAAAAAB9wBgMAAAAANAHjMEAAAAAAH3AGAwAAAAA0AeMwQAAAAAAPe+T+J/nnNIPnRqhbwAAAABJRU5ErkJggg==",
      "type": "image/PNG",
      "filename": "imageexample.png",
      "disposition": "inline",
      "contentId": "image-a"
    }
  ]
}
curl --include \
     --request POST \
https://{hostname}/v3/campaigns/transactional/send.json?apikey
{ 
    "From": { 
        "Email": "orders@example.com", 
        "Name": "Example Order Confirmation" 
    }, 
    "ReplyTo": { 
        "Email": "customer_service@example.com", 
        "Name": "Example Customer Service Team" 
    }, 
    "Subject": "Your Example Order Confirmation", 
    "TemplateId": "d59b39d5-da76-4797-8f24-c1265bb903b8", 
    "TemplateName": "My Sending Template", 
    "Content": [ 
        { 
            "Type": "text/html", 
            "Value": "<p>Hello world</p>", 
            "WebLocation": "https://mycompany.com/template.html" 
        } 
    ], 
    "Personalizations": [ 
        { 
            "To": [ 
                { 
                    "Email": "john_doe@example.com", 
                    "Name": "John Doe" 
                } 
            ], 
            "Substitutions": { 
                    "key1": "value1", 
                    "key2": "value2" 
                } 
        }, 
        { 
            "To": [ 
                { 
                    "Email": "julia_doe@example.com", 
                    "Name": "Julia Doe" 
                } 
            ], 
            "Substitutions": { 
                    "key1": "value1", 
                    "key2": "value2" 
                } 
        } 
    ], 
    "MailSettings": { 
        "BypassUnsubscribeManagement": { 
            "Enable": true 
        } 
    },
  "attachments": [
    {
      "content": "iVBORw0KGgoAAAANSUhEUgAABYMAAAOgCAYAAABvGmkhAAAABGdBTUEAAwAAAAA0AeMwQAAAAAAfcAYDAAAAADQB4zBAAAAAAB9wBgMAAAAANAHjMEAAAAAAH3AGAwAAAAA0AeMwQAAAAAAPe+T+J/nnNIPnRqhbwAAAABJRU5ErkJggg==",
      "Type": "application/pdf",
      "FileName": "attachementexample.pdf",
      "disposition": "attachment",
      "ContentId": "attachment-a"
    },
    {
      "content": "iVBORw0KGgoAAAAAfcAYDAAAAADQB4zBAAAAAAB9wBgMAAAAANAHjMEAAAAAAH3AGAwAAAAA0AeMwQAAAAAAfcAYDAAAAADQB4zBAAAAAAB9wBgMAAAAANAHjMEAAAAAAH3AGAwAAAAA0AeMwQAAAAAAPe+T+J/nnNIPnRqhbwAAAABJRU5ErkJggg==",
      "type": "image/PNG",
      "filename": "imageexample.png",
      "disposition": "inline",
      "contentId": "image-a"
    }
  ]
}'
Response
json
{
  "TotalAccepted": 1,
  "TotalExcluded": 1,
  "ExcludedRecipients": [
    {
      "Email": "recipient@domain.dom",
      "Reason": "The recipient was found with status bounced"
    }
  ]
}

Clone an existing campaign

Abstract

Describes the request and response details of this Moosend API endpoint to clone a campaign.

POST /campaigns/{CampaignID}/clone.{Format}

Clones or creates an exact copy of an existing campaign in your Moosend account. The cloned campaign is created with a Draft status.

Request

Parameter

In

Type

Required

Description

CampaignID

path

string

true

The ID of the campaign that you want to clone.

Format

path

string

true

The supported file format for getting a response.

Possible values: jsonand xml.

apikey

query

string

true

The API key of your account.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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.

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • Code - the response code. This is 0 if successful.

  • Error - the response error message. This is null if successful.

  • Context - this is null if successful.

Request
DELETE https://{hostname}/v3/campaigns/{CampaignID}/delete.{Format}?apikey=
Request
curl --include \
     --request DELETE \
https://{hostname}/v3/campaigns/{CampaignID}/delete.{Format}?apikey=
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": null
}

Update a draft campaign

Abstract

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • Code - the response code. 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}/update.{Format}?apikey=

Request body:
{
  "Name": "Test campaign",
  "Subject": "Some subject",
  "SenderEmail": "something@email.com",
  "ReplyToEmail": "something@email.com",
  "ConfirmationToEmail": "something@email.com",
  "WebLocation": "http://www.mysite.gr/newsletter/index",
  "MailingLists": [
    {
      "MailingListID": "adaf2fe1-55db-42dc-aaf8-56d8f502138d",
      "SegmentID": "10166"
    },
    {
      "MailingListID": "dce99b7a-2619-4805-aaeb-7fecdcb3c71b"
    }
  ],
  "IsAB": "true",
  "ABCampaignType": "Content",
  "WebLocationB": "http://www.mysite.gr/newsletter/index",
  "HoursToTest": "2",
  "ListPercentage": "20",
  "ABWinnerSelectionType": "OpenRate"
}
Request
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data-binary "{
    \"Name\":\"Test campaign\",
    \"Subject\":\"Some subject\",
    \"SenderEmail\":\"something@email.com\",
    \"ReplyToEmail\":\"something@email.com\",
    \"ConfirmationToEmail\":\"something@email.com\",
    \"WebLocation\":\"http://www.mysite.gr/newsletter/index\",
    \"MailingLists\": [
        {
            \"MailingListID\":\"adaf2fe1-55db-42dc-aaf8-56d8f502138d\",
            \"SegmentID\":\"10166\"
        },
        {
            \"MailingListID\":\"dce99b7a-2619-4805-aaeb-7fecdcb3c71b\"
        }
    ],
    \"IsAB\":\"true\",
    \"ABCampaignType\":\"Content\",
    \"WebLocationB\":\"http://www.mysite.gr/newsletter/index\",
    \"HoursToTest\":\"2\",
    \"ListPercentage\":\"20\",
    \"ABWinnerSelectionType\":\"OpenRate\"
}" \
'https://{hostname}/v3/campaigns/{CampaignID}/update.{Format}?apikey='
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": null
}

Test a campaign

Abstract

Describes the request and response details of this Moosend API endpoint to test a draft campaign.

POST /campaigns/{CampaignID}/send_test.{Format}

Tests and previews a draft campaign by sending it to a list of email addresses.

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 draft campaign that you want to test.

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.

TestEmails

body

array

true

A list of email addresses that you want to use to send your test campaign. Use a comma (,) to separate up to a maximum of five email addresses.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • Code - the response code. 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}/send_test.{Format}?apikey=

Request body:
{
  "TestEmails": [
    "email1@email.com",
    "email2@email.com"
  ]
}
Request
curl --include \
     --request POST \
https://{hostname}/v3/campaigns/{CampaignID}/send_test.{Format}?apikey=
{
    \"TestEmails\":
    [
        \"email1@email.com\",
        \"email2@email.com\"
    ]
}
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": null
}

Send a campaign

Abstract

Describes the request and response details of this Moosend API endpoint to send a campaign.

POST /campaigns/{CampaignID}/send.{Format}

Sends a draft campaign immediately to all recipients in the email list you've selected for the campaign.

Request

Parameter

In

Type

Required

Description

CampaignID

path

string

true

The ID of the draft campaign that you want to send.

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • Code - the response code. 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}/send.{Format}?apikey=
Request
curl --include \
     --request POST \
https://{hostname}/v3/campaigns/{CampaignID}/send.{Format}?apikey=
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": null
}

Schedule a campaign

Abstract

Describes the request and response details of this Moosend API endpoint to schedule a campaign for delivery.

POST /campaigns/{CampaignID}/schedule.{Format}

Schedules the delivery of a campaign by assigning a specific date and time.

Note

This API call is designed to assign the scheduled date time to the campaign, but not to send the campaign. If you would like to send the campaign at the scheduled time, you will need to call the Send a campaign API as well.

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 schedule.

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.

DateTime

body

date

true

The specific date and time the campaign is scheduled to be delivered.

Use the same format that you have in the Time and date settings in your account. For example, dd-mm-yyyy.

Timezone

body

string

false

The time zone of your specified date and time.

If you don't specify any timezone value, the time zone in your time and date settings is used.

Timezone values

The available time zones are the following:

  • Dateline Standard Time

  • Samoa Standard Time

  • Hawaiian Standard Time

  • Alaskan Standard Time

  • Pacific Standard Time

  • Pacific Standard Time (Mexico)

  • US Mountain Standard Time

  • Mountain Standard Time

  • Central Standard Time

  • Central Standard Time (Mexico)

  • Canada Central Standard Time

  • SA Pacific Standard Time

  • US Eastern Standard Time

  • Eastern Standard Time

  • Venezuela Standard Time

  • Atlantic Standard Time

  • SA Western Standard Time

  • Central Brazilian Standard Time

  • Pacific SA Standard Time

  • Newfoundland Standard Time

  • E. South America Standard Time

  • Argentina Standard Time

  • SA Eastern Standard Time

  • Greenland Standard Time

  • Montevideo Standard Time

  • Mid-Atlantic Standard Time

  • Azores Standard Time

  • Cape Verde Standard Time

  • Greenwich Standard Time

  • GMT Standard Time

  • Morocco Standard Time

  • W. Central Africa Standard Time

  • Central European Standard Time

  • Romance Standard Time

  • W. Europe Standard Time

  • Namibia Standard Time

  • E. Europe Standard Time

  • Israel Standard Time

  • FLE Standard Time

  • South Africa Standard Time

  • Egypt Standard Time

  • Middle East Standard Time

  • GTB Standard Time

  • Jordan Standard Time

  • Iran Standard Time

  • Georgian Standard Time

  • E. Africa Standard Time

  • Russian Standard Time

  • Arab Standard Time

  • Arabic Standard Time

  • Caucasus Standard Time

  • Mauritius Standard Time

  • Azerbaijan Standard Time

  • Arabian Standard Time

  • Afghanistan Standard Time

  • West Asia Standard Time

  • Pakistan Standard Time

  • Ekaterinburg Standard Time

  • Sri Lanka Standard Time

  • India Standard Time

  • Nepal Standard Time

  • N. Central Asia Standard Time

  • Central Asia Standard Time

  • Myanmar Standard Time

  • North Asia Standard Time

  • SE Asia Standard Time

  • Taipei Standard Time

  • W. Australia Standard Time

  • Singapore Standard Time

  • North Asia East Standard Time

  • China Standard Time

  • Yakutsk Standard Time

  • Korea Standard Time

  • Tokyo Standard Time

  • AUS Central Standard Time

  • Cen. Australia Standard Time

  • AUS Eastern Standard Time

  • West Pacific Standard Time

  • Tasmania Standard Time

  • Vladivostok Standard Time

  • Central Pacific Standard Time

  • New Zealand Standard Time

  • Tonga Standard Time

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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}/schedule.{Format}?apikey=

Request body:
{
  "DateTime": "24-06-2023 13:17",
  "Timezone": "US Eastern Standard Time"
}
Request
curl --include \
     --request POST \
    https://{hostname}/v3/campaigns/{CampaignID}/schedule.{Format}?apikey=
{
    \"DateTime\":\"24-06-2023 13:17\",
    \"Timezone\":\"US Eastern Standard Time\"
}
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": null
}

Unschedule a campaign

Abstract

Describes the request and response details of this Moosend API endpoint to unschedule a campaign that is scheduled for delivery.

POST /campaigns/{CampaignID}/unschedule.{Format}

Removes a previously scheduled date and time for delivering a campaign. If already queued, the campaign is sent immediately.

Request

Parameter

In

Type

Required

Description

CampaignID

path

string

true

The ID of the campaign that you want to unschedule.

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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 Analytics information for the campaign:

    • 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 results that are included in the response.

      • TotalPageCount - the total number of 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.

    • Analytics - a list of recipients containing the following information for each recipient:

      • Context - the email address of the recipient.

      • ContextName - the name of the recipient.

      • TotalCount - the total number of statistics based on the activity Type made by the recipient. This can be opens, link clicks, and so on.

      • UniqueCount - the total number of unique statistics based on the activity Type made by the recipient. This can be opens, link clicks, and so on.

      • ContextDescription : If the selected Type is Unsubscribed, this contains the date-time the recipient unsubscribed from the campaign.

Request
GET https://{hostname}/v3/campaigns/{CampaignID}/stats/{Type}.{Format}?apikey=
Request
curl --include \
https://{hostname}/v3/campaigns/{CampaignID}/stats/{Type}.{Format}?apikey=
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "Paging": {
      "PageSize": 1,
      "CurrentPage": 1,
      "TotalResults": 2,
      "TotalPageCount": 1,
      "SortExpression": null,
      "SortIsAscending": false
    },
    "Analytics": [
      {
        "Context": "recipient@email.com",
        "ContextName": "recipient name",
        "TotalCount": 1,
        "UniqueCount": 0,
        "ContextDescription": null
      },
      {
        "Context": "recipient2@email.com",
        "ContextName": "recipient2 name",
        "TotalCount": 1,
        "UniqueCount": 0,
        "ContextDescription": null
      }
    ]
  }
}

Get campaign statistics with paging and filter

Abstract

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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 Analytics information for the campaign:

    • 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 results that are included in the response.

      • TotalPageCount - the total number of 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.

    • Analytics - a list of recipients containing the following information for each recipient:

      • Context - the email address of the recipient.

      • ContextName - the name of the recipient.

      • TotalCount - the total number of statistics based on the activity Type made by the recipient. This can be opens, link clicks, and so on.

      • UniqueCount - the total number of unique statistics based on the activity Type made by the recipient. This can be opens, link clicks, and so on.

      • ContextDescription : If the selected Type is Unsubscribed, this contains the date-time the recipient unsubscribed from the campaign.

Request
GET https://{hostname}/v3/campaigns/{CampaignID}/stats/{Type}.{Format}?apikey=&Page=&PageSize=&From&To=
Request
curl --include \
https://{hostname}/v3/campaigns/{CampaignID}/stats/{Type}.{Format}?apikey=&Page=&PageSize=&From=&To=
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "Paging": {
      "PageSize": 5,
      "CurrentPage": 1,
      "TotalResults": 374,
      "TotalPageCount": 75,
      "SortExpression": null,
      "SortIsAscending": false
    },
    "Analytics": [
      {
        "Context": "recipient1@email.com",
        "ContextName": "",
        "TotalCount": 1,
        "UniqueCount": 0,
        "ContextDescription": null
      },
      {
        "Context": "recipient2@email.com",
        "ContextName": "Paul",
        "TotalCount": 1,
        "UniqueCount": 0,
        "ContextDescription": null
      },
      {
        "Context": "recipient3@email.com",
        "ContextName": "John",
        "TotalCount": 5,
        "UniqueCount": 0,
        "ContextDescription": null
      },
      {
        "Context": "recipient4@email.com",
        "ContextName": "Marc",
        "TotalCount": 4,
        "UniqueCount": 0,
        "ContextDescription": null
      },
      {
        "Context": "recipient5@email.com",
        "ContextName": "",
        "TotalCount": 3,
        "UniqueCount": 0,
        "ContextDescription": null
      }
    ]
  }
}

Get campaign summary

Abstract

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.

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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.

Request
GET https://{hostname}/v3/campaigns/{CampaignID}/view_summary.{Format}?apikey=
Request
curl --include \
https://{hostname}/v3/campaigns/{CampaignID}/view_summary.{Format}?apikey=
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "CampaignID": "13cffeee-0b8c-4610-8e0d-efa7bd44be32",
    "ABVersion": null,
    "CampaignName": "test image path",
    "CampaignSubject": "test image path",
    "MailingLists": [
      {
        "MailingListID": "84bs231b131-367a-4d73-af11-01b4b45d3f54",
        "SegmentID": 0
      }
    ],
    "CampaignDeliveredOn": "/Date(1464256291013+0100)/",
    "To": "/Date(1465481260987+0100)/",
    "From": "/Date(1464256291013+0100)/",
    "TotalOpens": 1340,
    "UniqueOpens": 780,
    "TotalBounces": 4,
    "TotalComplaints": 0,
    "TotalForwards": 55,
    "UniqueForwards": 55,
    "TotalUnsubscribes": 7,
    "TotalLinkClicks": 976,
    "UniqueLinkClicks": 711,
    "Sent": 2550,
    "CampaignIsArchived": false
  }
}

Get campaign activity by location

Abstract

Describes the request and response details of this Moosend API endpoint to get campaign activity by location.

GET /campaigns/{CampaignID}/stats/countries.{Format}

Retrieves the details about a specific campaign's unique or total opens by location.

Request

Parameter

In

Type

Required

Description

CampaignID

path

string

true

The ID of the campaign that you want to get the activity by location of.

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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 Analytics information for the campaign:

    • 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 results that are included in the response.

      • TotalPageCount - the total number of 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.

    • Analytics - a list of countries where the campaign opens occurred. It contains the following information for each country:

      • Context - the country code.

      • ContextName - the name of the country.

      • TotalCount - the total number of campaign opens.

      • UniqueCount - The total number of unique campaign opens.

      • ContextDescription - this is null for this case.

Request
GET https://{hostname}/v3/campaigns/{CampaignID}/stats/countries.{Format}?apikey=
Request
curl --include \
https://{hostname}/v3/campaigns/{CampaignID}/stats/countries.{Format}?apikey=
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "Paging": {
      "PageSize": 0,
      "CurrentPage": 1,
      "TotalResults": 0,
      "TotalPageCount": 0,
      "SortExpression": null,
      "SortIsAscending": false
    },
    "Analytics": [
      {
        "Context": "  ",
        "ContextName": null,
        "TotalCount": 1,
        "UniqueCount": 1,
        "ContextDescription": null
      }
    ]
  }
}

Get campaign link activity

Abstract

Describes the request and response details of this Moosend API endpoint to get campaign link activity.

GET /campaigns/{CampaignID}/stats/links.{Format}

Retrieves a list of all the links in a specific campaign and the number of unique or total link clicks made by campaign recipients.

Request
GET https://{hostname}/v3/campaigns/{CampaignID}/stats/links.{Format}?apikey=
Request
curl --include \
https://{hostname}/v3/campaigns/{CampaignID}/stats/links.{Format}?apikey=
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": {
    "Paging": {
      "PageSize": 0,
      "CurrentPage": 1,
      "TotalResults": 0,
      "TotalPageCount": 0,
      "SortExpression": null,
      "SortIsAscending": false
    },
    "Analytics": [
      {
        "Context": "http://someUrl.com/",
        "ContextName": null,
        "TotalCount": 34,
        "UniqueCount": 30,
        "ContextDescription": null
      },
      {
        "Context": "http://someUrl.com/product1/",
        "ContextName": null,
        "TotalCount": 95,
        "UniqueCount": 67,
        "ContextDescription": null
      },
      {
        "Context": "http://someUrl.com/product2/",
        "ContextName": null,
        "TotalCount": 102,
        "UniqueCount": 78,
        "ContextDescription": null
      },
      {
        "Context": "https://twitter.com/myCompany",
        "ContextName": null,
        "TotalCount": 89,
        "UniqueCount": 89,
        "ContextDescription": null
      }
    ]
  }
}

Get A/B campaign summary

Abstract

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.

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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.

Request
GET https://{hostname}/v3/campaigns/{CampaignID}/view_ab_summary.{Format}?apikey=
Request
curl --include \
https://{hostname}/v3/campaigns/{CampaignID}/view_ab_summary.{Format}?apikey=
Response
json
{
  "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.

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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 segments:

    • 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 segments that are included in the response.

      • TotalPageCount - the total number of available segment 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.

    • Segments - a list of segments in the email list containing the following information for each segment:

      • ID - the ID of the segment.

      • Name - the name of the segment.

      • MatchType - specifies how subscribers are returned by your segment based on the 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 the following information for each selected criterion selected for the segment:

        • ID - the ID of the criteria.

        • SegmentID - the ID of the segment.

        • Field - the enum value of the selected filter.

        • CustomFieldID - if the selected filter is a custom field, this is the ID of the custom field.

        • Comparer - the operator that defines how to compare Field and Value. If not specified, Is is assumed.

          • 0 - for Is. Finds subscribers where the Field is exactly equal to the specified Value.

          • 1 - for IsNot. Finds subscribers where the Field is not equal to the specified Value.

          • 2 - for Contains. Finds subscribers where the Field contains the specified Value.

          • 3 - for DoesNotContain. Finds subscribers where the Field does not contain the specified Value.

          • 4 - for StartsWith. Finds subscribers where the Field starts with the specified Value.

          • 5 - for DoesNotStartWith. Finds subscribers where the Field does not start with the specified Value.

          • 6 - for EndsWith. Finds subscribers where the Field ends with the specified Value.

          • 7 - for DoesNotEndWith. Finds subscribers where the Field does not end with the specified Value.

          • 8 - for IsGreaterThan. Finds subscribers where the Field is greater than the specified Value.

          • 9 - for IsGreaterThanOrEqualTo. Finds subscribers where the Field is greater than or equal to the specified Value.

          • 10 - for IsLessThan. Finds subscribers where the Field is less than the specified Value.

          • 11 - for IsLessThanOrEqualTo. Finds subscribers where the Field is less than or equal to the specified Value.

          • 12 - for IsBefore. Finds subscribers where the Field is before the specified Value.

          • 13 - for IsAfter. Finds subscribers where the Field is after the specified Value.

          • 14 - for IsEmpty. Finds subscribers where the Field has no Value.

          • 15 - for IsNotEmpty. Finds subscribers where the Field contains a Value.

          • 16 - for IsTrue. Finds subscribers where the condition defined by the Field is true.

          • 17 - for IsFalse. Finds subscribers where the condition defined by the Field is false.

          • 24 - for IsBetween. Finds subscribers where the numeric value of a criterion is between two defined numbers.

          • 25 - for IsNotBetween. Finds subscribers where the numeric value of a criterion is not between two defined numbers.

        • Value - the search term used to filter the specified Field.

        • DateFrom - the starting date-time value selected to filter the results. If not selected, this is null.

        • DateTo - the ending date-time value selected to filter the results. If not selected, this is null.

        • Properties - this is null for this case.

        • Subscriteria - this is null for this case.

      • CreatedBy - the IP address used to create the requested segment.

      • CreatedOn - the date-time the requested segment was created.

      • UpdatedBy - the IP address used to update the requested segment.

      • UpdatedOn - the date-time the requested 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.

      • FetchValue - the value used to apply the FetchType filter.

      • Description - contains a string representation of all the selected filters, MatchType and FetchType criteria.

      • SegmentType - the selected segment type for the selected segment criteria. Possible values are:

        • 1 - for Custom

        • 2 - for SystemGenerated

        • 4 - for ReadOnly

Request
GET https://{hostname}/v3/lists/{MailingListID}/segments.{Format}?apikey=
Request
curl --include \
'https://{hostname}/v3/lists/{MailingListID}/segments.{Format}?apikey='
Response
json
{
  "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.

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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:

    • ID - the ID of the segment.

    • Name - the name of the segment.

    • MatchType - specifies how subscribers are returned by your segment based on the 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 the following information for each selected criterion selected for the segment:

      • ID - the ID of the criteria.

      • SegmentID - the ID of the segment.

      • Field - the enum value of the selected filter.

      • CustomFieldID - if the selected filter is a custom field, this is the ID of the custom field.

      • Comparer - the operator that defines how to compare Field and Value. If not specified, Is is assumed.

        • 0 - for Is. Finds subscribers where the Field is exactly equal to the specified Value.

        • 1 - for IsNot. Finds subscribers where the Field is not equal to the specified Value.

        • 2 - for Contains. Finds subscribers where the Field contains the specified Value.

        • 3 - for DoesNotContain. Finds subscribers where the Field does not contain the specified Value.

        • 4 - for StartsWith. Finds subscribers where the Field starts with the specified Value.

        • 5 - for DoesNotStartWith. Finds subscribers where the Field does not start with the specified Value.

        • 6 - for EndsWith. Finds subscribers where the Field ends with the specified Value.

        • 7 - for DoesNotEndWith. Finds subscribers where the Field does not end with the specified Value.

        • 8 - for IsGreaterThan. Finds subscribers where the Field is greater than the specified Value.

        • 9 - for IsGreaterThanOrEqualTo. Finds subscribers where the Field is greater than or equal to the specified Value.

        • 10 - for IsLessThan. Finds subscribers where the Field is less than the specified Value.

        • 11 - for IsLessThanOrEqualTo. Finds subscribers where the Field is less than or equal to the specified Value.

        • 12 - for IsBefore. Finds subscribers where the Field is before the specified Value.

        • 13 - for IsAfter. Finds subscribers where the Field is after the specified Value.

        • 14 - for IsEmpty. Finds subscribers where the Field has no Value.

        • 15 - for IsNotEmpty. Finds subscribers where the Field contains a Value.

        • 16 - for IsTrue. Finds subscribers where the condition defined by the Field is true.

        • 17 - for IsFalse. Finds subscribers where the condition defined by the Field is false.

        • 24 - for IsBetween. Finds subscribers where the numeric value of a criterion is between two defined numbers.

        • 25 - for IsNotBetween. Finds subscribers where the numeric value of a criterion is not between two defined numbers.

      • Value - the search term used to filter the specified Field.

      • DateFrom - the starting date-time value selected to filter the results. If not selected, this is null.

      • DateTo - the ending date-time value selected to filter the results. If not selected, this is null.

      • Properties - this is null for this case.

      • Subscriteria - this is null for this case.

    • CreatedBy - the IP address used to create the requested segment.

    • CreatedOn - the date-time the requested segment was created.

    • UpdatedBy - the IP address used to update the requested segment.

    • UpdatedOn - the date-time the requested 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.

    • FetchValue - the value used to apply the FetchType filter.

    • Description - contains a string representation of all the selected filters, MatchType and FetchType criteria.

Request
GET https://{hostname}/v3/lists/{MailingListID}/segments/{SegmentID}/details.{Format}?apikey=
Request
curl --include \
'https://{hostname}/v3/lists/{MailingListID}/segments/{SegmentID}/details.{Format}?apikey='
Response
json
{
  "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.

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • 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=
Request
curl --include \
'https://{hostname}/v3/lists/{MailingListID}/segments/{SegmentID}/members.{Format}?apikey='
Response
json
{
  "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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • Code - the response code. This is 0 if successful.

  • Error - the response error message. This is null if successful.

  • Context - the ID of the segment created.

Request
POST https://{hostname}/v3/lists/{MailingListID}/segments/create.{Format}?apikey=

Request body:
{
  "Name": "New Customers",
  "MatchType": "All",
  "FetchType": "Top",
  "FetchValue": "200"
}
Request
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data-binary "{
  \"Name\":\"New Customers\",
  \"MatchType\":\"All\",
  \"FetchType\":\"Top\",
  \"FetchValue\":\"200\"
}" \
'https://{hostname}/v3/lists/{MailingListID}/segments/create.{Format}?apikey='
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": 10199
}

Create a segment with criteria

Abstract

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • Code - the response code. This is 0 if successful.

  • Error - the response error message. This is null if successful.

  • Context - the ID of the segment created.

Request
POST https://{hostname}/v3/lists/{MailingListID}/segments/create.{Format}?apikey=

Request body:
{
    "Name": "Engaged and Verified",
    "MatchType": "All",
    "FetchType": "All",
    "Criteria": [
       {
            "Field": "VerifiedForDoubleOptIn",
            "Comparer": "IsTrue"
        },
        {
            "Field": "LinksClicked",
            "Comparer": "Is",
            "Value": "2",
            "LastXMinutes": 43200
        },
        {
            "Field": "Age",
            "Comparer": "Is",
            "Value": "25"
        }
    ]
}
Request
curl --include --globoff --location --request
POST https://{hostname}/v3/lists/{MailingListID}/segments/create.{Format}?apikey=

{
    "Name": "Engaged and Verified",
    "MatchType": "All",
    "FetchType": "All",
    "Criteria": [
        {
            "Field": "VerifiedForDoubleOptIn",
            "Comparer": "IsTrue"
        },
        {
            "Field": "LinksClicked",
            "Comparer": "Is",
            "Value": "2",
            "LastXMinutes": 43200
        },
        {
            "Field": "Age",
            "Comparer": "Is",
            "Value": "25"
        }
    ]
}'
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": 10199
}

Update a segment

Abstract

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • Code - the response code. This is 0 if successful.

  • Error - the response error message. This is null if successful.

  • Context - this is null if successful.

  • SegmentType - the selected segment type for the selected segment criteria. Possible values are:

    • 1 - for Custom

    • 2 - for SystemGenerated

    • 4 - for ReadOnly

Request
POST https://{hostname}/v3/lists/{MailingListID}/segments/{SegmentID}/update.{Format}?apikey=

Request body:
{
  "Name": "Customer Tracking and Opener",
  "MatchType": "Any",
  "FetchType": "All",
  "Criteria": [
    {
      "Field": "AddedAnythingToCart",
      "Comparer": "IsTrue",
      "Times": 2,
      "ProductCode": "123",
      "LastXMinutes": 4320,
      "WebsiteId": "12345678-1234-abdc-efgh-1231bc456efg789hij"
    },
    {
      "Field": "OpenedAnyCampaign",
      "Comparer": "IsTrue",
      "DateFrom": "2019-09-01",
      "DateTo": "2020-12-01"
    }
  ]
}
Request
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data-binary "{
  \"Name\":\"Customer Tracking and Opener\",
  \"MatchType\":\"Any\",
  \"FetchType\":\"All\",
  \"Criteria\": [
      {
        \"Field\":\"AddedAnythingToCart\",
        \"Comparer\":\"IsTrue\",
        \"Times\":2,
        \"ProductCode\":\"123\",
        \"LastXMinutes\":4320,
        \"WebsiteId\":\"12345678-1234-abdc-efgh-1231bc456efg789hij\"
      },
      {
        \"Field\":\"OpenedAnyCampaign\",
        \"Comparer\":\"IsTrue\",
        \"DateFrom\":\"2019-09-01\",
        \"DateTo\":\"2020-12-01\"
      }
    ]
}" \
'https://{hostname}/v3/lists/{MailingListID}/segments/SegmentID/update.{Format}?apikey='
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": null,
  "SegmentType": 1
}

Add criteria to a segment

Abstract

Describes the request and response details of this Moosend API endpoint to add criteria or rules to a specific segment.

POST /lists/{MailingListID}/segments/{SegmentID}/criteria/add.{Format}

Adds a criterion or rule to a specific segment in your 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 that contains the segment.

SegmentID

path

string

true

The ID of the segment.

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.

Field

body

string

true

The criterion used to filter the email list. See Field values.

Comparer

body

string

false

The operator that defines how to compare a Field with its Value. See Comparer values.

Value

body

string

false

The search term used to filter the specified Field.

LastXMinutes

body

integer

false

Constrains the results by the time that has elapsed.

DateFrom to DateTo

body

date

false

Constrains the results by a date span.

DateFunction

body

string

false

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • Code - the response code. This is 0 if successful.

  • Error - the response error message. This is null if successful.

  • Context - the ID of the new criteria added.

Request
POST https://{hostname}/v3/lists/{MailingListID}/segments/{SegmentID}/criteria/add.{Format}?apikey=

Request body:
{
  "Field": "DateAdded",
  "DateFunction": "Year",
  "Comparer": "Is",
  "Value": "2020"
}
Request
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data-binary "{
    \"Field\":\"DateAdded\",
    \"DateFunction\": \"Year\",
    \"Comparer\":\"Is\",\"Value\":\"2020\"
}" \
'https://{hostname}/v3/lists/{MailingListID}/segments/{SegmentID}/criteria/add.{Format}?apikey='
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": 15783
}

Update segment criteria

Abstract

Describes the request and response details of this Moosend API endpoint to update the criteria or rules in a specific segment.

POST /lists/{MailingListID}/segments/{SegmentID}/criteria/{CriteriaID}/update.{Format}

Updates an existing criterion or rule in a specific segment in your 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 that contains the segment.

SegmentID

path

string

true

The ID of the segment.

CriteriaID

path

number(double)

true

The ID of the criteria of a 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.

Field

body

string

true

The criterion used to filter the email list. See Field values.

Comparer

body

string

false

The operator that defines how to compare a Field with its Value. See Comparer values.

Value

body

string

false

The search term used to filter the specified Field.

LastXMinutes

body

integer

false

Constrains the results by the time that has elapsed.

DateFrom to DateTo

body

date

false

Constrains the results by a date span.

DateFunction

body

string

false

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • Code - the response code. This is 0 if successful.

  • Error - the response error message. This is null if successful.

  • Context - the ID of the updated segment.

Request
POST https://{hostname}/v3/lists/{MailingListID}/segments/{SegmentID}/criteria/{CriteriaID}/update.{Format}?apikey=

Request body:
{
  "Field": "LinkURL",
  "Comparer": "is",
  "Value": "https://www.yourpage.com/"
}
Request
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/json" \
     --data-binary "{
    \"Field\":\"LinkURL\",
    \"Comparer\":\"is\",
    \"Value\":\"https://www.yourpage.com/\"
}" \
'https://{hostname}/v3/lists/{MailingListID}/segments/{SegmentID}/criteria/{CriteriaID}/update.{Format}?apikey='
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": 15783
}

Delete a segment

Abstract

Describes the request and response details of this Moosend API endpoint to delete a segment in a mailing list.

DELETE /lists/{MailingListID}/segments/{SegmentID}/delete.{Format}

Deletes a segment including its criteria from a specific email list. Deleting a segment does not affect the email list subscribers.

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 to be deleted.

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.

Response

Status

Description

Headers

Schema

200 OK

The request is successful.

Content-Type:application/json

Accept:application/json

N/A

  • Code - the response code. This is 0 if successful.

  • Error - the response error message. This is null if successful.

  • Context - the response context. This is null if successful.

Request
DELETE https://{hostname}/v3/lists/{MailingListID}/segments/{SegmentID}/delete.{Format}?apikey=
Request
curl --include \
     --request DELETE \
'https://{hostname}/v3/lists/{MailingListID}/segments/{SegmentID}/delete.{Format}?apikey='
Response
json
{
  "Code": 0,
  "Error": null,
  "Context": null
}