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
1333 Subskrybent jest na czarnej liście
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