Walkthrough: Create a mailing list and add subscribers

This walkthrough shows how you can make your first calls to the Sitecore Send 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
Add subscribers to your new email list using the API

Create a new email list using the API

To create a new email list using the API:

Go to the Create a mailing list endpoint reference.
Create a POST request using /lists/create.{Format}.
Add your request header. You can use the following value: Content-Type:application/json.
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.
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.

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

curl

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

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:
json
{ "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:

Go to the Add multiple subscribers endpoint reference.
Create a POST request using /subscribers/{MailingListID}/subscribe_many.{Format}.
Add your request header. You can use the following value: Content-Type:application/json.
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
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

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

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

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:

json

{
  "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": "[email protected]",
      "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": "[email protected]",
      "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.

If you have suggestions for improving this article, let us know!