openapi: 3.2.0 info: title: Moosend Mailing Lists API version: v3 description: '#Moosend API ## Getting started with Moosend API Before making use of our API, please read the following carefully to get you started. ## Making API Requests Both API requests and responses have a format the data is expected to be sent or returned. Requests consist of a URL that specifies which operation to also call, a query string and usually a request stream as well, which specify parameters for the call. For each request there is a syntax pattern for the URL that must be followed for the system to understand your intension. You may find the appropriate pattern for each call in the “Access URLs” sections in our API Documentation pages. Parameters in the query string or the request stream should be specified in a format like: name1=value1&name2=value2&name3=value3&... As you have probably noticed, each name-value pair is separated by a & character. Note also that special characters in values should be URL-encoded. There are built-in URL-encoding functions in all major programming languages like C# and PHP. Please refer to each language’s documentation for more information. The request must also contain information about how you would like the response to be formatted. There are currently two available formats for getting a response: **xml** and **json**. You have to specify the format in every API call as an extension in the URL. So let’s summarize all above with an example request URL and a couple of hypothetical parameters: Example requesting response in xml format: `http://api.moosend.com/v3/somepath/testmethod.xml?param1=value1&m2=value2+with+special+chars+like+%40` Example requesting response in json format: `http://api.moosend.com/v3/somepath/testmethod.json?param1=value1&m2=value2+with+special+chars+like+%40` Note also that you must set the correct accept header in your application’s request in order to retrieve the response data in the expected format. For xml response you must set the accept header to: **application/xhtml+xml,application/xml** For json response you must set the accept header to: **application/json** ## Authentication All API calls require authentication. This is essential for the API to identify which user is making the call so that appropriate results will be returned, as well as for security reasons. Authentication is achieved through the use of an API key. This is a unique key for each account in our system. You can get your API key from the settings page in your account. Please keep your API key safe to prevent any unauthorized access. Once you obtain your API key, you will have to use it in every API call you make. The API key must always be specified as a parameter in the query string of the requesting URL, as in the example below: `http://api.moosend.com/v3/campaigns/create.xml?apikey=YOUR_API_KEY` You may find your API Key or generate a new one in the respective section under the Settings Menu. ## Request Methods There are 3 request methods that you will have to use in order to make full use of our API: GET, POST and DELETE. You must set your application to make each API call using the appropriate request method, which is explicitly specified in our API documentation pages for each call. Let us explain how these methods should be used: **GET:** Used for retrieving data from your account in our system. All request parameters in this case are expected to be found in the request URL, in a format specified explicitly for each API call. You can find detailed information on how to specify parameters for each call in our API documentation pages. You may test a GET request in a web browser, by entering the URL in the address bar. Don''t forget to include your API key parameter in the query string! **POST:** Used for sending information to our system in order to modify data in your account. In this case request parameters should be specified in the request stream. Only authentication and response format are usually expected to be found in the URL, unless differently specified in the “Access URLs” section of our API Documentation pages. Currently, the API accepts only URL-encoded data in the request stream, which is the same format as the one expected for parameter values in the query string. Note also that the content-type header of the request to be made should be “application/x-www-form-urlencoded”. **DELETE:** Used for deleting information from your account. No more different from POST regarding its use. Below is an example of a *POST* request: Request URL: `http://api.moosend.com/v3/campaigns/create.xml?apikey=YOUR_API_KEY` Request Stream: *(assumes hypothetical parameters: Name = New campaign, Subject = Some cool subject, SenderEmail = info@example.com, WebLocation = http://example.com/home/newsletter, MailingListID = 01234567-89ab-cdef-0123-456789abcdef)* `Name=New+campaign&Subject=Some+cool+subject&SenderEmail=info%40example.com& WebLocation=http%3a%2f%2fexample.com%2fhome%2fnewsletter&MailingListID=01234567-89ab-cdef-0123-456789abcdef` ## Changelog + Added HasExternalDoubleOptIn property in [Adding subscribers](https://jsapi.apiary.io/previews/moosendapp/reference/subscribers/add-or-update-subscribers/adding-subscribers) + Added HasExternalDoubleOptIn property in [Adding multiple subscribers](https://jsapi.apiary.io/previews/moosendapp/reference/subscribers/add-or-update-subscribers/adding-multiple-subscribers) + Added HasExternalDoubleOptIn property in [Updating a subscriber](https://jsapi.apiary.io/previews/moosendapp/reference/subscribers/add-or-update-subscribers/updating-a-subscriber)' contact: name: Moosend Support url: https://moosend.com/support/ x-source: Transcribed from the Moosend API Blueprint published by Moosend at https://moosendapp.docs.apiary.io/api-description-document (FORMAT 1A, HOST https://api.moosend.com/v3). servers: - url: https://api.moosend.com/v3 security: - apikeyQuery: [] tags: - name: Mailing Lists paths: /lists.{Format}: get: operationId: gettingAllActiveMailingLists summary: Getting all active mailing lists description: Gets a list of your active mailing lists in your account. tags: - Mailing Lists parameters: - name: Format in: path required: true schema: type: string example: json - name: apikey in: query required: true schema: type: string description: Account API key. Passed as a query-string parameter on every call. - name: WithStatistics in: query required: false schema: type: string - name: ShortBy in: query required: false schema: type: string - name: SortMethod in: query required: false schema: type: string responses: '200': description: Successful response content: application/json: schema: type: object properties: Code: description: The response code for this call. This will be 0 if successful. Error: description: The response error message. This will be null if successful. Context: description: 'This contains all the following information for the requested mailing list:' Paging: description: A list with all the following paging information. MailingLists: description: 'A list with mailing lists containing the following information for each list:' CreatedBy: description: The ip that requested mailing list was created from. CreatedOn: description: The date time that the requested mailing list was created. UpdatedBy: description: The ip that the requested mailing list was updated from. UpdatedOn: description: The date time that the requested mailing list was updated ImportOperation: description: The details of the latest import operation that was performed in the requested mailing list. This will be blank if no import operation was performed for this list. example: 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 - 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 security: - apikeyQuery: [] /lists/{Page}/{PageSize}.{Format}: get: operationId: gettingAllActiveMailingListsWithPaging summary: Getting all active mailing lists with paging description: Gets a list of your active mailing lists in your account. Because the results for this call could be quite big, paging information is required as input. tags: - Mailing Lists parameters: - name: Page in: path required: true schema: type: number example: '1' - name: PageSize in: path required: true schema: type: number example: '20' - name: Format in: path required: true schema: type: string example: json - name: apikey in: query required: true schema: type: string description: Account API key. Passed as a query-string parameter on every call. - name: ShortBy in: query required: false schema: type: string description: The name of the campaign property to sort results by. If not specified, results will be sorted by the CreatedOn property - name: SortMethod in: query required: false schema: type: string description: 'The method to sort results: ASC for ascending, DESC for descending. If not specified, `ASC` will be assumed' responses: '200': description: Successful response content: application/json: schema: type: object properties: Code: description: The response code for this call. This will be 0 if successful. Error: description: The response error message. This will be null if successful. Context: description: 'This contains all the following information for the requested mailing list:' Paging: description: 'A list with all the following paging information:' MailingLists: description: 'A list with mailing lists. Contains the following information for each list:' CreatedBy: description: The ip from where the requested mailing list was created CreatedOn: description: The date time that the requested mailing list was created UpdatedBy: description: The ip from where the requested mailing list was updated UpdatedOn: description: The date time that the requested mailing list was updated ImportOperation: description: The details of the latest import operation that was performed for the requested mailing list. Will be blank if no import operation was performed for this list. example: Code: 0 Error: null Context: Paging: PageSize: 20 CurrentPage: 1 TotalResults: 92 TotalPageCount: 5 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 - ID: 4d90a60c-fad2-4f29-b541-318f0ea82be6 Name: Some Name ActiveMemberCount: 0 BouncedMemberCount: 0 RemovedMemberCount: 0 UnsubscribedMemberCount: 0 Status: 0 CustomFieldsDefinition: [] CreatedBy: 192.168.1.1 CreatedOn: /Date(1400765707432)/ UpdatedBy: 192.168.1.1 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 security: - apikeyQuery: [] /lists/{MailingListID}/details.{Format}: get: operationId: gettingMailingListDetails summary: Getting mailing list details description: Gets details for a given mailing list. You may include subscriber statistics in your results or not. Any segments existing for the requested mailing list will not be included in the results. tags: - Mailing Lists parameters: - name: MailingListID in: path required: true schema: type: string example: a589366a-1a34-4965-ac50-f1299fe5979e - name: Format in: path required: true schema: type: string example: json - name: apikey in: query required: true schema: type: string description: Account API key. Passed as a query-string parameter on every call. - name: WithStatistics in: query required: false schema: type: string responses: '200': description: Successful response content: application/json: schema: type: object properties: Code: description: The response code for this call. This will be 0 if successful. Error: description: The response error message. This will be null if successful. Context: description: 'This contains all the following information for the requested mailing list:' ID: description: The id of the requested mailing list. Name: description: The name of the requested mailing list. ActiveMemberCount: description: The number of the active members for the requested mailing list. BouncedMemberCount: description: The number of the bounced emails for the requested mailing list. RemovedMemberCount: description: The number of the removed emails for the requested mailing list. UnsubscribedMemberCount: description: The number of the unsubscribed emails for the requested mailing list. Status: description: The status of the requested mailing list. CustomFieldsDefinition: description: The details of each custom field for the requested mailing list. This will be blank if there are no custom fields for this mailing list. CreatedBy: description: The ip from where the requested mailing list was created. CreatedOn: description: The date time that the requested mailing list was created. UpdatedBy: description: The ip from where the requested mailing list was updated. UpdatedOn: description: The date time that the requested mailing list was updated. ImportOperation: description: The details of the latest import operation that was performed in the requested mailing list. example: Code: 0 Error: null Context: ID: 28132257-f655-49a4-8af7-6fbf31645641 Name: test auto ActiveMemberCount: 19999 BouncedMemberCount: 0 RemovedMemberCount: 0 UnsubscribedMemberCount: 0 Status: 1 CustomFieldsDefinition: - ID: c3226cc-8a18-4f22-907b-8422d61a53a1 Name: Gender Context: MaleMaleFemaleFemale IsRequired: true Type: 3 - ID: bf14b37c-3c47-412d-baf1-c6850b8cf2af Name: Town Context: null IsRequired: false Type: 0 CreatedBy: 223.16.165.23 CreatedOn: /Date(1443174387327+0100)/ UpdatedBy: 223.16.165.23 UpdatedOn: /Date(1443174387327+0100)/ ImportOperation: ID: 3706 DataHash: 2490c26c-79f6-a52c-4afb-852f624a91b0 Mappings: Email EmailNotify: null CreatedOn: /Date(1443181931130+0100)/ StartedOn: /Date(1443181958330+0100)/ CompletedOn: /Date(1443182730673+0100)/ TotalInserted: 19999 TotalUpdated: 0 TotalUnsubscribed: 1 TotalInvalid: 0 TotalIgnored: 0 TotalDuplicate: 0 TotalMembers: 20000 Message: null Success: true SkipNewMembers: false security: - apikeyQuery: [] /lists/create.{Format}: post: operationId: creatingAMailingList summary: Creating a mailing list description: Creates a new empty mailing list in your account. tags: - Mailing Lists parameters: - name: Format in: path required: true schema: type: string example: json - name: apikey in: query required: true schema: type: string description: Account API key. Passed as a query-string parameter on every call. requestBody: required: true content: application/json: schema: type: object properties: Name: type: string description: The name of the new mailing list. ***(Required)*** ConfirmationPage: type: string description: The URL of the page that will be displayed at the end of the subscription process. ***(Optional)*** RedirectAfterUnsubscribePage: type: string description: The URL of the page that users will be redirected after unsubscribing from your mailing list. ***(Optional)*** example: Name: New List ConfirmationPage: www.someUrl.com RedirectAfterUnsubscribePage: www.someUrl.com responses: '200': description: Successful response content: application/json: schema: type: object properties: Code: description: The response code for this call. This will be 0 if successful. Error: description: The response error message. This will be null if successful. Context: description: The unique id for the mailing list created. example: Code: 0 Error: null Context: 6ca52d31-765c-4760-a78e-91e511e49d76 security: - apikeyQuery: [] /lists/{MailingListID}/update.{Format}: post: operationId: updatingAMailingList summary: Updating a mailing list description: Updates the properties of an existing mailing list. tags: - Mailing Lists parameters: - name: MailingListID in: path required: true schema: type: string description: The ID of the mailing list to be updated. example: a589366a-1a34-4965-ac50-f1299fe5979e - name: Format in: path required: true schema: type: string example: json - name: apikey in: query required: true schema: type: string description: Account API key. Passed as a query-string parameter on every call. requestBody: required: true content: application/json: schema: type: object properties: Name: type: string description: The name of the updated mailing list. ***(Required)*** ConfirmationPage: type: string description: The URL of the page that will be displayed at the end of the subscription process. ***(Optional)*** RedirectAfterUnsubscribePage: type: string description: The URL of the page that users will be redirected after unsubscribing from your mailing list. ***(Optional)*** example: Name: New List Name ConfirmationPage: www.someotherUrl.com RedirectAfterUnsubscribePage: www.someotherUrl.com responses: '200': description: Successful response content: application/json: schema: type: object properties: Code: description: The response code for this call. This will be 0 if successful. Error: description: The response error message. This will be null if successful. Context: description: The unique id for the updated mailing list. example: Code: 0 Error: null Context: e5f6c0a3-1fe6-4d89-951e-eafae0b01368 security: - apikeyQuery: [] /lists/{MailingListID}/delete.{Format}: delete: operationId: deletingAMailingList summary: Deleting a mailing list description: Deletes a mailing list from your account. tags: - Mailing Lists parameters: - name: MailingListID in: path required: true schema: type: string example: b9c67cb4-a821-4187-930d-79d81a3067df - name: Format in: path required: true schema: type: string example: json - name: apikey in: query required: true schema: type: string description: Account API key. Passed as a query-string parameter on every call. responses: '200': description: Successful response content: application/json: schema: type: object properties: Code: description: The response code for this call. This will be 0 if successful. Error: description: The response error message. This will be null if successful. Context: description: Context will be null if successful. example: Code: 0 Error: null Context: null security: - apikeyQuery: [] /lists/{MailingListID}/customfields/create.{Format}: post: operationId: creatingACustomField summary: Creating a custom field description: Creates a new custom field in the specified mailing list. tags: - Mailing Lists parameters: - name: MailingListID in: path required: true schema: type: string example: a589366a-1a34-4965-ac50-f1299fe5979e - name: Format in: path required: true schema: type: string example: json - name: apikey in: query required: true schema: type: string description: Account API key. Passed as a query-string parameter on every call. requestBody: required: true content: application/json: schema: type: object properties: Name: type: string description: The name of the custom field. ***(Required)*** CustomFieldType: type: string description: Specifies the data type of the custom field. This must be one of the following values. ***(Optional)***
If omitted, Text will be assumed. Options: type: string description: If you want to create a custom field of type SingleSelectDropdown, you must set this parameter to specify the available options for the user to choose from. Use a comma (,) to separate different options. ***(Optional)*** IsRequired: type: string description: Specify whether this field will be mandatory on not, when a subscriber is added to your list by any means. You should specify a value of either true or false. If omitted, false will be assumed. ***(Optional)*** IsHidden: type: string description: Specify whether this field will be visible by your subscribers on not, in their update profile page. If omitted, false will be assumed. ***(Optional)*** example: Name: Town CustomFieldType: SingleSelectDropdown Options: Athens,London,New York responses: '200': description: Successful response content: application/json: schema: type: object properties: Code: description: The response code for this call. This will be 0 if successful. Error: description: The response error message. This will be null if successful. Context: description: The unique id for the new custom field. example: Code: 0 Error: null Context: b42b4e0f-ca2f-403d-8231-32a2405651af security: - apikeyQuery: [] /lists/{MailingListID}/customfields/{CustomFieldID}/update.{Format}: post: operationId: updatingACustomField summary: Updating a custom field description: Updates the properties of an existing custom field in the specified mailing list. tags: - Mailing Lists parameters: - name: MailingListID in: path required: true schema: type: string example: a589366a-1a34-4965-ac50-f1299fe5979e - name: CustomFieldID in: path required: true schema: type: string example: b42b4e0f-ca2f-403d-8231-32a2405651af - name: Format in: path required: true schema: type: string example: json - name: apikey in: query required: true schema: type: string description: Account API key. Passed as a query-string parameter on every call. requestBody: required: true content: application/json: schema: type: object properties: Name: type: string description: The name of the custom field. ***(Required)*** CustomFieldType: type: string description: Specifies the data type of the custom field. This must be one of the following values. ***(Optional)***
If omitted, Text will be assumed. Options: type: string description: If you want to create a custom field of type SingleSelectDropdown, you must set this parameter to specify the available options for the user to choose from. Use a comma (,) to separate different options. ***(Optional)*** IsRequired: type: string description: Specify whether this field will be mandatory on not, when a subscriber is added to your list by any means. You should specify a value of either true or false. If omitted, false will be assumed. ***(Optional)*** IsHidden: type: string description: Specify whether this field will be visible by your subscribers on not, in their update profile page. If omitted, false will be assumed. ***(Optional)*** example: Name: City CustomFieldType: SingleSelectDropdown Options: Frankfurt,London,Paris,Rome responses: '200': description: Successful response content: application/json: schema: type: object properties: Code: description: The response code for this call. This will be 0 if successful. Error: description: The response error message. This will be null if successful. Context: description: The unique id for the updated custom field. example: Code: 0 Error: null Context: null security: - apikeyQuery: [] /lists/{MailingListID}/customfields/{CustomFieldID}/delete.{Format}: delete: operationId: removingACustomField summary: Removing a custom field description: Removes a custom field definition from the specified mailing list. tags: - Mailing Lists parameters: - name: MailingListID in: path required: true schema: type: string example: a589366a-1a34-4965-ac50-f1299fe5979e - name: CustomFieldID in: path required: true schema: type: string example: b42b4e0f-ca2f-403d-8231-32a2405651af - name: Format in: path required: true schema: type: string example: json - name: apikey in: query required: true schema: type: string description: Account API key. Passed as a query-string parameter on every call. responses: '200': description: Successful response content: application/json: schema: type: object properties: Code: description: The response code for this call. This will be 0 if successful. Error: description: The response error message. This will be null if successful. Context: description: Context will be null if successful. example: Code: 0 Error: null Context: null security: - apikeyQuery: [] components: securitySchemes: apikeyQuery: type: apiKey in: query name: apikey description: Moosend account API key, supplied as the `apikey` query-string parameter on every request. Generated in the account Settings menu.