Subskrybenci – zarządzanie wieloma subskrybentami w pojedynczym żądaniu

Za pomocą poniższych metod można wykonywać dokładnie te same działania co przy zarządzaniu pojedynczymi subskrybentami, ale w żądaniu można przesłać do 100 subskrybentów naraz.

Dodawanie wielu subskrybentów

Metoda dodaje wielu subskrybentów jeśli nie było ich w liście subskrypcyjnej lub aktualizuje ich status i dane jeśli nie był w statusie „Aktywny” oraz „Do aktywacji”. W przypadku dodania tylko części z adresów (np. jeden z adresów jest niepoprawny) zostaje zwrócony kod 200 oraz dane dotyczące błędnego/błędnych adresów.

W przypadku nie dodania żadnego subskrybenta zostanie zwrócony błąd 422.

Wywołanie:

POST /rest/subscriber/addMultiple

 

Dane w POST:

subscribers Wymagane Tablica z adresami email i polami dodatkowymi w postaci

{"email" : "adres_email",

"custom_fields":

{ "tag personalizacji pola 1" : "wartość",

"tag personalizacji pola 1" : "wartość" }

}

Pole ”custom_fields” nie jest obowiązkowe.

list Wymagane Hash list subskrypcyjnej
state Opcjonalne Status jaki chcemy nadać subskrybentowi, jeśli pole będzie puste zostanie nadany status „Do aktywacji”, lista dostępnych statusów w dziale „Kody Statusów Subskrybentów”
confirm Opcjonalne Czy do subskrybenta ma być wysłany email potwierdzający. Możliwe wartości to 0 oraz 1. Jeśli pole będzie puste zostanie wysłany email z potwierdzeniem. To pole jest ignorowane (email nie zostanie wysłany) jeśli nadamy subskrybentowi status inny niż „Do aktywacji”.

 

Przykładowy request:

{"list":"id_hash",
"subscribers" : [{"email":"tester1@freshmail.pl",
"custom_fields":{"imie":"Hanna",
"kod_promocyjny":"abcde"} },
{"email":"tester2@freshmail.pl",
"custom_fields":{"imie":"Anna",
"kod_promocyjny":"efgh"} },
{"email":"tester3@freshmail.pl",
"custom_fields":{"imie":"Agata",
"kod_promocyjny":"wxyz"}}]} 

Kody błędów:

1331 Nie udało się dodać/aktualizować żadnego subskrybenta
1332 Lista subskrypcyjna nie istnieje lub brak hash'a listy
1335 Próbowano nadać niepoprawny status subskrybenta
1336 Nie przekazano adresów email do dodania
1399 Za dużo subskrybentów w jednym żądaniu – limit 100

Przykład częściowych błędów, wysłany request:

{"list":"4zcnmd2ski",
"subscribers":[{"email":"poprawny@adres.email.pl"},
{"email":"niepoprawny adres email"}]}

Zwracane dane (kod odpowiedzi 200):

{"status":"OK",
"data":{
"inserted":1,
"not_inserted":1,
"errors":[{"email":"niepoprawny adres email",
"error":"Email address not correct",
"code":1301}]}}

Kody błędów zwracane dla poszczególnych subskrybentów są identyczne jak kody błędów dla metody /rest/subscriber/add

Modyfikowanie danych wielu subskrybentów

Metoda aktualizuje status i dane wielu subskrybentów

Wywołanie:

POST /rest/subscriber/editMultiple

Dane w POST:

subscribers Wymagane

Tablica z adresami email i polami dodatkowymi w postaci

{"email" : "adres_emaiil",

"custom_fields":

{ "tag personalizacji pola 1" : "wartość",

"tag personalizacji pola 1" : "wartość" }

}

Pole ”custom_fields” nie jest obiwiązkowe.

list Wymagane Hash list subskrypcyjnej
state Opcjonalne Status jaki chcemy nadać subskrybentowi, jeśli pole będzie puste aktualny status subskrybenta nie zostanie zmieniony

 

Kody błędów:

1331 Nie udało się dodać/aktualizować żadnego subskrybenta
1332 Lista subskrypcyjna nie istnieje lub brak hash'a listy
1335 Próbowano nadać niepoprawny status subskrybenta
1336 Nie przekazano adresów email do zaktualizowania
1399 Za dużo subskrybentów w jednym żądaniu – limit 100

Zwracane dane/informacje o błędach są identyczne jak w przypadku metody /rest/subscriber/addMultiple

Modyfikowanie pól dodatkowych wszystkich subskrybentów

Metoda aktualizuje wybrane pole dodatkowe i ustawia ustaloną wartość dla wszystkich subskrybentów

Wywołanie:

POST /rest/subscriber/updateFieldValue

Dane w POST:

listHash Wymagane

Hash list subskrypcyjnej

tag Wymagane

Tag pola dodatkowego (np. kod_promocyjny)

value Wymagane

Wartość jak zostanie ustawiona w danym polu dodatkowym dla wszystkich subskrybentów

url Wymagane

Adres www na który ma zostać wysłana odpowiedź po zakończeniu procesu aktualizacji

 

Zwracane dane:

  id id procesu

Kody błędów:

1381 Pole dodatkowe nie istnieje
1382 Brak hasha listy lub tag'a pola dodatkowego
1383 Niepoprawny adres url
1384 Zbyt duża liczba znaków w polu „value” - max. 255
1385 Pole „value” jest wymagane
1386 Proces aktualizacji tego pola wciąż trwa, poczekaj na jego zakończenie

Przykład odpowiedzi niepoprawnej:

{"status":"ERROR",
"errors":[{
"message":"Niepoprawny adres url",
"code":1383
}]}

Przykład odpowiedzi poprawnej (kod odpowiedzi 200):

{"status":"OK", 
"data":{
"id":5
}}

Po procesie aktualizacji zostanie wysłane żądanie na wskazany adres URL. Odpowiedz będzie żądaniem typu POST, w treści żądania znajdą się następujące dane:

  id id procesu
  updated ilość zaktualizowanych pól subskrybentów

 

Przykładowe żądanie:

{"status":"OK",
"data":{ "id":5,
"updated":150
}} 

W odpowiedzi skrypt oczekuje kody ze statusem „OK”:

{"status":"OK"} 

Jeśli powyższa odpowiedz nie będzie poprawna, skrypt ponowi kilka razy próbę komunikacji, przy większej ilości błędów nastąpi zaniechanie wysyłania kolejnych żądań.

Pobieranie danych wielu subskrybentów

W przypadku gdy request jest częściowo niepoprawny (np. część adresów email nie istnieje) lub całkowicie niepoprawny (np. żaden z adresów email nie istnieje) zostaje zwrócony kod 200 oraz dane dotyczące błędnego/błędnych adresów.W przypadku gdy request jest całkowicie niepoprawny (np. żaden z adresów email nie istnieje) zostaje zwrócony kod 422 wraz z wiadomością błędu.

Wywołanie:

POST/rest/subscriber/getMultiple

Dane w GET:

subscribers Wymagane

Tablica z adresami email użytkowników:

{ {"email":"tester1@freshmail.pl"},

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

{"email":"tester3@freshmail.pl"} }

list Wymagane Hash list subskrypcyjnej

 

Zwracane dane:

email Adres email subskrybenta
state Status subskrybenta (zgodny z opisem w dziale „Kody Statusów Subskrybentów”)
custom_fields Pola dodatkowe wraz z wartościami
errors Tablica z błędami (w przypadku gdy któryś z adresów nie istnieje)

Kody błędów:

1336 Nie przekazano adresów email do dodania
1341 Lista subskrypcyjna nie istnieje
1342 Tablica z subskrybentami jest pusta
1399 Za dużo subskrybentów w jednym żądaniu – limit 100

Kasowanie wielu subskrybentów

Metoda kasuje subskrybentów z listy subskrypcyjnej

Wywołanie:

POST /rest/subscriber/deleteMultiple

Dane w POST:

subscribers Wymagane Tablica z adresami email użytkowników:

{ {"email":"tester1@freshmail.pl"},

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

{"email":"tester3@freshmail.pl"} }

list Wymagane Hash list subskrypcyjnej

 

Kody błędów:

1351 Lista subskrypcyjna nie istnieje
1352 Żaden z subskrybentów nie istnieje/nie został skasowany
1399 Za dużo subskrybentów w jednym żądaniu – limit 100

Zwracane dane/informacje o błędach są identyczne jak w przypadku metody /rest/subscriber/addMultiple

Dodawanie subskrybentów do listy odbiorców blokowanych

Metoda dodaje adresy subskrybentów do listy odbiorców blokowanych.

Wywołanie:

POST /rest/subscriber/addBlocks

Dane w POST:

emails Wymagane Tablica z adresami email użytkowników:

{ {"email":"tester1@freshmail.pl"},

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

{"email":"tester3@freshmail.pl"} }

Zwracane dane:

stats['added'] Ilość dodanych odbiorców
stats['existing'] Ilość już istniejących odbiorców
stats['incorrect'] Ilość błędnych odbiorców
Incorrect_mails Tablica z błędnymi adresami (w przypadku gdy jakiś mail był błędny)

Kody błędów:

1301 Adresy odbiorców są niepoprawne
1336 Nie przekazano adresów odbiorców do dodania
1343 Format przekazanych danych jest niepoprawny

Kasowanie subskrybentów z listy odbiorców blokowanych

Metoda kasuje subskrybentów z listy odbiorców blokowanych. Akcja możliwa jedynie przy adresach zablokowanych własnoręcznie

Wywołanie:

POST /rest/subscriber/removeBlocks

Dane w POST:

 

emails Wymagane Tablica z adresami email użytkowników:

{ {"email":"tester1@freshmail.pl"},

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

{"email":"tester3@freshmail.pl"} }

 

Zwracane dane:

stats['removed'] Ilość skasowanych odbiorców
stats['not_existing'] Ilość nieistniejących odbiorców
stats['incorrect'] Ilość błędnych odbiorców

 

Kody błędów:

 

1336 Nie przekazano adresów odbiorców do dodania
1343 Format przekazanych danych jest niepoprawny