API Reference
Your guide to getting things done
Search our documentation articles

Your complete guide to mastering Moosend. Search to get started.

Create an email list and add subscribers

Article: 000054554
Updated: September 11, 2025

Walkthrough: Create a mailing list and add subscribers

Abstract

Provides a walkthrough in making your first requests to the Moosend API to create a new email list and add multiple subscribers to the list.

This walkthrough shows how you can make your first calls to the Moosend API. When making API requests, you must always locate the specific API endpoints and parameters you need in API reference.

In this example, you create two requests using two API endpoints.

This walkthrough describes how to:

Create a new email list using the API

To create a new email list using the API:

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

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

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

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

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

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

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

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

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

  7. Send your API request. If successful, you get a response with HTTP code 200, a Content-Type: application/json response header, and the following JSON response:

    {
  "Code": 0,
  "Error": null,
  "Context": "6ca52d31-765c-4760-a78e-91e511e49d76"
}

    The response body contains the Context parameter that gives you the ID of the new email list created. You can now use this ID to add subscribers to your new email list using the next API endpoint.

Add subscribers to your new email list using the API

To add subscribers to your new email list:

  1. Go to the Add multiple subscribers endpoint reference.

  2. Create a POST request using /subscribers/{MailingListID}/subscribe-many.{Format}.

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

  4. Add the required path parameters in the request URL. Possible values for Format are json or xml. For MailingListID, use the ID of the new email list you created.

    For example, if you select a JSON format and use the new email list ID, you can edit the URL as:

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

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

    For example, you can add your API key as https://{hostname}/v3/subscribers/6ca52d31-765c-4760-a78e-91e511e49d76/subscribe-many.json?apikey=bafe55f4-e53e-4651-8164-c6d6ff05081b

  6. Add the required request body parameters for Subscribers. You must specify the Name, Email, and CustomEields for each subscriber on this list. Optionally, you can add the HasExternalDoubleOptIn parameter.

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

  7. Send your API request. If successful, you get a response with HTTP code 200, a Content-Type: application/json response header, and the following JSON response:

    {
  "Code": 0,
  "Error": "2 items with invalid email address were ignored: email@email, email2@email",
  "Context": [
    {
      "ID": "ca506fc5-0967-4756-8848-74e9766bdbdd",
      "Name": "test1Email",
      "Email": "test1@test.com",
      "CreatedOn": "/Date(1465377493907+0100)/",
      "UpdatedOn": "/Date(1465381164389)/",
      "UnsubscribedOn": null,
      "UnsubscribedFromID": null,
      "SubscribeType": 1,
      "SubscribeMethod": 1,
      "CustomFields": [
        {
          "CustomFieldID": "42acf2cf-1096-4c80-960b-051791d9a276",
          "Name": "Country",
          "Value": "UK"
        }
      ],
      "RemovedOn": null
    },
    {
      "ID": "b751f349-f6b3-4b14-8d75-c37dfafbe40a",
      "Name": "test2133Email",
      "Email": "test2133@test.com",
      "CreatedOn": "/Date(1465377493907+0100)/",
      "UpdatedOn": "/Date(1465381164389)/",
      "UnsubscribedOn": null,
      "UnsubscribedFromID": null,
      "SubscribeType": 1,
      "SubscribeMethod": 1,
      "CustomFields": [
        {
          "CustomFieldID": "60d4e2b0-e5ae-4737-9ac5-ce071ab346fb",
          "Name": "Age",
          "Value": 25
        },
        {
          "CustomFieldID": "42acf2cf-1096-4c80-960b-051791d9a276",
          "Name": "Country",
          "Value": "USA"
        }
      ],
      "RemovedOn": null
    }
  ]
}

    The response body contains the Context parameter that gives you the ID and details of each subscriber added to the new email list.

Related Answers

Moosend Logo

Copyright © 2026 · All Rights Reserved · Moosend · Privacy Policy