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.

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.

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:

  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