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:
| 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 |