openapi: 3.2.0 info: title: Moosend Subscribers 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: Subscribers paths: /lists/{MailingListID}/subscribers/{Status}.{Format}: get: operationId: gettingSubscribers summary: Getting subscribers description: Gets a list of all subscribers in a given mailing list. You may filter the list by setting a date to fetch those subscribed since then and/or by their status. Because the results for this call could be quite big, paging information is required as input. tags: - Subscribers parameters: - name: MailingListID in: path required: true schema: type: string example: a589366a-1a34-4965-ac50-f1299fe5979e - name: Status in: path required: true schema: type: string example: Subscribed - 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: Page in: query required: false schema: type: number - name: PageSize in: query required: false schema: type: number 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 response context. This contains all the following information for the subscribers of requested mailing list:' Paging: description: A list with all the following paging information. Subscribers: description: 'A list with all the subscribers for the requested mailing list, with all the following information:' CustomFields: description: A list with all the custom fields for the requested mailing list. example: 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 - ID: 83485f6c-569c-4012-ab2e-f91d3f888995 Name: Andreas Email: andreas@moosend.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 security: - apikeyQuery: [] /subscribers/{MailingListID}/view.{Format}: get: operationId: getSubscriberByEmailAddress summary: Get subscriber by email address description: Searches for a subscriber with the specified email address in the specified mailing list and returns detailed information such as id, name, date created, date unsubscribed, status and custom fields tags: - Subscribers 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: Email 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: 'The response context. Contains all the following information for the requested subscriber:' example: Code: 0 Error: null Context: ID: 9bef1735-f04d-4472-b029-68eb7fa2cfe7 Name: Andreas Email: andreas@moosend.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 security: - apikeyQuery: [] /subscribers/{MailingListID}/find/{SubscriberID}.{Format}: get: operationId: getSubscriberById summary: Get subscriber by id description: Searches for a subscriber with the specified unique id in the specified mailing list and returns detailed information such as email, name, date created, date unsubscribed, status and custom fields. tags: - Subscribers parameters: - name: MailingListID in: path required: true schema: type: string example: a589366a-1a34-4965-ac50-f1299fe5979e - name: SubscriberID in: path required: true schema: type: string example: 118e41dc-bb9e-435d-a86a-e5bd374668a8 - 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: 'The response context. Contains all the following information for the requested subscriber:' example: Code: 0 Error: null Context: ID: 118e41dc-bb9e-435d-a86a-e5bd374668a8 Name: Some name Email: getmoocampaigns+1@gmail.com CreatedOn: /Date(1464952683773+0100)/ UpdatedOn: /Date(1465380328390+0100)/ UnsubscribedOn: null UnsubscribedFromID: null SubscribeType: 4 SubscribeMethod: 2 CustomFields: [] RemovedOn: /Date(1465381597743+0100)/ security: - apikeyQuery: [] /subscribers/{MailingListID}/subscribe.{Format}: post: operationId: addingSubscribers summary: Adding subscribers description: Adds a new subscriber to the specified mailing list. If there is already a subscriber with the specified email address in the list, an update will be performed instead. The rate limit for this request is 10 requests per 10 seconds (*per API key). tags: - Subscribers 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 member. ***(Optional)*** Email: type: string description: The email address of the member. ***(Required)*** HasExternalDoubleOptIn: type: string description: When true, flags the added member as having given their subscription consent by other means. ***(Optional)*** CustomFields: type: string description: A list of name-value pairs that match the member's custom fields defined in the mailing list. ***(Optional)*** example: Name: Paul Email: someEmail@email.com HasExternalDoubleOptIn: false CustomFields: - Age=25 - Country=USA 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 response context. Contains all the following information for the requested subscriber:' example: 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 security: - apikeyQuery: [] /subscribers/{MailingListID}/subscribe_many.{Format}: post: operationId: addingMultipleSubscribers summary: Adding multiple subscribers description: This method allows you to add multiple subscribers in a mailing list with a single call. If some subscribers already exist with the given email addresses, they will be updated. If you try to add a subscriber with an invalid email address, this attempt will be ignored, as the process will skip to the next subscriber automatically. The rate limit for this request is 2 requests per 10 seconds (*per API key). tags: - Subscribers 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: HasExternalDoubleOptIn: type: string description: When true, flags the added members as having given their subscription consent by other means. ***(Optional)*** Subscribers: type: string description: A list of up to 1000 subscribers to add to the mailing list. You may specify the email address, the name and the custom fields for each subscriber. ***(Required)*** example: HasExternalDoubleOptIn: false Subscribers: - Name: test1Email Email: test1@test.com CustomFields: - Country=UK - Name: test2133Email Email: test2133@test.com CustomFields: - Age=25 - Country=USA 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 will show how many and which emails are invalid. It will be null if all emails are valid. Context: description: 'A list with response contexts. Each context contains all the following information for each subscriber:' example: 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 security: - apikeyQuery: [] /subscribers/{MailingListID}/update/{SubscriberID}.{Format}: post: operationId: updatingASubscriber summary: Updating a subscriber description: Updates a subscriber in the specified mailing list. tags: - Subscribers parameters: - name: MailingListID in: path required: true schema: type: string example: a589366a-1a34-4965-ac50-f1299fe5979e - name: SubscriberID in: path required: true schema: type: string example: 118e41dc-bb9e-435d-a86a-e5bd374668a8 - 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 member. ***(Optional)*** Email: type: string description: The email address of the member. ***(Required)*** HasExternalDoubleOptIn: type: string description: When true, flags the added member as having given their subscription consent by other means. ***(Optional)*** CustomFields: type: string description: A list of name-value pairs that match the member's custom fields defined in the mailing list. ***(Optional)*** example: Name: Some Name HasExternalDoubleOptIn: false Email: someEmail@email.com CustomFields: - Age=25 - Country=USA 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 response context. Contains all the following information for the requested subscriber:' example: 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 security: - apikeyQuery: [] /subscribers/unsubscribe.{Format}: post: operationId: unsubscribingSubscribersFromAccount summary: Unsubscribing subscribers from account description: Unsubscribes a subscriber from the account. The rate limit for this request is 20 requests per 10 seconds (*per API key). tags: - Subscribers 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: Email: type: string description: The email address of the member. ***(Required)*** example: Email: test1@test.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 message for this call. This will be null if successful. Context: description: The response context for this call. This will be null if successful. example: Code: 0 Error: null Context: null security: - apikeyQuery: [] /subscribers/{MailingListID}/unsubscribe.{Format}: post: operationId: unsubscribingSubscribersFromMailingList summary: Unsubscribing subscribers from mailing list description: Unsubscribes a subscriber from the specified mailing list. The rate limit for this request is 20 requests per 10 seconds (*per API key). tags: - Subscribers 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: Email: type: string description: The email address of the member. ***(Required)*** example: Email: test1@test.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 message for this call. This will be null if successful. Context: description: The response context for this call. This will be null if successful. example: Code: 0 Error: null Context: null security: - apikeyQuery: [] /subscribers/{MailingListID}/{CampaignID}/unsubscribe.{Format}: post: operationId: unsubscribingSubscribersFromMailingListAndASpecifiedCampaign summary: Unsubscribing subscribers from mailing list and a specified campaign description: Unsubscribes a subscriber from the specified mailing list and the specified campaign. This call will take into account the setting you have in "unsubscribe settings" and will remove the subscriber from all other mailing lists or not accordingly. The rate limit for this request is 20 requests per 10 seconds (*per API key). tags: - Subscribers parameters: - name: MailingListID in: path required: true schema: type: string example: a589366a-1a34-4965-ac50-f1299fe5979e - name: CampaignID in: path required: true schema: type: string example: cbcb297d-52a8-4bed-ae85-640c37c92771 - 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: Email: type: string description: The email address of the member. ***(Required)*** example: Email: test1@test.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 message for this call. This will be null if successful. Context: description: The response context for this call. This will be null if successful. example: Code: 0 Error: null Context: null security: - apikeyQuery: [] /subscribers/{MailingListID}/remove.{Format}: post: operationId: removingASubscriber summary: Removing a subscriber description: Removes a subscriber from the specified mailing list permanently (without moving to the suppression list). tags: - Subscribers 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: Email: type: string description: The email address of the member. ***(Required)*** example: Email: test1@test.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 message for this call. This will be null if successful. Context: description: The response context for this call. This will be null if successful. example: Code: 0 Error: null Context: null security: - apikeyQuery: [] /subscribers/{MailingListID}/remove_many.{Format}: post: operationId: removingMultipleSubscribers summary: Removing multiple subscribers description: Removes a list of subscribers from the specified mailing list permanently (without putting them in the suppression list). Any invalid email addresses specified will be ignored. tags: - Subscribers 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 example: Emails: someEmail@email.com,someEmail2@email.com,someEmail3@email.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 message for this call. This will be null if successful. Context: description: 'The response context for this call. This contains the following:' example: Code: 0 Error: null Context: EmailsIgnored: 0 EmailsProcessed: 3 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.