Subscribers

Add a new subscriber

POST /subscribers/{MailingListID}/subscribe.{Format}

Adds a new subscriber to a specific email list in your Sitecore Send account. If the subscriber with the specified email address already exists in the list, the list is instead updated.

Note

When you add a single subscriber to an email list manually or through the API, the subscriber is added regardless of whether the subscriber has previously been unsubscribed.

Request

Parameter	In	Type	Required	Description
Accept	header	string	true	Determines the expected format and data type to retrieve the response data.Value: application/json
MailingListID	path	string	true	The ID of the email list where you want to add a new subscriber.
Format	path	string	true	The supported file format for getting a response.Possible values: json and xml.
apikey	query	string	true	The API key of your account.
Name	body	string	false	The name of the new subscriber.
Email	body	string	true	The email address of the new subscriber.
HasExternalDoubleOptIn	body	Boolean	false	When true, it flags the added subscriber as having given subscription consent by other means.
CustomFields	body	array	false	A list of name-value pairs that match the subscriber’s custom fields defined in the email list. (for example, Name or Country).When updating an existing member, any custom fields that are not included in the request will have their values cleared. To preserve existing data, include values for all custom fields associated with the list.
Tags	body	object	false	The member tag you can use to filter members by when working with an email list.
Preferences	body	object	false	The member preferences you can use to segment or filter members by, when working with an email list.

POST https://{hostname}/v3/subscribers/{MailingListID}/subscribe.{Format}?apikey=

{
    "Name" : "Paul",
    "Email" : "[email protected]",
    "HasExternalDoubleOptIn": false,
    "CustomFields": \[
        "Age=25",
        "Country=USA"
    \],
    "Tags": \[
        "repeater"
    \],
    "Preferences": \[
      "option a",
      "option b",
      "option c"
    \]
}

curl --include \\
     --request POST \\
     --header "Content-Type: application/json" \\
     --header "Accept: application/json" \\
     --data-raw '{
    "Name" : "Paul",
    "Email" : "[email protected]",
    "HasExternalDoubleOptIn": false,
    "CustomFields": \[
        "Age=25",
        "Country=USA"
    \],
    "Tags": \[
        "repeater"
    \],
    "Preferences": \[
        "option a",
        "option b",
        "option c"
    \]
}' \\
'https://{hostname}/v3/subscribers/{MailingListID}/subscribe.{Format}?apikey='

Response

Status	Description	Headers	Schema
200 OK	The request is successful.	Content-Type /json	N/A

Code - the response code. This is 0 if successful.
Error - the response error message. This is null if successful.
Context - an object that contains all the following information for the new subscriber added to the email list:
- ID - the ID of the subscriber.
- Name - the name of the subscriber.
- Email - the email address of the subscriber.
- CreatedOn - the date-time the subscriber was added to the email list.
- UnsubscribedOn - the date-time the subscriber was unsubscribed from the email list. This is null if not unsubscribed from the list.
- UnsubscribedFromID - the ID that the subscriber is unsubscribed from.
- SubscribeType - the status of the subscriber. For subscribed, this is 1, for unsubscribed, this is 2, for bounced, this is 3 , and for removed, this is 4.
- SubscribeMethod - the method used to subscribe the member to the email list. For subscription forms, this is 0, for file imports, this is 1, for manually added, this is 2.
- CustomFields - a list containing the custom fields of the new subscriber. Each custom field contains the following:
  - CustomFieldID - the ID of the custom field.
  - Name - the name of the custom field.
  - Value - the value of the custom field.
- RemovedOn - the date-time the subscriber was removed from the email list.
- Tags - a list containing the tags of the new subscriber.

{
  "Code": 0,
  "Error": null,
  "Context": {
    "ID": "f582c388-7916-4890-a9ab-b592615ef095",
    "Name": "Paul",
    "Email": "[email protected]",
    "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,
    "Tags": \[
       "potential",
       "repeater"
    \]  
    }
}

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