Moosend Subscribers API

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