Moosend API

openapi: 3.1.0
info:
  title: Moosend 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
tags:
- name: Mailing Lists
- name: Subscribers
- name: Campaigns
- name: Segments
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: <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
                  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)***
                    <br/> 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 thi

# --- truncated at 32 KB (176 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/moosend/refs/heads/main/openapi/moosend-openapi.yml