Subscribers – managing subscribers

This control module is used to add and update data about subscribers in the subscription lists.

Status codes for subscribers

Status Value  Description
Active 1 An active subscriber that can receive campaigns
Awaiting activation 2 The subscriber must click on an activation link to confirm his subscription
Not activated 3 The confirmation link sent to this subscriber expired after the defined validation period passed
Resigned 4 The subscriber resigned from the mailing list
Soft bounce 5 A subscriber with an address that produced several consecutive “soft” bounces
Hard bounce 8 A subscriber with an address that produced several consecutive “hard” bounces

Adding subscribers

Method for adding subscribers not on a mailing list or with without a status of “Active” or “Awaiting activation”

To execute this action:

POST /rest/subscriber/add

Data in POST: 

email   required  Email address of subscriber
list   required  Subscriber list hash
state   optional  The status that we want to give the subscriber, if the field is  left empty it will be labeled “awaiting activation”.
confirm   optional  Determines if subscriber is sent confirmation email or not.  Possible values are 0 or 1. If field is left empty, subscriber will  be sent confirmation mail. The field is ignored - no  confirmation mail will be sent - if the subscriber has any status  other than “to be activated”.
custom_fields   optional  Additional fields and values in the form of (personalized field  1: “value”, personalized field 2: “value”).

Error codes:

1301 Email address is incorrect
1302 Subscriber list does not exist or there is not hash
1303 One or more additional fields is incorrect
1304 Subscriber does not exist on this subscriber list and is active or to be activated
1305 Invalid subscriber status

Modifying subscriber data

Updating subscriber statuses and data

To execute this action:

POST /rest/subscriber/edit

Data in POST: 

email required

  Subscriber email address

list required

  Subscriber list hash

state optional

  The status that we want to assign to the subscriber, if field is       left empty subscriber status is not changed.

custom_fields optional

  Additional fields and values in the form of (personalized field 1:   “value”, personalized field 2: “value”).

 Error codes:

1331 Subscriber doesn’t exist
1302 Subscriber list does not exist or there is not hash
1305 Invalid subscriber status

Downloading subscriber data

To execute this action:

GET /rest/subscriber/get/[list]/[email]

Data in GET:

email required   Subscriber email address
list required   Subscriber list hash

 

Received data:

email Subscriber email address
state Subscriber status
custom_fields Value of additional fields for subscriber
id_hash Unique campaign identifier

Error codes:

1311 Incorrect email address
1312 Subscriber list does not exist

Deleting subscribers

How to delete subscribers from a list.

To execute this action:

POST /rest/subscriber/delete

Data in POST:

email required   Subscriber email
list required   Subscriber list hash

 

Error codes:

1321 Email address does not exist on subscriber list
1322 Subscriber list does not exist or list has no hash

Download subscriber action history

How to download subscriber action history.

To execute this action:

POST /rest/subscriber/getHistory

Data in POST:

email required   Subscriber email address
list required   Subscriber list hash
limit optional   Number of subscriber actions to download (default 10)

 

Sample request:

{"email":"tester1@freshmail.com"
"list":"4zcnmd2ski"
"limit":"30"}

Received data:

name Name of campaign
email_topic Subject of campaign
scheduled_sent Date and time of sent campaign (in yyyy-mm-dd and hh-ii-ss format)
state Subscriber status - deliveries, soft bounces, hard bounces
opens_count Number of subscriber opens
clicks_count Number of subscriber clicks

 

Error codes:

1311 Incorrect email address
1312 Subscriber list does not exist
1313 Subscriber does not exist on given subscriber list
1314 Attribute value limit is incorrect
1315 Subscriber does not have an action

 

Example of incorrect reply:

{"status":"ERROR",
"errors":[{
"message":"Subscriber doesn't exist",
"code":1313 }]}

Example of correct reply:

{"status":"OK",
"data":[{
"name":"4 campaign sent on 30.07.2013",
"email_topic":"Autumn promotion",
"scheduled_sent":"2013-07-30 21:37:42",
"state":"DELIVERED",
"opens_count":"1",
"clicks_count":"2" }]}