Subscribers – managing many subscribers within one request

The same commands used to manage individual subscribers can be used to manage groups of up to 100 subscribers at a time.

Adding groups of subscribers

It is possible to add multiple subscribers to lists or update their statuses to “Active” or “Awaiting Activation”. If only part of the addresses are added (if, for example, an address in incorrect), code 200 will be returned along with data connected with the incorrect addresses.
Call: POST /rest/subscriber/addMultiple
Data in POST:

subscribers Required Table with email addresses and additional fields in the form of{"email" : "adres_email",
"custom_fields":
      { "tag personalisation field 1" : "value",
        "tag personalisation field 1" : "value" }
}
”custom_fields” is not obligatory
list Required Subscribers has list
state Optional Status to be added to subscribers, “Awaiting activation” by default.
confirm Optional If confirmation mail should be sent or not. Possible values are 0 and 1. Confirmation mail sent by default. Field is ignored (mail not sent) if subscriber status is other than “Awaiting activation”.

Sample request:
{"list":"id_hash",
"subscribers" : [ {"email":"tester1@freshmail.com",
        "custom_fields":{"name":"Hanna",
    "promotion_code":"abcde"} },
      {"email":"tester2@freshmail.com",
        "custom_fields":{"name":"Anna",
    "promotion_code":"efgh"} },
      {"email":"tester3@freshmail.com",
        "custom_fields":{"name":"Maria",
    "promotion_code":"wxyz"} } ] }

Error codes:

1331 Adding/updating subscriber failed
1332 Subscriber list or hash doesn’t exist
1335 Attempt to add incorrect subscriber status
1336 No email given to add
1399 Too many subscribers in one command - limit 100

Sample of frequent error, sent request:
{"list":"4zcnmd2ski",
 "subscribers":[{"email":"correct@address.email.com"},
    {"email":"incorrect email addressl"}]}
Returned Data (answer code 200):
{"status":"OK",
 "data":{
"inserted":1,
"not_inserted":1,
"Errors":[{"email":"incorrect email address",
      "error":"Email address not correct",
      "code":1301}]}}
Error codes returned for particular subscribers are identical to the error codes for /rest/subscriber/add

Modifying data for groups of subscribers

Updating and modification for multiple subscribers at once
Call: POST /rest/subscriber/editMultiple
Data in POST:

subscribers Required Table with email address and additional fields in the form of{"email" : "adres_emaiil",
"custom_fields":
      { "tag personalisation field 1" : "value",
        "tag personalisation field 1" : "value" }
}
”custom_fields” is not obligatory
list Required Subscriber hash list
state Optional Status to be added to subscriber, no change by default

Error codes:

1331 Adding/updating subscribers failed
1332 Subscriber list or hash list doesn’t exist
1335 Attempt to add incorrect subscriber status
1336 No addresses given to update
1399 Too many subscribers in one command - limit 100

Returned Data/information about errors are identical to those used in /rest/subscriber/addMultiple

Modifying additional fields for all subscribers

 

Updating selected additional fields and setting values for all subscribers

Call: POST /rest/subscriber/updateFieldValue

Data in POST:

listHash Required Subscriber hash list
tag Required Tag for additional field (ex. Promotional code)
value Required Value for additional field for all subsribers
url Required Online address to which replies are to be sent after updating

Returned Data:

id Process Id

Error codes:

1381 Additional field does not exist
1382 No hash list or tag for additional field
1383 Incorrect URL address
1384 Too many characters in “value” field - max. 255
1385 “Value” field is required
1386 Updating process for field is in progress, wait until finished

Sample error response:
{"status":"ERROR",
"errors":[{
"message":"Incorrect URL address",
"code":1383
}]}
Sample proper response (answer code 200):
{"status":"OK",
  "data":{
"id":5
}}
After updating, the command will be sent to the provided URL. The response will be in the POST format, and the command will contain the following data:

id Id of process
updated Number of updated subscriber fields


Sample commands:

{"status":"OK",
  "data":{
"id":5,
"updated":150
}}
Code with status “OK” is expected after script:
{"status":"OK"}
If the response is incorrect, the script will continue to attempt to communicate but will stop with more errors.

Downloading data from multiple subscribers

If a request is partially incorrect (ex. Email address does not exist) or is completely incorrect (ex. None of the email addresses exist), code 200 will be returned along with data from the incorrect addresses.
Call: POST /rest/subscriber/getMultiple
Data in GET:

subscribers Required Table with user email addresses:[{"email":"tester1@freshmail.com"},
 {"email":"tester2@freshmail.com"},
 {"email":"tester3@freshmail.com"} ]
list Required Subscriber hash list

Returned Data:

email Subscriber email address
state Subscriber status
custom_fields Additional fields with values
errors Table with errors (in cases where certain addresses don’t exist)

Error codes:

1341 Subscriber list does not exist
1342 Table with subscribers is empty
1399 Too many subscribers in command - limit 100

Mass deletion of subscribers

Deleting groups of subscribers from lists

Call: POST /rest/subscriber/deleteMultiple

Data in POST:

subscribers Required Table with user email addresses:

[ {"email":"tester1@freshmailcoml"},

 {"email":"tester2@freshmail.com"},

 {"email":"tester3@freshmail.com”} ]

list Required Subscriber hash list

Error codes:

1351 Subscriber list doesn’t exist
1352 Subscriber lists don’t exist / have been deleted
1399 Too many subscribers in one command - limit 100

Returned data/Information about errors is identical to process for /rest/subscriber/addMultiple

Adding subscribers to list of blocked recipients

Added subscriber addresses to lists of blocked recipients.

Call: POST /rest/subscriber/addBlocks

Data in POST:

emails Required Table with user email addresses:

{ "emails":[

"tester1@freshmail.com",

"tester2@freshmail.com",

"tester3@freshmail.com"

] }

Returned Data:

stats['added'] Number of added subscribers
stats['existing'] Number of existing subscribers
stats['incorrect'] Number of incorrect addresses
Incorrect_mails Table with incorrect addresses

Error codes:

1301 Recipient addresses are incorrect
1336 Recipient addresses not supplied
1343 Format of submitted data is incorrect

Deleting subscribers from blocked recipient lists

Removing subscribers from lists of blocked recipients. This is possible only with addresses you have blocked yourself.

Call: POST /rest/subscriber/removeBlocks

Data in POST:

emails Required Table of user email addresses:

{ "emails":[

"tester1@freshmail.com",

"tester2@freshmail.com",

"tester3@freshmail.com"

]}

Returned Data:

stats['removed'] Number of deleted subscribers
stats['not_existing'] Number of non-existent subscribers
stats['incorrect'] Number of incorrect subscribers

Error codes:

1336 Addresses to add not supplied
1343 Supplied format is incorrect