User API - Guida all'utilizzo dei Web Service - Servizi

Questo è l'elenco dei servizi disponibili e l'URL (in cui occorre sostituire il dominio corretto) relativo al file WSDL:

Questo è l'elenco completo, in dettaglio, delle richieste e dei comandi:

LoginService

Il servizio di login mette a disposizione due richieste fondamentali. Il login ed il logout.

Link al wsdl : https://DOMAIN/ws-v2/login?wsdl

Richieste

login

La richiesta di login ha lo scopo fondamentale di fornire un token valido (della durata di base di 15 minuti), ad un utente. Il token è l'elemento sempre presente in tutte le altre richieste di tutti gli altri servizi, e serve ad autenticare ed autorizzare lo specifico utente che rappresenta.

Login successivi prima della normale scadenza del token restituiscono sempre lo stesso token e spostano la scadenza in ulteriormente in avanti nel tempo.

Parametri
username String Lo username che identifica l'utente.
domain String Il dominio di appartenenza dell'utente.
password String La password di accesso al sistema.
Risposta
String Un token valido che rappresenta l'utente in questione.
Torna su ^

logout

La richiesta di logout ha lo scopo di invalidare il token prima della sua normale scadenza. Una volta invalidato un token sarà necessario rieffettuare un login per ottenere un nuovo token valido.

Parametri
token String Il token che si vuole invalidare.
Risposta
Nessuna
Torna su ^

MailingListService

Il servizio di Mailing List mette a disposizione un'insieme di richieste per la creazione di mailing list, la condivisione delle stesse con altri utenti e la gestione del form di sottoscrizione. I termini mailing list e lista utilizzati nel presente documento si riferiscono allo stesso concetto.

Link al wsdl : https://DOMAIN/ws-v2/mailingList?wsdl

Richieste

listMailingList

Restituisce un l'elenco di tutte le liste reali e profilate a cui ha accesso l'utente. Quest'elenco comprende tutte le liste base, le liste virtuali, la lista di test e le liste di altri utenti condivise all'utente stesso.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
Risposta
MailingListWs[] L'elenco di tutte le liste a cui ha accesso l'utente
Torna su ^

showMailingList

Restituisce le informazioni di una specifica mailing list.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idMailingList long L'id univoco della mailing list di cui si stanno richiedendo le informazioni.
Risposta
EnhancedMailingListWs L'oggetto che rappresenta la mailing list.
Torna su ^

createMailingList

Crea una nuova mailing list. In fase di creazione, come si verrà di seguito, è possibile definire in anticipo la struttura del form di sottoscrizione per la lista in questione.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
name String Il nome della lista che si vuole creare.
comment String Opzionale. Un breve commento, nota mnemonica sulla lista.
firstnameFlag String Opzionale. Una stringa di un carattere che indica come l'applicazione si deve comportare nella definizione del form di sottoscrizione in relazione al campo firstname (nome). I valori possibili sono:
  • H(idden) il campo nome non viene mostrato
  • R(equired) il campo nome è obbligatorio
  • O(ptional) il campo nome è opzionale
Se omesso si assumerà il valore di default pari a O(ptional)
lastnameFlag String Opzionale. Una stringa di un carattere che indica come l'applicazione si deve comportare nella definizione del form di sottoscrizione in relazione al campo lastname (cognome). I valori possibili sono:
  • H(idden) il campo cognome non viene mostrato
  • R(equired) il campo cognome è obbligatorio
  • O(ptional) il campo cognome è opzionale
Se omesso si assumerà il valore di default pari a O(ptional)
contentChoiceFlag String Opzionale. Una stringa di due caratteri che indica come l'applicazione si deve comportare nella definizione del form di sottoscrizione in relazione al campo contentChoice (scelta del contenuto).
Il primo carattere rappresenta la visibilità (Hidden, Visible) di tale campo.
Il secondo carattere rappresenta il valore di default (Multipart,Plaintext).
La combinazione di questi due caratteri porta ai seguenti scenari:
  • HM non selezionabile e fisso a Multipart
  • HP non selezionabile e fisso a Plaintext
  • VM selezionabile con Multipart preimpostato
  • VP selezionabile con Plaintext preimpostato
Se omesso si assumerà il valore di default pari a HM.

E' possibile definire il valore di questo campo solo se si ha attivo il modulo corrispondente.
privacyFlag String Opzionale. Una stringa di un carattere che indica come l'applicazione si deve comportare nella definizione del form di sottoscrizione in relazione al checkbox sull'accettazione della normativa sulla privacy. I valori possibili sono:
  • H(idden) l'accettazione della privacy non viene mostrata
  • R(equired) l'accettazione della privacy è obbligatoria
  • O(ptional) l'accettazione della privacy è opzionale
Se omesso si assumerà il valore di default pari a R(equired)
privacyText String Opzionale. Il testo della normativa sulla privacy da visualizzare. Se assente verrà preimpostato il testo generico definito nell'applicazione.
formFields FormFieldWs[] Un elenco di campi opzionali da inserire per ogni elemento della lista e da mostrare nel form di sottoscrizione. Nella definizione di nuovi campi del form solo i seguenti attributi dell'Oggetto FormFieldWs vengono presi in considerazione:
  • name: il nome del campo
  • type: tipo del campo. I valori possibili sono:
    • S Scelta singola (radio buttons)
    • D Scelta singola (drop-down selection)
    • M Scelta multipla (checkbox)
    • F Testo libero
  • required: il campo è obbligatorio
  • options: un elenco di FormFieldOptionsWs con le opzioni possibili per il campo in questione. Se il campo è di tipo testo libero, l'elenco delle opzioni (qualora ci fosse) viene trascurato. Degli oggetti che compongono l'elenco delle opzioni è necessario solo definire l'attributo optionText; gli altri attributi vengono trascurati.
Risposta
EnhancedMailingListWs L'oggetto che rappresenta la mailing list appena creata.
Torna su ^

updateMailingList

Modifica gli attributi di una mailing list specifica.

Così come tutti gli altri metodi del presente servizio che operano delle modifiche sulle liste anche updateMailingList non permette di modificare la lista di test e le liste di altri utenti condivise all'utente corrente.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idMailingList long L'id univoco della mailing list che si vuole modificare.
name String Opzionale. Il nuovo nome che si vuole dare alla lista in questione. Se omesso verrà mantenuto il valore attuale.
comment String Opzionale. Un breve commento, nota mnemonica sulla lista. Se omesso verrà mantenuto il valore attuale.
firstnameFlag String Opzionale. Una stringa di un carattere che indica come l'applicazione si deve comportare nella definizione del form di sottoscrizione in relazione al campo firstname (nome). I valori possibili sono:
  • H(idden) il campo nome non viene mostrato
  • R(equired) il campo nome è obbligatorio
  • O(ptional) il campo nome è opzionale
Se omesso si assumerà il valore di default pari a O(ptional)
lastnameFlag String Opzionale. Una stringa di un carattere che indica come l'applicazione si deve comportare nella definizione del form di sottoscrizione in relazione al campo lastname (nome). I valori possibili sono:
  • H(idden) il campo cognome non viene mostrato
  • R(equired) il campo cognome è obbligatorio
  • O(ptional) il campo cognome è opzionale
Se omesso si assumerà il valore attuale
contentChoiceFlag String Opzionale. Una stringa di due caratteri che indica come l'applicazione si deve comportare nella definizione del form di sottoscrizione in relazione al campo contentChoice (scelta del contenuto).
Il primo carattere rappresenta la visibilità (Hidden, Visible) di tale campo.
Il secondo carattere rappresenta il valore di default (Multipart,Plaintext).
La combinazione di questi due caratteri porta ai seguenti scenari:
  • HM non selezionabile e fisso a Multipart
  • HP non selezionabile e fisso a Plaintext
  • VM selezionabile con Multipart preimpostato
  • VP selezionabile con Plaintext preimpostato
Se omesso si assumerà il valore di default pari a HM.

E' possibile definire il valore di questo campo solo se si ha attivo il modulo corrispondente.
privacyFlag String Opzionale. Una stringa di un carattere che indica come l'applicazione si deve comportare nella definizione del form di sottoscrizione in relazione al checkbox sull'accettazione della normativa sulla privacy. I valori possibili sono:
  • H(idden) l'accettazione della privacy non viene mostrata
  • R(equired) l'accettazione della privacy è obbligatoria
  • O(ptional) l'accettazione della privacy è opzionale
Se omesso si assumerà il valore di default pari a R(equired)
privacyText String Opzionale. Il testo della normativa sulla privacy da visualizzare. Se omesso verrà mantenuto il valore definito in precedenza.
Risposta
EnhancedMailingListWs L'oggetto che rappresenta la mailing list risultante dalle modifiche apportate.
Torna su ^

deleteMailingList

Elimina una mailing list.

Così come tutti gli altri metodi del presente servizio che operano delle modifiche sulle liste anche deleteMailingList non permette di eliminare la lista di test e le liste di altri utenti condivise all'utente corrente.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idMailingList long L'id univoco della mailing list che si vuole eliminare.
Risposta
Nessuna risposta. In caso di errore viene lanciata l'eccezione opportuna.
Torna su ^

addFormField

Aggiunge un nuovo campo alla lista e al form di sottoscrizione della mailing list specificata.

Così come tutti gli altri metodi del presente servizio che operano delle modifiche sulle liste anche addFormField non permette di modificare la lista di test e le liste di altri utenti condivise all'utente corrente.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idMailingList long L'id univoco della mailing list di cui si vuole modificare il form di sottoscrizione.
fieldName String Il nome del campo che si vuole aggiungere.
fieldType String Il tipo di campo che si vuole aggiungere. I valori possibili sono:
  • S campo a scelta singola; realizzato per mezzo di radio buttons
  • D campo a scelta singola; realizzato per mezzo di tendina di selezione (drop-down selection)
  • M campo a scelta multipla; realizzato tramite checkbox
  • F campo di testo libero; realizzato da un semplice campo di testo.
Se omesso si assumerà il valore di default pari a O(ptional)
required boolean Se true indica che nel form di sottoscrizione tale campo deve essere segnalato come campo obbligatorio.
options String[] Un elenco delle opzioni possibili per il campo in questione. Se il campo si tratta di un campo di testo libero l'elenco (se fornito) non verrà preso in considerazione.
Risposta
EnhancedMailingListWs L'oggetto che rappresenta la mailing list risultante dalle modifiche apportate.
Torna su ^

updateFormField

Modifica gli attributi del campo del form di sottoscrizione di una mailing list.

Così come tutti gli altri metodi del presente servizio che operano delle modifiche sulle liste anche updateFormField non permette di modificare la lista di test e le liste di altri utenti condivise all'utente corrente.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idMailingList long L'id univoco della mailing list di cui si vuole modificare il form di sottoscrizione.
idFormField long L'id univoco del campo del form che si vuole modificare.
fieldName String Opzionale. Il nuovo nome che si vuole dare al campo. Se omesso verrà mantenuto il nome precedente.
required boolean Opzionale. L'obbligatorietà del campo all'atto della compilazione del form di sottoscrizione. Se true il campo è obbligatorio. Se omesso verrà mantenuto il valore precedentemente definito.
Risposta
EnhancedMailingListWs L'oggetto che rappresenta la mailing list risultante dalle modifiche apportate.
Torna su ^

moveFormField

Modifica l'ordine di rappresentazione dello specifico campo nel form di sottoscrizione, spostandolo verso l'alto o verso il basso rispetto agli altri.

Cosi' come tutti gli altri metodi del presente servizio che operano delle modifiche sulle liste, anche moveFormField non permette di modificare la lista di test e le liste di altri utenti condivise all'utente corrente.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idMailingList long L'id univoco della mailing list di cui si vuole modificare il form di sottoscrizione.
idFormField long L'id univoco del campo del form che si vuole modificare.
decreasePosition boolean La posizione del campo nel form di sottoscrizione è rappresentata dal valore dell'attributo sequenceNumber dell'oggetto FormFieldWs che rappresenta il campo stesso. Il valore 0 rappresenta il primo tra i campi opzionali del form(vengono prima di tutti i campi nome, cognome, email ed eventualmente scelta del contenuto), 1 il secondo e così via. Se decreasePosition è pari a true il valore assunto da sequenceNumber del campo specifico diminuisce di 1 (minimo 0) mentre il campo immediatamente prima aumenta il proprio sequenceNumber di 1. Ottenendo in questa maniera lo scambio di posizione tra il campo in esame con quello subito prima. Se decreasePosition è pari a false avviene l'esatto contrario. Se il campo è il primo della lista (sequenceNumber uguale a 0) l'operazione con decreasePosition true non ha alcun effetto. Se il campo è l'ultimo della lista (sequenceNumber uguale al numero totale dei campi meno 1) l'operazione con decreasePosition false non ha alcun effetto.
Risposta
EnhancedMailingListWs L'oggetto che rappresenta la mailing list risultante dalle modifiche apportate.
Torna su ^

deleteFormField

Elimina un campo del form.

Così come tutti gli altri metodi del presente servizio che operano delle modifiche sulle liste anche deleteFormField non permette di modificare la lista di test e le liste di altri utenti condivise all'utente corrente.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idMailingList long L'id univoco della mailing list di cui si vuole modificare il form di sottoscrizione.
idFormField long L'id univoco del campo del form che si vuole eliminare.
Risposta
EnhancedMailingListWs L'oggetto che rappresenta la mailing list risultante dalle modifiche apportate.
Torna su ^

addOptionFormField

Aggiunge un'opzione ad un campo del form di sottoscrizione alla mailing list.

Non è possibile aggiungere opzioni ad un campo del form di tipo testo libero.

Così come tutti gli altri metodi del presente servizio che operano delle modifiche sulle liste anche addOptionFormField non permette di modificare la lista di test e le liste di altri utenti condivise all'utente corrente.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idMailingList long L'id univoco della mailing list di cui si vuole modificare il form di sottoscrizione.
idFormField long L'id univoco del campo del form che si vuole eliminare.
optionText String Il testo dell'opzione che si vuole aggiungere. Se esiste già un'opzione con lo stesso testo (case-insensitive) l'operazione non ha effetto.
Risposta
FormFieldWs L'oggetto che rappresenta il campo del form oggetto della modifica.
Torna su ^

deleteOptionFormField

Elimina un'opzione specifica tra quelle definite per un particolare campo del form di sottoscrizione alla mailing list.

Così come tutti gli altri metodi del presente servizio che operano delle modifiche sulle liste anche deleteOptionFormField non permette di modificare la lista di test e le liste di altri utenti condivise all'utente corrente.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idMailingList long L'id univoco della mailing list di cui si vuole modificare il form di sottoscrizione.
idFormField long L'id univoco del campo del form che si vuole modificare.
idOption long L'id univoco dell'opzione che si vuole eliminare.
Risposta
FormFieldWs L'oggetto che rappresenta il campo del form oggetto della modifica.
Torna su ^

shareMailingList

Questa particolare richiesta ha due funzionalità specifiche:

Per poter condividere una lista con altri utenti è necessario che l'utente corrente abbia il modulo corrispondente abilitato.

È possibile condividere unicamente proprie liste base, non è perciò possibile condividere la lista di test, ne tantomeno condividere liste condivise da altri utenti.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idMailingList long L'id univoco della mailing list che si vuole condividere o di cui si intende conoscere lo stato di condivisione.
idAccount long
  • Lasciare non specificato
  • L'id univoco dell'account a con cui si vuole condividere la lista.
remove boolean
  • Lasciare non specificato
  • Se false la lista verrà condivisa con l'account specificato. Se true la lista verrà tolta dalla condivisione con tale account.
Risposta
AccountReaderWs[] L'elenco di tutti gli account e il loro specifico stato di condivisione attuale.
Torna su ^

RecipientService

Questo servizio fornisce un insieme di metodi per gestire le proprie liste di indirizzi, oltre che effettuare delle ricerche sulle stesse.

Link al wsdl : https://DOMAIN/ws-v2/recipients?wsdl

Richieste

getRecipient

Restituisce le informazioni relative ad un particolare destinatario di una lista. Vi sono due modi per recuperare le informazioni su un particolare destinatario:

I due metodi non sono esattamente identici, in quanto l'indirizzo email riferito ad un particolare destinatario può in alcuni casi mutare (es. modifica manuale dell'indirizzo da parte del proprietario della lista) cosa che invece non accade all'id univoco del destinatario. Il metodo B viene utilizzato solamente quando non viene specificato l'id del destinatario.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idRecipient long
  • Id univoco del destinatario
  • Lasciare vuoto
idMailingList long
  • Lasciare vuoto
  • Id Univoco della mailing list di appartenenza.
email String
  • Lasciare vuoto
  • Indirizzo email del destinatario
Risposta
RecipientWs Le informazioni riguardanti il destinatario cercato.
Torna su ^

addRecipient

Aggiunge un destinatario ad una lista specifica.

Si possono aggiungere destinatari soltanto alle proprie liste base ed alla lista di test.

È possibile che la richiesta sebbene ben formata restituisca dei fault. I fault più comuni sono dovuti a:

Il fatto che un campo del form di sottoscrizione sia o meno obbligatorio non si ripercuote nella obbligatorietà dei parametri di questo metodo. Essenzialmente è possibile creare un destinatario in una lista semplicemente definendo solamente il suo indirizzo email, anche se nel form di sottoscrizione sono stati definiti ulteriori campi obbligatori.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idMailingList long L'id univoco della mailing list a cui si vuole aggiungere il destinatario.
email String L'indirizzo email del destinatario. L'indirizzo email deve avere una forma valida.
firstname String Opzionale. Il nome del destinatario
lastname String Opzionale. Il cognome del destinatario
blocked Boolean Opzionale. Se il destinatario deve essere creato in stato bloccato. Se omesso il destinatario viene creato attivo.
subscribed Boolean Opzionale. Se il destinatario deve essere creato in stato subscribed (iscritto). Se omesso viene creato in stato subscribed (iscritto)
contentChoice String Opzionale. Il tipo del contenuto scelto dallo specifico destinatario. I valori possibili sono:
  • M Multipart
  • P Plaintext
Se l'utente corrente non ha il modulo corrispondente attivo, viene impostato comunque a M.
Se l'utente ha il modulo attivo e tale parametro viene omesso viene impostato il valore di default definito per la lista (vedi createMailingList e updateMailingList su MailingListService).
fields RecipientFieldWs[] La lista dei valori assunti per lo specifico destinatario dai campi opzionali definiti nel form di sottoscrizione alla mailing list.
Per ciascuno dei campi opzionali che si vuole valorizzare con una (o più nel caso di campi a scelta multipla) delle opzioni disponibili deve essere definito un RecipientFieldWs valorizzando unicamente gli attributi:
  • id: l'id univoco del campo del form
  • answers: l'elenco delle risposte per tale campo.
Le risposte sono oggetti di tipo RecipientAnswerWs. La risposta può essere individuata vari modi. Le varie modalità sono descritte qui (1) .
Risposta
RecipientWs Il destinatario appena creato.
(1) In fase di inserimento le risposte ad un campo del form devono essere segnalate nei seguenti modi: Torna su ^

addRecipientList

Aggiunge in unica richiesta un elenco di destinatari, alle rispettive liste.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
recipients RecipientWs[] L'elenco dei destinatari da aggiungere. Non tutti gli attributi degli elementi della richiesta devono essere valorizzati, in riferimento alla richiesta addRecipient i seguenti attributi sono obbligatori:
  • idMailingList
  • email
I seguenti attributi sono invece opzionali (riferirsi eventualmente alla richiesta addRecipient per conoscere i valori di default):
  • firstname
  • lastname
  • blocked
  • subscribed
  • contentChoice
  • fields
Risposta
RecipientWs[] Diversamente da quanto capita per l'aggiunta di un singolo destinatario, questa richiesta non restituisce un fault per le motivazioni esposte in riferimento alla richiesta addRecipient. Tuttavia, tali errori, vengono segnalati nella risposta, tramite l'attributo reportMessage dei singoli destinatari. In caso di eventuali errori durante l'aggiunta di uno specifico elemento della richiesta, l'elemento viene restituito nella risposta così come è stato ricevuto e con l'attributo sopra indicato valorizzato alla motivazione dell'eventuale errore. Se l'inserimento del singolo destinatario va a buon fine l'elemento corrispondete restituito ha tale attributo non valorizzato.
Torna su ^

updateRecipient

Modifica un destinatario. Vi sono due modi per identificare un destinatario, in ordine di precedenza tali modi sono:

I due metodi non sono esattamente identici, in quanto l'indirizzo email riferito ad un particolare destinatario può in alcuni casi mutare (es. modifica manuale dell'indirizzo da parte del proprietario della lista) cosa che invece non accade all'id univoco del destinatario. Il metodo B viene utilizzato solamente quando non viene specificato l'id del destinatario. Il metodo B come appare ovvio, non da modo inoltre di poter modificare l'indirizzo email.

Si possono modificare solamente i destinatari presenti nelle proprie liste base ed in quella di test.

È possibile che la richiesta sebbene ben formata restituisca dei fault. I fault più comuni sono dovuti a:

Il fatto che un campo del form di sottoscrizione sia o meno obbligatorio non si ripercuote nella obbligatorietà dei parametri di questo metodo. Essenzialmente è possibile creare un destinatario in una lista semplicemente definendo solamente il suo indirizzo email, anche se nel form di sottoscrizione sono stati definiti ulteriori campi obbligatori.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idRecipient long
  • L'id univoco del destinatario che si vuole modificare.
  • Lasciare vuoto.
idMailingList long
  • Non necessario.
  • L'id univoca della lista del destinatario che di vuole modificare.
email String
  • Opzionale. Il nuovo indirizzo email del destinatario.
  • L'email del destinatario che si vuole modificare.
firstname String Opzionale. Il nome del destinatario, se omesso non viene cambiato.
lastname String Opzionale. Il cognome del destinatario, se omesso non viene cambiato.
blocked Boolean Opzionale. Se l'utente è bloccato o meno. Se omesso tale valore rimarrà invariato.
subscribed Boolean Opzionale. Se il destinatario è in stato subscribed (iscritto) o meno. Se omesso tale valore rimarrà invariato.
contentChoice String Opzionale. Il tipo del contenuto scelto dallo specifico destinatario. I valori possibili sono:
  • M Multipart
  • P Plaintext
Se l'utente corrente non ha il modulo corrispondente attivo, viene impostato comunque a M.
Se l'utente ha il modulo attivo ed il parametro viene omesso, il valore precedente rimarrà invariato
fields RecipientFieldWs[] La lista dei valori assunti per lo specifico destinatario dai campi opzionali definiti nel form di sottoscrizione alla mailing list. Per ciascuno dei campi opzionali che si intende modificare, è necessario che esso sia segnalato nell'elenco. Se non si vuole alcuna risposta per tale campo sarà sufficiente fornire un elenco di risposte vuoto. Per come identificare le risposte riferirsi qui (1) .
Risposta
RecipientWs Il destinatario modificato.
Torna su ^

updateRecipientList

Modifica in unica richiesta un elenco di destinatari.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
recipients RecipientWs[] L'elenco dei destinatari da modificare. Non tutti gli attributi degli elementi della richiesta devono essere valorizzati, riferirsi alla richiesta updateRecipient per sapere quali attributi (e come) valorizzarli. Gli attributi definiti negli elementi di questo elenco vengono in sintesi trasposti nei parametri di singole richieste updateRecipient
Risposta
RecipientWs[] Analogamente alla richiesta addRecipientList gli elementi della risposta presentano l'attributo reportMessage valorizzato qualora la modifica del destinatario definito da quello specifico elemento abbia generato un errore.
Torna su ^

removeRecipient

Elimina un destinatario. Esistono due modi per identificare un destinatario:

I due metodi non sono esattamente identici, in quanto l'indirizzo email riferito ad un particolare destinatario può in alcuni casi mutare (es. modifica manuale dell'indirizzo da parte del proprietario della lista) cosa che invece non accade all'id univoco del destinatario. Il metodo B viene utilizzato solamente quando non viene specificato l'id del destinatario.

Si possono eliminare solamente i destinatari presenti nelle proprie liste base ed in quella di test.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idRecipient long
  • L'id univoco del destinatario che si vuole eliminare.
  • Lasciare vuoto.
idMailingList long
  • Non necessario.
  • L'id univoco della lista del destinatario che si vuole eliminare.
Risposta
boolean true se l'eliminazione è andata a buon fine.
Torna su ^

removeRecipientList

Elimina in un'unica richiesta un elenco di destinatari.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
recipients RecipientWs[] L'elenco dei destinatari da eliminare. È necessario valorizzare unicamente gli attributi necessari per identificare i rispettivi destinatari, utilizzando una delle seguenti modalità:
  • id (id univoco del destinatario).
  • idMailingList (id univoco della lista) e email (indirizzo email del destinatario).
Risposta
String[] Per ognuno degli elementi della richiesta viene restituito un valore nullo qualora l'eliminazione sia andata a buon fine, altrimenti viene restituito il corrispondente messaggio di errore.
Torna su ^

getSearchFields

Restituisce l'elenco dei campi associati ad una lista, su cui è possibile effettuare una ricerca tramite la richiesta searchRecipients. In genere tali campi sono

È possibile effettuare ricerche su tutte le liste elencate dalla richiesta listMailingList del servizio MailingListService.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idMailingList Long L'id univoco della lista di cui si vogliono conoscere i campi su cui è possibile effettuare ricerche.
Risposta
SearchFieldWs[] L'elenco dei campi su cui è possibile fare delle ricerche per la lista definita.
Torna su ^

searchRecipients

Restituisce l'elenco dei destinatari appartenenti alla lista specificata, che rispettano i criteri di ricerca definiti. I criteri di ricerca sono:

È possibile effettuare ricerche su tutte le liste elencate dalla richiesta listMailingList del servizio MailingListService.

Nella risposta saranno presenti al più 250 destinatari. Il numero totale dei destinatari che rispecchiano i criteri di ricerca, è riportato nella risposta. È possibile oltre che definire i criteri di ricerca, selezionare una particolare pagina (blocco di 250 risultati), se la ricerca producesse più di 250 destinatari.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idMailingList Long L'id univoco della lista su cui si vuole effettuare la ricerca.
searchField SearchFieldWs Il campo su cui effettuare la ricerca: vedere il risultato della richiesta getSearchFields per veder quali campi sono disponibili.
searchString String Stringa da cercare per il campo in questione. Se non si specifica alcuna stringa questo equivale a non definire alcun vincolo per il campo in questione.
blockFilter String[] Opzionale. Un filtro sullo stato di blocco dei destinatari. Nel risultato compariranno solo coloro il cui stato di blocco è tra quelli elencati nel filtro. Il non specificare alcun filtro sul blocco equivale al non voler filtrare i risultati in base a tale valore. I valori possibili del filtro sono:
  • A destinatari attivi (non bloccati)
  • BG destinatari bloccati manualmente (compresi quelli in black list)
  • BB destinatari bloccati dal bouncing
  • BA destinatari bloccati in attesa della conferma di sottoscrizione.
subscribedFilter String[] Opzionale. Un filtro sullo stato di sottoscrizione dei destinatari. Nel risultato compariranno solo coloro il cui stato di iscrizione è tra quelli elencati nel filtro. Il non specificare alcun filtro sullo stato di iscrizione equivale al non voler filtrare i risultati in base a tale valore. I valori possibili del filtro sono:
  • true destinatari iscritti
  • false destinatari che hanno chiesto la deiscrizione ma non hanno ancora confermato tale scelta (compresi quelli deiscritti manualmente dall’utente possessore della lista).
contentFilter String[] Opzionale. Un filtro sulla tipo di contenuto scelto dal destinatario. Tale filtro viene preso in considerazione solo se l'utente ha il modulo corrispondente attivo. Il non specificare alcun filtro sul tipo di contenuto equivale al non voler filtrare i risultati in base a tale valore. I valori possibili del filtro sono:
  • M destinatari che hanno scelto di ricevere mail multipart
  • P destinatari che hanno scelto di ricevere email solo testo.
page int Opzionale. Il numero della pagina (o blocco) di risultati. Se non venisse specificato, qualora la ricerca producesse più di 250 risultati solamente i primi 250 comparirebbe nella risposta (page = 0).
Risposta
SearchResultWs Il risultato della ricerca comprensivo di:
  • Numero totale dei destinatari che rispettano i criteri di ricerca.
  • Pagina corrente
  • Numero dei risultati per pagina
  • Elenco dei destinatari (massimo 250)
    • Qualora un destinatario rispecchiasse i criteri di ricerca ma il suo indirizzo email fosse presente nella black list, verrebbe comunque restituito un elemento per tale destinatario ma con dati oscurati.
Torna su ^

NewsletterService

Questo servizio mette a disposizione un'ampia gamma di richieste, per fornire all'utente finale tutti gli strumenti fondamentali per gestire le proprie newsletter. Vi sono dunque richieste per creare e modificare le newsletter nelle bozze, richieste per ottenere la lista delle proprie newsletter inviate, in coda e in uscita, e richieste per gestire la coda messaggi. Una generica newsletter del mailing-tool è un abbinamento tra layout (struttura formale) e contenuti. Un layout è composto da uno o più campi che possono essere di testo o immagine. A ciascuno di questi campi può essere associato del contenuto oppure essere lasciato vuoto. Ciascuno di questi contenuti unitamente ai campi a cui sono associati, va a collocarsi in una specifica posizione nel corpo della mail, in funzione alla struttura del particolare layout. Questa guida da per assunto che l'utente conosca a livello applicativo la forma che il layout prescelto imprime nella newsletter. Questo assunto è necessario in quanto le richieste qui esposte non sono in grado fornire una descrizione formale e rigorosa dell'"aspetto" dei layout.

Ad esempio il layout con id = -200 viene utilizzato nel caso in cui viene eseguito l’upload di un file zip che contiene la newsletter da spedire. Questo layout contiene un solo campo, quello con id = 3601, destinato a contenere tutta la newsletter.

Link al wsdl : https://DOMAIN/ws-v2/newsletter?wsdl

Richieste

listLayouts

Restituisce un elenco dei layout messi a disposizione dal sistema all'utente per la creazione delle proprie newsletter.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
Risposta
LayoutWs[] L'elenco dei layout messi a disposizione dal sistema all'utente corrente.

listDrafts

Restituisce un elenco delle newsletter presenti nelle bozze dell'utente.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
Risposta
NewsletterWs[] Elenco di newsletter presenti nelle bozze e quindi non ancora spedite.
Torna su ^

listOutbox

Restituisce un elenco delle newsletter in uscita, la cui spedizione non è ancora partita o la cui spedizione è in corso.

Se l'utente ha la coda di invio (le sue spedizioni devono essere approvate da un amministratore) nella risposta compariranno anche le newsletter ancora in attesa di approvazione.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
Risposta
NewsletterWs[] Elenco delle newsletter in uscita.
Torna su ^

listSent

Restituisce un elenco di newsletter la cui spedizione è stata ultimata.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
Risposta
NewsletterWs[] Elenco delle newsletter spedite.
Torna su ^

listQueue

Questa richiesta funziona in maniera diversa in base al tipo di utente:

Utenti Amministratori: Restituisce l'elenco delle newsletter (appartenenti anche ad altri utenti) in attesa di approvazione.

Utenti non Amministratori ma con la coda di invio attiva: Restituisce l'elenco delle proprie newsletter in uscita ed in attesa di approvazione.

Utenti non Amministratori ma con la coda di invio NON attiva: Restituisce un Fault

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
Risposta
NewsletterWs[] Elenco delle newsletter in attesa di approvazione.
Torna su ^

getNewsletter

Restituisce le informazioni riguardanti una singola newsletter.

È possibile visualizzare unicamente le informazioni delle proprie newsletter, tuttavia gli amministratori possono visualizzare le informazioni riguardanti le newsletter non proprie ma che siano in attesa di approvazione.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idNewsletter long Id univoco della newsletter di cui si vogliono ricevere i dettagli.
Risposta
NewsletterWs La newsletter ricercata
Torna su ^

createNewsletter

Crea una nuova newsletter vuota.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
title String Il titolo della newsletter, che non necessariamente corrisponderà all'oggetto della newsletter quando verrà inviata. Il titolo non deve essere vuoto
idLayout long L'id univoco del layout che si vuole utilizzare.
Risposta
NewsletterWs Oggetto che contiene le informazioni riguardanti la newsletter appena creata.
Torna su ^

deleteDraft

Elimina una newsletter non ancora inviata.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idNewsletter long Id univoco della newsletter da eliminare
Risposta
boolean true se l'eliminazione è stata eseguita con successo; una apposita eccezione se si verifica qualche problema durante il tentativo di eliminazione..
Torna su ^

updateTextField

Aggiorna e/o inserisce il contenuto di un singolo campo testuale di una propria newsletter non ancora inviata.

Gli id dei campi (idField) di una newsletter, così come il tipo, si possono recuperare dagli oggetti NewsletterWs, restituiti ad esempi da createNewsletter e getNewsletter tali oggetti presentano infatti, sotto l'attributo fields, l'elenco di tutti i campi della newsletter, siano essi con del contenuto o meno.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idNewsletter long Id univoco della newsletter di cui si vuole aggiornare il contenuto.
field NewsletterFieldWs Il nuovo contenuto per il campo in questione. Nello specifico è obbligatorio specificare i seguenti attributi:
  • idField: id del campo di cui si vuole aggiornare il contenuto
  • textualContent: il nuovo contenuto del campo. Se si vuole cancellare il vecchio contenuto senza sostituirlo con del nuovo utilizzare la richiesta clearTextField.
Risposta
NewsletterWs La newsletter modificata.
Torna su ^

clearTextField

Elimina il contenuto di un specifico campo testuale appartenente ad una propria newsletter non ancora inviata.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idNewsletter long Id univoco della newsletter di cui si vuole aggiornare il contenuto.
field NewsletterFieldWs Il campo di cui si vuole eliminare il contenuto. Nello specifico è obbligatorio specificare unicamente l'attributo idField.
Risposta
NewsletterWs La newsletter modificata.
Torna su ^

updateImageField

Aggiorna e/o inserisce il contenuto di un singolo campo immagine di una propria newsletter non ancora inviata .

Gli id dei campi (idField) di una newsletter, così come il tipo, si possono recuperare dagli oggetti NewsletterWs, restituiti ad esempi da createNewsletter e getNewsletter; tali oggetti presentano infatti, sotto l'attributo fields, l'elenco di tutti i campi della newsletter, siano essi con del contenuto o meno.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idNewsletter long Id univoco della newsletter di cui si vuole aggiornare il contenuto.
field NewsletterFieldWs Il nuovo contenuto per il campo in questione. Nello specifico è obbligatorio specificare i seguenti attributi:
  • idField: id del campo di cui si vuole aggiornare il contenuto

I seguenti attributi sono opzionali:

  • imageLink: il link a cui si rimanda se si seleziona l'immagine. Default nessuno
  • imageAlt: il testo alternativo dell'immagine. Viene visualizzato se l'utente finale ha le immagini disabilitate. Default nessuno.
    • Gli altri attributi non sono necessari.
imageFile FileWs Il file (binario) con l'immagine che si vuole caricare.
Risposta
NewsletterWs La newsletter modificata.
Torna su ^

clearImageField

Elimina il contenuto di un specifico campo immagine appartenente ad una propria newsletter non ancora inviata.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idNewsletter long Id univoco della newsletter di cui si vuole aggiornare il contenuto.
field NewsletterFieldWs Il campo di cui si vuole eliminare il contenuto. Nello specifico è obbligatorio specificare unicamente l'attributo idField.
Risposta
NewsletterWs La newsletter modificata.
Torna su ^

uploadHtml

Con questa richiesta è possibile aggiornare il contenuto di un campo testuale (HTML), in funzione del contenuto dell'archivio archivio Zip mandato come parametro della richiesta. Si rimanda alla documentazione dell'applicazione per sapere come deve essere formato il contenuto dell'archivio Zip.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idNewsletter long Id univoco della newsletter di cui si vuole aggiornare il contenuto.
field NewsletterFieldWs Il campo di cui si vuole aggiornare il contenuto. Nello specifico è obbligatorio specificare unicamente l'attributo idField.
zipFile FileWs Il file (binario) che rappresenta l'archivio Zip contente i file necessari a costruire il contenuto per il campo specificato.
Risposta
NewsletterWs La newsletter modificata.
Torna su ^

listSenders

Restituisce la propria lista degli indirizzi da utilizzare come mittente per la spedizione delle proprie newsletter.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
Risposta
SenderWs[] L'elenco dei mittenti validi dell'utente specifico.
Torna su ^

sendTest

Effettua l'invio di test di una bozza. Un invio di test viene effettuato con questi parametri:

Lista utilizzata: Lista di test dell'account specifico

Indirizzo mittente: L'indirizzo base dell'account (quello definito alla creazione dell'account).

Oggetto della newsletter: equivalente al titolo della newsletter come specificato in fase di creazione.

Data di invio: immediato.

Un invio di test non modifca il numero dei crediti residui perchè non consuma ricariche.

La newsletter rimane nelle bozze e non viene spostata tra le newsletter inviate (ne tra quelle in uscita).

Non vengono registrate le statistiche dell'invio. Link quali quelli di deiscrizione e sottoscrizione sono disabilitati.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idNewsletter long L'id univoco della bozza di cui si vuole effettuare un invio di test.
Risposta
NewsletterWs[] Le informazioni relative alla newsletter specifica.
Torna su ^

send

Invia una newsletter.

Una newsletter che viene inviata viene spostata immediatamente tra le newsletter in uscita; solo dopo che il sistema ha completato l'operazione di invio essa viene spostata tra le newsletter inviate (status uguale a 'S'). Se gli invii dell'utente devono essere approvati da un amministratore, la newsletter comparirà anche nella coda di approvazione. Il sistema invierà inoltre una notifica (email) dell'operazione a tutti gli amministratori dell'utente.

La richiesta potrebbe comunque restituire dei Fault se il numero dei crediti necessari per l'invio della newsletter supera il numero dei crediti disponibili all'utente corrente.

Se gli invii dell'utente devono essere autorizzati da un amministratore, il controllo sui crediti viene effettuato solo quando l'amministratore approva la spedizione e non prima.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idNewsletter long Id univoco della newsletter che si vuole inviare
from SenderWs Opzionale. Uno dei mittenti validi che si vuole utilizzare per l'invio. Se non specificato viene utilizzato quello base (definito in fase di creazione dell' account corrente).
subject String Opzionale. Oggetto della newsletter. Se omesso viene utilizzato il titolo della stessa.
idMailingList long Id univoco della lista a cui si vuole inviare la newsletter. Si può utilizzare una qualunque lista (base, test, profilata, condivisa) purchè non sia in fase di elaborazione (quelle con l'attributo type pari a L).
scheduledTime Date (xs:dateTime) Opzionale. Data e ora in cui si intende pianificare l'invio. Se omesso l'invio sarà immediato. N.B. Un invio non può in qualunque modo essere predatato.
Risposta
NewsletterWs Le informazioni riguardanti la newsletter che si sta inviando.
Torna su ^

cancelSpedition

Annulla una spedizione in corso (status uguale a 'O') o in attesa di approvazione (status uguale a 'U').

Se l'invio effettivo non è ancora iniziato all'atto di annullare la spedizione (mailSent uguale a '0') l'intera somma dei crediti detratti per l'invio in questione verrà ripristinata. La newsletter verrà inoltre spostata nelle bozze.

Se l'invio è gia iniziato i crediti verranno ripristinati solamente in parte (in funzione di quanti invii erano stati programmati e di quelli già effettati all'atto di annullare l'invio). La newsletter viene inoltre spostata tra quelle inviate..

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idNewsletter long Id univoco della newsletter in uscita di cui si vuole annullare la spedizione.
Risposta
boolean true se l'operazione è andata a buon fine; se si verifica qualche problema durante la spedizione viene lanciata l’eccezione opportuna.
Torna su ^

confirmSpedition

Conferma la spedizione di una newsletter inattesa di approvazione (status uguale a 'U').

Solamente gli amministratori possono utilizzare questa richiesta.

L'approvazione della newsletter da il via libera al sistema per eseguire la spedizione. Si può tuttavia incorrere nei Fault definiti come per la richiesta send e derivati da un numero insufficiente di crediti dell'utente proprietario della newsletter.

Il sistema notifica inoltre l'utente che ha richiesta l'approvazione dell'esito di questa operazione.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idNewsletter long Id univoco della newsletter in stato di approvazione di cui si vuole autorizzare l'invio.
Risposta
NewsletterWs Le informazioni riguardanti la newsletter appena approvata.
Torna su ^

rejectSpedition

Non autorizza l'invio di una newsletter in attesa di approvazione (status uguale a 'U').

Solamente gli amministratori possono utilizzare questa richiesta.

Una newsletter non approvata viene spostata nuovamente tra le bozze.

Il sistema inoltre notifica l'utente che ha richiesto l'invio, dell'esito di questa operazione. Tale notifica contiene pure la motivazione fornita dall'amministratore.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idNewsletter long Id univoco della newsletter in attesa di approvazione di cui non si vuole autorizzare l'invio.
reason String La motivazione di tale scelta.
Risposta
NewsletterWs Le informazioni riguardanti la newsletter appena respinta.
Torna su ^

listHeaderFooter

Restituisce l’elenco degli Header e Footer disponibili.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
Risposta
HeadersAndFootersWs[] L’elenco degli Header e Footer disponibili.
Torna su ^

setHeadersAndFooters

Consente di assegnare ad una newsletter un Header e Footer.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idNewsletter long Id univoco della newsletter di cui si vuole impostare l’header e il footer.
idHeaderAndFooter long Id univoco dell’header e footer da assegnare alla newsletter.
Risposta
boolean true se l'operazione è andata a buon fine, false altrimenti.
Torna su ^

StatisticService

Il servizio StatisticService mette a disposizione unicamente due richieste per poter recuperare le statistiche di un invio.

Link al wsdl : https://DOMAIN/ws-v2/statistic?wsdl

Richieste

getNewsletterStatistics

Restituisce le statistiche generali di un invio.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idNewsletter long Id univoco di una newsletter inviata di cui si vogliono recuperare le statistiche.
Risposta
NewsletterStatisticsWs Le statistiche generali della newsletter.
Torna su ^

requestDetailedStatistics

Permette di ricevere una notifica (email) contenente, in allegato, le statistiche dettagliate di un invio.

L'utente deve avere il modulo corrispondente abilitato per poter utilizzare questa richiesta.

Parametri
token String Un token valido, che autorizza ed autentica l’utente corrente.
idNewsletter long Id univoco di una newsletter inviata di cui si vogliono recuperare le statistiche.
email String Indirizzo email a cui inviare le statistiche dettagliate dell’invio.
Risposta
boolean true se la richiesta è stata messa in coda, in attesa di essere processata. false altrimenti.
Torna su ^