manuale api - infomail
DESCRIPTION
Le API sono state create per dare ai clienti di Infomail l’accesso diretto al livello di programmazione e alle funzioni chiave della creazione e della spedizione delle email ad un grosso set di dati. Virtualmente, qualsiasi cosa che può essere fatta nell’applicazione di Infomail può anche essere programmata attraverso l’uso delle API. Il più comune utilizzo delle API è quello di sincronizzare e centralizzare i dati dei clienti contenuti in un sistema CRM e altri database. Le API permettono di saltare la fase del caricamento manuale di qualsiasi file di dati inclusi quelli di Excel e CSV.TRANSCRIPT
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 1 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
MANUALE DI UTILIZZO DEI WEB SERVICE UTENTE
PIATTAFORMA INFOMAIL
Data ultimo aggiornamento: 08/10/2008
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 2 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
Scopo del documento
Il presente documento ha lo scopo di illustrare le funzionalità esposte attraverso i web services,
dall’applicazione Infomail. Non tutte le funzionalità accessibili attraverso l’utilizzo dell’interfaccia
web sono rese disponibili come web service.
Un utente deve essere esplicitamente abilitato per poter usufruire dei metodi di seguito documentati.
Una volta che l'utente viene esplicitamente abilitato dall'amministratore all'utilizzo dei Web
Services può utilizzare le proprie credenziali per autenticarsi ed ottenere l'autorizzazione all'utilizzo
degli stessi, tramite il servizio di login (LoginService).
Per autenticarsi occorre fornire oltre il nome utente e la password anche il dominio. Il nome utente e
password sono le stesse che si utilizzano per accedere attraverso l’interfaccia web. Il dominio è
quello a cui ci si collega per utilizzare l’applicazione web.
Si può fruire dei web services di seguito descritti attraverso lo sviluppo di un client nel linguaggio
che si preferisce che comunichi con i web services attraverso il protocollo SOAP 2.0 over http.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 3 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
Guida alle API
La guida fornisce la descrizione di:
• servizi
Le pagine della guida riguardanti i servizi elencano le richieste che il servizio gestisce. Le
richieste prendono dei parametri di input e restituiscono una risposta. Sia i parametri di input
che la risposta possono essere o dati semplici (per esempio un int) od oggetti (data objects)
come MapElement.
• data objects(oggetti)
Le pagine della guida riguardanti gli oggetti elencano i campi presenti e che cosa
rappresentano.
Il modo in cui vengono costruiti la richiesta e i parametri di input, dipende dallo strumento e dal
linguaggio che si sta utilizzando, o dal fatto che si sta sviluppando direttamente in XML.
Per applicare ciò che viene descritto nella guida occorrerà mappare gli oggetti ed i campi per
adattarli alla particolare situazione in esame.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 4 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
Guida ai Servizi
Di seguito vengono riportati l’elenco dei servizi disponibili e l’URL (in cui occorre sostituire il
dominio corretto) relativo al file WSDL.
• LoginService (http://dominio/ws/login?wsdl)
• MailingListService (http://dominio/ws/mailingList?wsdl)
• RecipientService (http://dominio/ws/recipients?wsdl)
• NewsletterService (http://dominio/ws/newsletter?wsdl)
• StatisticService (http://dominio/ws/statistic?wsdl)
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 5 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
Indice
Scopo del documento .................................................................................................................. 2 Guida alle API ............................................................................................................................ 3 Guida ai Servizi........................................................................................................................... 4 Indice .......................................................................................................................................... 5 LoginService ............................................................................................................................... 7
login ........................................................................................................................................ 7 logout ...................................................................................................................................... 7
MailingListService ...................................................................................................................... 9 listMailingList ......................................................................................................................... 9 showMailingList ................................................................................................................... 10 createMailingList .................................................................................................................. 10 updateMailingList ................................................................................................................. 13 deleteMailingList .................................................................................................................. 15 addFormField ........................................................................................................................ 15 updateFormField ................................................................................................................... 16 moveFormField ..................................................................................................................... 17 deleteFormField .................................................................................................................... 18 addOptionFormField ............................................................................................................. 19 deleteOptionFormField .......................................................................................................... 19 shareMailingList ................................................................................................................... 20
RecipientService ....................................................................................................................... 22 getRecipient .......................................................................................................................... 22 addRecipient ......................................................................................................................... 23 addRecipientList ................................................................................................................... 25 updateRecipient ..................................................................................................................... 26 updateRecipientList ............................................................................................................... 28 removeRecipient ................................................................................................................... 29 removeRecipientList ............................................................................................................. 30 getSearchFields ..................................................................................................................... 30 searchRecipients .................................................................................................................... 31
NewsletterService ..................................................................................................................... 34 listLayouts ............................................................................................................................. 35 listDrafts ............................................................................................................................... 35 listOutbox ............................................................................................................................. 36 listSent .................................................................................................................................. 36 listQueue ............................................................................................................................... 37 getNewsletter ........................................................................................................................ 37 createNewsletter .................................................................................................................... 38 deleteDraft ............................................................................................................................ 38 updateTextField .................................................................................................................... 39 clearTextField ....................................................................................................................... 39 updateImageField .................................................................................................................. 40 clearImageField ..................................................................................................................... 41 uploadHtml ........................................................................................................................... 41 listSenders ............................................................................................................................. 42 sendTest ................................................................................................................................ 42 send ....................................................................................................................................... 43 cancelSpedition ..................................................................................................................... 45 confirmSpedition ................................................................................................................... 45
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 6 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
rejectSpedition ...................................................................................................................... 46 listHeaderFooter .................................................................................................................... 47 setHeadersAndFooters ........................................................................................................... 47
StatisticService .......................................................................................................................... 48 getNewsletterStatistics .......................................................................................................... 48 requestDetailedStatistics ........................................................................................................ 48
Guida agli oggetti ...................................................................................................................... 50 MailingListWs ...................................................................................................................... 51 EnhancedMailingListWs ....................................................................................................... 52 FormFieldWs ........................................................................................................................ 54 FormFieldOptionsWs ............................................................................................................ 55 AccountReaderWs ................................................................................................................. 55 RecipientWs .......................................................................................................................... 56 RecipientFieldWs .................................................................................................................. 57 RecipientAnswerWs .............................................................................................................. 58 SearchFieldWs ...................................................................................................................... 58 SearchResultWs .................................................................................................................... 59 HeadersAndFootersWs .......................................................................................................... 60 FileWs ................................................................................................................................... 61 LayoutWs .............................................................................................................................. 61 NewsletterWs ........................................................................................................................ 62 NewsletterFieldWs ................................................................................................................ 64 SenderWs .............................................................................................................................. 65 NewsletterStatisticsWs .......................................................................................................... 66 LinkStatisticsWs ................................................................................................................... 67 PollStatisticsWs .................................................................................................................... 68 AnswerStatisticsWs ............................................................................................................... 68
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 7 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
LoginService
Il servizio di login mette a disposizione due richieste fondamentali. Il login ed il logout.
Link al wsdl
http://DOMAIN/ws/login?wsdl.
Richieste
• login
• logout
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.
password String La password di accesso al sistema.
domain String Il dominio di appartenenza dell'utente.
Risposta
String Un token valido che rappresenta l'utente in questione.
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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 8 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
Parametri
token String Il token che si vuole invalidare.
Risposta
Nessuna
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 9 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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
http://DOMAIN/ws/mailingList?wsdl
Richieste
• listMailingList
• showMailingList
• createMailingList
• updateMailingList
• deleteMailingList
• addFormField
• updateFormField
• moveFormField
• deleteFormField
• addOptionFormField
• deleteOptionFormField
• shareMailingList
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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 10 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
Risposta
MailingListWs[] L'elenco di tutte le liste a cui ha accesso l'utente
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.
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
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 11 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
• 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
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 12 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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:
o S Scelta singola (radio buttons)
o D Scelta singola (drop-down selection)
o M Scelta multipla (checkbox)
o 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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 13 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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 varrà mantenuto il valore attuale.
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 varrà mantenuto il valore attuale.
contentChoiceFlag String Opzionale. Una stringa di due caratteri che indica come
l'applicazione si deve comportare nella definizione del form
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 14 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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 varrà mantenuto il valore attuale.
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 varrà mantenuto il valore attuale.
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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 15 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
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
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 16 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
• 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.
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.
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
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 17 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
moveFormField
Modifica l'ordine di rappresentazione dello specifico campo nel form di sottoscrizione, spostandolo
verso l'alto o verso il basso rispetto agli altri.
Così 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
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 18 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 19 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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 modificare.
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.
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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 20 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
shareMailingList
Questa particolare richiesta ha due funzionalità specifiche:
A) conoscere l'attuale stato di condivisione di una particolare mailing list
B) modificare lo stato di condivisione di una particolare lista.
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 A) Lasciare non specificato
B) L'id univoco dell'account a con cui si vuole
condividere la lista.
remove boolean A) Lasciare non specificato
B) Se false la lista verrà condivisa con l'account
specificato. Se true la lista verrà tolta dalla
condivisione con tale account.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 21 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
Risposta
AccountReaderWs[] L'elenco di tutti gli account e il loro specifico stato di condivisione attuale.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 22 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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
http://DOMAIN/ws/recipients?wsdl
Richieste
• getRecipient
• addRecipient
• addRecipientList
• updateRecipient
• updateRecipientList
• removeRecipient
• removeRecipientList
• getSearchFields
• searchRecipients
getRecipient
Restituisce le informazioni relative ad un particolare destinatario di una lista. Vi sono due modi per
recuperare le informazioni su un particolare destinatario:
A) Tramite l’id univoco del destinatario
B) Tramite l'indirizzo email del destinatario e l'id univoco della lista di appartenenza.
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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 23 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
idRecipient Long A) Id univoco del destinatario
B) Lasciare vuoto
idMailingList Long A) Lasciare vuoto
B) Id Univoco della mailing list di appartenenza.
email String A) Lasciare vuoto
B) Indirizzo email del destinatario
Risposta
RecipientWs Le informazioni riguardanti il destinatario cercato.
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:
• Si sta cercando di aggiungere un destinatario il cui indirizzo email compare nella
black list.
• Si sta cercando di aggiungere un destinatario con un indirizzo email uguale ad un
altro destinatario sulla stessa lista.
• L'indirizzo email del destinatario non è valido.
• È stato superato il limite di 10 destinatari per la lista di test, (se si sta aggiungendo
destinatari alla lista di test)
• È stato superato il limite di indirizzi (definito per l'account) che si possono caricare
nelle proprie liste base (se si sta aggiungendo destinatari alle proprie liste base).
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
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 24 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 25 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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:
• Campi a scelta singola. Se sono presenti più risposte solo la prima viene presa in
considerazione, in ordine di precedenza i modi per segnalare tale risposta sono:
i. Valorizzando l'attributo idOption.
ii. Valorizzando l'attributo optionValue.
• Campi a scelta multipla. Tutte le risposte devono essere segnalate allo stesso modo.
Analogamente ai campi a scelta singola i modi per segnalare le risposte sono (in
ordine di precedenza):
i. Valorizzando l'attributo idOption.
ii. Valorizzando l'attributo optionValue.
• Campi a testo libero. Valorizzando unicamente l'attributo optionText.
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
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 26 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
updateRecipient
Modifica un destinatario. Vi sono due modi per identificare un destinatario, in ordine di precedenza
tali modi sono:
A) Tramite un id univoco del destinatario stesso
B) Tramite l'indirizzo email e l'id univoco della lista di appartenenza.
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
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 27 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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:
• Si sta cercando di modificare l'email di un destinatario con un indirizzo email
compare nella black list.
• Si sta cercando di modificare l'indirizzo email di un destinatario con l'indirizzo email
uguale ad un altro destinatario sulla stessa lista.
• Il nuovo indirizzo email del destinatario non è valido.
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 A) L'id univoco del destinatario che si vuole modificare.
B) Lasciare vuoto.
idMailingList Long A) Non necessario.
B) L'id univoca della lista del destinatario che di vuole
modificare.
email String A) Opzionale. Il nuovo indirizzo email del destinatario.
B) 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
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 28 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
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
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 29 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
removeRecipient
Elimina un destinatario. Esistono due modi per identificare un destinatario:
A) Tramite un id univoco del destinatario stesso
B) Tramite l'indirizzo email e l'id univoco della lista di appartenenza.
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 A) L'id univoco del destinatario che si vuole eliminare.
B) Lasciare vuoto.
idMailingList Long A) Non necessario.
B) L'id univoco della lista del destinatario che si vuole
eliminare.
Risposta
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 30 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
boolean true se l'eliminazione è andata a buon fine.
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.
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
• nome
• cognome
• eventuali campi del form opzionali
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 31 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
È 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.
searchRecipients
Restituisce l'elenco dei destinatari appartenenti alla lista specificata, che rispettano i criteri di
ricerca definiti. I criteri di ricerca sono:
1) Campo di ricerca (uno tra quelli restituito dalla richiesta getSearchFields) e parola da
ricercare.
2) Filtro sul tipo di blocco; uno o più tra utenti attivi (A), bloccati manualmente (BG),
bloccati dal bouncing (BB) e bloccati in attesa della conferma di sottoscrizione alla lista
specifica (BA).
3) Filtro sullo stato di sottoscrizione: uno tra utenti iscritti (true) e deiscritti (false) ma
senza la conferma di deiscrizione.
4) Filtro sul tipo di contenuto prescelto: uno tra Multipart (M) e Plaintext (P). (Solo per chi
ha il modulo corrispondente attivo).
È 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
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 32 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 33 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 34 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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
http://DOMAIN/ws/newsletter?wsdl
Richieste
• listLayouts
• listDrafts
• listOutbox
• listSent
• listQueue
• getNewsletter
• createNewsletter
• deleteDraft
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 35 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
• updateTextField
• clearTextField
• updateImageField
• clearImageField
• uploadHtml
• listSenders
• sendTest
• send
• cancelSpedition
• confirmSpedition
• rejectSpedition
• listHeaderFooter
• setHeadersAndFooters
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
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 36 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
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.
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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 37 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
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
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 38 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
NewsletterWs La newsletter ricercata
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.
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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 39 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
clearTextField
Elimina il contenuto di un specifico campo testuale appartenente ad una propria newsletter non
ancora inviata.
Parametri
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 40 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
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:
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 41 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
• 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.
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.
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
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 42 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
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.
sendTest
Effettua l'invio di test di una bozza.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 43 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
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').
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 44 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 45 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 46 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 47 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 48 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
StatisticService
Il servizio StatisticService mette a disposizione unicamente due richieste per poter recuperare le
statistiche di un invio.
Link al wsdl
https://DOMAIN/ws/statistic?wsdl
Richieste
• getNewsletterStatistics
• requestDetailedStatistics
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.
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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 49 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
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.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 50 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
Guida agli oggetti
• MailingListWs
• EnhancedMailingListWs
• FormFieldWs
• FormFieldOptionsWs
• AccountReaderWs
• RecipientWs
• RecipientFieldWs
• RecipientAnswerWs
• SearchFieldWs
• SearchResultWs
• HeaderAndFootersWs
• FileWs
• LayoutWs
• NewsletterWs
• NewsletterFieldWs
• SenderWs
• NewsletterStatisticsWs
• LinkStatisticsWs
• PollStatisticsWs
• AnswerStatisticsWs
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 51 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
MailingListWs
Un oggetto di questo tipo vuole rappresentare l'insieme delle informazioni base di una generica
mailing list, priva quindi degli eventuali dati riguardanti il form di sottoscrizione.
Campi
• id
• name
• comment
• type
• ownerType
• emailNumber
Campo Tipo Descrizione
id long Id univoco della mailing list
name String Nome della mailing list
comment String Commento/nota sulla mailing list
type String Tipo della lista. I valori possibili sono:
• T lista di test
• R lista base
• L in fase di caricamento
• S lista condivisa
• V lista virtuale
ownerType String Tipo della lista originale. Questo
campo assume generalmente lo stesso
valore del campo type tranne nel caso
in cui la lista non sia una lista condivisa
(S), nel qual caso il campo rappresenta
il tipo originale (tra le liste del
proprietario).
emailNumber int Il numero di indirizzi validi presenti
nella lista. Questo numero include
anche gli indirizzi bloccati e quelli
deiscritti senza conferma.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 52 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
EnhancedMailingListWs
Un oggetto di questo tipo completa le informazioni contenute in oggetto di tipo MailingListWs con
ulteriori informazioni riguardanti il form di sottoscrizione. Queste informazioni sono disponibili
solamente per quanto riguarda le liste di tipo R.
Campi
• id
• name
• comment
• type
• ownerType
• emailNumber
• firstnameFlag
• lastnameFlag
• contentChoiceFlag
• privacyFlag
• privacyText
• formFields
Campo Tipo Descrizione
id long Id univoco della mailing list
name String Nome della mailing list
commento String Commento/nota sulla mailing list
type String Tipo della lista. I valori possibili sono:
• T lista di test
• R lista base
• L in fase di caricamento
• S lista condivisa
• V lista virtuale
ownerType String Tipo della lista originale. Questo
campo assume generalmente lo stesso
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 53 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
valore del campo type tranne nel caso
in cui la lista non sia una lista condivisa
(S), nel qual caso il campo rappresenta
il tipo originale (tra le liste del
proprietario).
emailNumber int Il numero di indirizzi validi presenti
nella lista. Questo numero include
anche gli indirizzi bloccati e quelli
deiscritti senza conferma.
firstnameFlag String Un carattere indicante il
comportamento del campo nome nel
form di sottoscrizione:
• H nascosto
• O opzionale
• R obbligatorio
lastnameFlag String Un carattere indicante il
comportamento del campo cognome
nel form di sottoscrizione:
• H nascosto
• O opzionale
• R obbligatorio
contentChoiceFlag String Un carattere indicante il
comportamento del campo scelta del
contenuto nel form di sottoscrizione:
• HM non selez. Multipart
• HP non selez. Plaintext
• VM selez., default Multipart
• VP selez., default Plaintext
privacyFlag String Un carattere indicante il
comportamento del campo accettazione
della normativa sulla privacy nel form
di sottoscrizione:
• H nascosto
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 54 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
• O opzionale
• R obbligatorio
privacyText String Testo specifico della normativa sulla
privacy associato alla lista
formFields FormFieldWs[] Elenco degli eventuali campi opzionali
del form.
FormFieldWs
Un oggetto di questo tipo rappresenta un generico campo opzionale del form.
Campi
• idField
• name
• type
• required
• sequenceNumber
• options
Campo Tipo Descrizione
idField long Id univoco di uno specifico campo del
form di sottoscrizione alla mailing list.
name String Nome del campo
type String Tipo del campo del form. I valori
possibili:
• S Scelta singola (radio button)
• D Scelta singola (drop-down
selection)
• M Scelta multipla (checkbox)
• F Testo libero
required boolean Se il campo nel form deve essere
considerato obbligatorio o meno.
sequenceNumber int Rappresenta l'ordine di comparizione
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 55 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
del campo opzionale nel form,
relativamente agli altri campi opzionali.
0 indica che è il primo, 1 il secondo,
etc.
options FormFieldOptionsWs[] L'elenco delle opzioni disponibili per il
campo. Se si tratta i un campo di testo
libero l'elenco è sempre vuoto.
FormFieldOptionsWs
Un oggetto di questo tipo rappresenta una singola opzione di uno specifico campo del form (S,D o
M) di sottoscrizione alla mailing list.
Campi
• idOption
• value
• text
Campo Tipo Descrizione
idOption long Id univoco di una specifica opzione.
value int Valore numerico dell'opzione. Serve ad
indicare l'ordine di comparizione
dell'opzione stessa tra tutte quelle
disponibili per lo specifico campo del
form.
text String Testo dell'opzione.
AccountReaderWs
Un oggetto di questo tipo rappresenta unicamente un generico utente del sistema ed il suo stato di
condivisione con una specifica lista.
L'oggetto presenta unicamente le minime informazioni necessarie per identificare l'utente.
Campi
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 56 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
• id
• firstname
• lastname
• shared
Campo Tipo Descrizione
id long Elenco di accoppiamenti nome-valore
firstname String Nome dell'utente
lastname String Cognome dell'utente
shared boolean Stato di condivisione.
true la lista è condivisa con l'utente.
false la lista non è condivisa con
l'utente
RecipientWs
Un oggetto di questo tipo rappresenta un generico destinatario appartenente ad una lista base.
Campi
• id
• idMailingList
• firstname
• lastname
• contentChoice
• fields
• blocked
• blockedType
• subscribed
• reportMessage
Campo Tipo Descrizione
id long id univoco del destinatario
idMailingList long id univoco della mailing list a cui
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 57 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
appartiene il destinatario
email String indirizzo email del destinatario
firstname String nome del destinatario
lastname String cognome del destinatario
contentChoice String tipo di contenuto scelto dal destinatario
fields RecipientFieldWs[] elenco dei campi opzionali definiti per
il form di sottoscrizione, con le
eventuali risposte
blocked Boolean se è bloccato (true) o meno (false)
blockedType String il tipo di blocco
subscribed Boolean se il destinatario è iscritto (true) o
meno (false)
reportMessage String eventuale messaggio dell'errore che si è
verificato nella richiesta
addRecipientList o
updateRecipientList quando si è
tentato di processare il destinatario
rappresentato da questo oggetto
RecipientFieldWs
Un oggetto di questo tipo rappresenta il generico campo opzionale di un form di sottoscrizione
comprensivo dei valori specifici scelti dall'utente. Un oggetto di questo tipo ha sempre un
corrispondente FormFieldWs riferito alla stessa lista. L'elenco dei valori specifici che assume il
campo in questione è un sottoinsieme delle opzioni definite come FormFieldOptionsWs, semprein
riferimento allo stesso campo.
Campi
• id
• fieldName
• answers
Campo Tipo Descrizione
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 58 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
id long Id univoco di uno specifico campo del
form di sottoscrizione alla mailing list.
fieldName String Nome del campo
answers RecipientAnswerWs[] Elenco dei valori assunti da tale campo
per uno specifico utente.
Se si tratta di un campo a scelta singola
(radio button o drop-down selection) o
testo libero sarà disponibile al più un
unico elemento.
RecipientAnswerWs
Un singolo valore assunto da uno specifico campo del form per uno specifico destinatario.
Per chiarimenti su come questi oggetti sono legati con gli oggetti FormFieldOptionsWs vedere
l'esempio.
Campi
• idOption
• value
• text
Campo Tipo Descrizione
idOption long Id univoco di uno specifica opzione.
optionValue int Valore numerico dell'opzione. Analogo
al campo value di
FormFieldOptionsWs.
answer String Testo dell'opzione e quindi della
risposta per uno specifico utente.
SearchFieldWs
Un oggetto di questo tipo rappresenta possibile campo chiave su cui effettuare una ricerca per una
lista specifica. Esso può essere il campo indirizzo email dei destinatari come un generico campo
opzionale.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 59 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
Campi
• fieldName
• idField
Campo Tipo Descrizione
fieldName String Nome del campo. Esso può essere uno
tra:
• firstname
• lastname
oppure il nome di un generico campo
opzionale come ad esempio hobbies.
idField long Id univoco di uno specifico campo del
form di sottoscrizione alla mailing list.
per quanto riguarda i campi fissi
(email, firstname, lastname) il
assume un valore nullo, mentre riveste
fondamentale importanza per i campi
opzionali.
SearchResultWs
Rappresenta il risultato di una ricerca.
Campi
• recipients
• page
• maxRecipientsPerPage
• totalRecipients
Campo Tipo Descrizione
recipients RecipientWs[] Elenco dei risultati di una ricerca, fino
ad un massimo di
maxRecipientsPerPage (250)
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 60 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
elementi.
page int Numero della pagina di risultati (0
prima pagina, 1 seconda e cosi via)
maxRecipientsPerPage int Numero massimo di elementi restituiti
da una singola ricerca (250).
totalRecipients int Numero totale di destinatari che
rispecchiano i criteri di ricerca.
HeadersAndFootersWs
Un oggetto di questo tipo rappresenta un generico Header e Footer.
Campi
Campo Tipo Descrizione
idHnF long Id univoco del set Header e Footer.
description String Descrizione di questo set di H & F.
footerHtml String Codice Html relativo al footer.
footerTxt String Testo relativo al footer
footerViralHtml String Codice Html relativo al footer da
usare nel caso di viral marketing
headerHtml Codice Html relativo all’header
headerPollsHtml String Codice Html relativo all’header da
utilizzare nel caso in cui ci siano
sondaggi
headerPollsTxt String Testo relativo all’header da utilizzare
nel caso in cui ci siano sondaggi
headerTxt String Testo relativo all’header
headerViralHtml String Codice Html relativo all’header da
utilizzare nel caso di Viral marketing
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 61 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
FileWs
Questo tipo di data-object vuole rappresentare un generico file; nello specifico esso contiene
unicamente due informazioni: un nome ed il suo contenuto.
Campi
• fileName
• fileData
Campo Tipo Descrizione
fileName String Il nome del file. O in maniera più
generale il nome con cui associare lo
stream di byte specificati nell'attributo
fileData.
fileData xs:base64Binary Lo stream di byte corrispondente al
contenuto binario del file.
LayoutWs
Un oggetto che rappresenta un generico layout.
Questo oggetto non contiene le informazioni riguardanti i campi che compongono il layout stesso.
Tali informazioni sono tuttavia disponibili all'interno degli oggetti NewsletterWs (ad esclusione di
quelli restituiti dalle richieste listDrafts, listOutbox, listSent e listQueue che presentano
unicamente le informazioni base senza il contenuto) e si riferiscono al layout su cui la specifica
newsletter è basata.
Campi
• idLayout
• name
• plainText
Campo Tipo Descrizione
idLayout long Id univoco del layout.
name String Nome del layout
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 62 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
plainText boolean true se il layout è di testo semplice,
false altrimenti.
NewsletterWs
Rappresenta una qualsiasi newsletter.
Non sempre tutti gli attributi di oggetti di questo tipo, che vengono restituiti dalle richieste dei
servizi, hanno un valore; le richieste che ritornano delle liste di newsletter, per esempio,
restituiscono unicamente le informazioni base, trascurando volutamente di recuperare (e quindi di
restituire) le informazioni riguardo al contenuto. Anche lo stato di una newsletter influisce nella
costruzione degli oggetti restituiti. Ad esempio gli oggetti che rappresentano newsletter non ancora
spedite (bozze) non presentano alcun valore per gli attributi recipients, mailsent,
idMailingList, scheduledTime, senderName, senderAddress e subject.
Nella descrizione di ciascun campo sarà comunque indicato quando quello specifico campo è (o
dovrebbe essere in genere) presente.
Campi
• idNewsletter
• title
• status
• layout
• fields
• preview
• idMailingList
• senderName
• senderAddress
• subject
• scheduledTime
• recipients
• mailsent
Campo Tipo Descrizione
idNewsletter long Id univoco della newsletter.
title String Titolo della newsletter. Il titolo non è necessariamente
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 63 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
uguale all'oggetto delle mail quando la newsletter viene
inviata.
status String Stato della newsletter: qui di seguito sono elencati i
possibili valori ed il loro significato:
- A. Bozza, newsletter non ancora inviata
- O. Newsletter in uscita
- S. Newsletter inviata
- U. Newsletter inviata, ma in attesa di approvazione
layout LayoutWs Layout su cui è basata la newsletter
fields NewsletterFieldWs[] Campi della newsletter ed il loro contenuto.
NB: Questo attributo non è presente nelle risposte alle
richieste che restituiscono NewsletterWs[].
preview String Una stringa contenente l'anteprima della newsletter.
Se il layout utilizzato è plain-text sarà da intendersi
come del normale testo, altrimenti molto probabilmente
si tratterà del sorgente di un documento in formato
HTML.
NB: Questo attributo non è presente nelle risposte alle
richieste che restituiscono NewsletterWs[].
idMailingList long Id univoco della lista a cui si sta spedendo la newsletter.
Questo attributo è presente solo per newsletter con
status O, S e U.
senderName String Nome del mittente utilizzato nella spedizione della
newsletter.
Questo attributo è presente solo per newsletter con
status O, S e U.
senderAddress String Indirizzo di posta elettronica del mittente utilizzato nella
spedizione della newsletter.
Questo attributo è presente solo per newsletter con
status O, S e U.
subject String Oggetto della newsletter che si sta inviando.
Questo attributo è presente solo per newsletter con
status O, S e U.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 64 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
scheduledTime Date (xs:dateTime) Data pianificata per l'invio, se non è presente alcun
valore per questo attributo significa che l'invio è da
considerarsi immediato.
Questo attributo ha significato solo per newsletter con
status O, S e U.
recipients int Numero di destinatari ai quali dovrà essere inviata la
presente newsletter.
Questo attributo è presente solo per newsletter con
status O e S.
mailsent int Numero effettivo di newsletter inviate, questo numero
comprende anche gli errori (bouncing). Per le newsletter
il cui invio è terminato sarà sempre pari a recipients.
Assume quindi un particolare significato unicamente per
le newsletter in uscita (O).
Questo attributo è presente solo per newsletter con
status O e S.
NewsletterFieldWs
Rappresenta un generico campo di un layout con il contenuto associato per una specifica newsletter.
I campi gestiti dai web services sono esclusivamente i campi di tipo Textual e i campi di tipo
Image.
I campi di tipo Textual hanno un contenuto testuale che può eventualmente essere codice HTML.
I campi di tipo Image (unicamente presenti nei layout non plainText) contengono unicamente un
frammento di codice HTML con sintassi pari a:
[<a href="imageLink">]<img src="imageSource"/ [alt="imageAlt"]>[</a>]
Campi
• idField
• type
• empty
• textualContent
• imageSource
• imageLink
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 65 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
• imageAlt
Campo Tipo Descrizione
idField long Id univoco del campo del layout.
type String Tipo di campo. I valori possibili sono:
- Textual: Campo contente testo (semplice o HTML)
- Image: Campo immagine
- Other: altro tipo di campo non gestito dai web services
empty boolean true se il campo non presenta alcun contenuto in riferimento alla
newsletter alla newsletter specifica. false altrimenti.
textualContent String Il contenuto testuale del campo in riferimento alla specifica
newsletter.
Ha significato solamente per i campi di tipo Textual.
imageSource String Indirizzo relativo dell'immagine all'interno del sistema.
Ha significato solamente per i campi di tipo Image.
imageLink String Eventuale link a cui si rimanda se si seleziona l'immagine.
Ha significato solamente per i campi di tipo Image.
imageAlt String Eventuale testo alternativo dell'immagine.
Ha significato solamente per i campi di tipo Image.
SenderWs
Un oggetto di questo tipo rappresenta un mittente valido che può essere utilizzato nell'invio di una
newsletter.
Campi
• senderName
• senderAddress
Campo Tipo Descrizione
senderName String Nome di un mittente valido.
senderAddress String Indirizzo di posta elettronica di un
mittente valido.
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 66 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
NewsletterStatisticsWs
Un oggetto di questo tipo racchiude tutte le statistiche generalizi un invio (newsletter inviata).
Campi
• newsletter
• firstSpedition
• lastSpedition
• speditions
• speditionErrors
• opened
• totalOpened
• unsubscriptions
• viralSenders
• viralSents
• viralOpened
• viralSubscriptions
• linkStatistics
• pollStatistics
Campo Tipo Descrizione
newsletter NewsletterWs Newsletter a cui si riferiscono le statistiche di
invio.
firstSpedition Date
(xs:dateTime)
Data e ora del primo invio effettivo
lastSpedition Date
(xs:dateTime)
Data e ora dell'ultimo invio effettivo
speditions int Numero di email inviate
speditionErrors int Numero di errori di spedizione (bouncing).
opened int Numero di destinatari che hanno aperto la
newsletter.
totalOpened int Numero totale di aperture.
unsubscriptions int Numero di destinatari che si sono iscritti
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 67 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
utilizzando il link di deiscrizione presente nella
newsletter ricevuta.
viralSenders int Numero di destinatari che hanno segnalato la
newsletter ad un potenziale nuovo sottoscrittore.
viralSents int Numero totale di messaggi di viral marketing
inviati.
viralOpened int Numero totale dei destinatari del viral marketing,
che hanno visualizzato la newsletter.
viralSubscriptions int Numero totale dei destinatari che si sono iscritti
alla mailing list dopo aver ricevuto un messaggio
di viral marketing.
linkStatistics LinkStatisticsWs[] Elenco dei link presenti nel corpo della newsletter
e le rispettive statistiche.
pollStatistics PollStatisticsWs[] Elenco dei sondaggi presenti nella newsletter e le
rispettive statistiche.
LinkStatisticsWs
Un oggetto di questo tipo rappresenta un singolo link, e relative statistiche, presente all'interno del
corpo di una specifica newsletter.
Campi
• idLink
• url
• clicks
• totalClicks
Campo Tipo Descrizione
idLink long Id univoco del link.
url String Indirizzo del link.
clicks int Numero di utenti che hanno selezionato
il link.
totalClicks int Numero totale di volte che il link è
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 68 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
stato selezionato.
PollStatisticsWs
Un oggetto di questo tipo rappresenta un singolo sondaggio,e relative statistiche, presente all'interno
del corpo di una specifica newsletter.
Campi
• idPoll
• name
• question
• multipleChoice
• voters
• answers
Campo Tipo Descrizione
idPoll long Id univoco del sondaggio.
name String Nome del sondaggio.
question String Domanda del sondaggio.
multipleChoice boolean true se il sondaggio è a scelta multipla,
false se è a scelta singola.
voters int Numero totale di votanti.
answers AnswerStatisticsWs[] Elenco delle risposte possibili per il
sondaggio in questione e relative
statistiche.
AnswerStatisticsWs
Un oggetto di questo tipo rappresenta una singola opzione, e relative statistiche, di uno specifico
sondaggio presente all'interno del corpo di una specifica newsletter.
Campi
• idOption
• optionValue
Piattaforma Infomail – Manuale di utilizzo dei Web Service Pag. 69 di 69
HOPLO S.r.l. - Via Morghen, 27 - 10143 TORINO - P.IVA 08450220010 - www.hoplo.com - [email protected] T +39 011 7575647 - F +39 011 7575946
• answer
• votes
Campo Tipo Descrizione
idOption long Id univoco dell'opzione del sondaggio.
optionValue int Numero sequenziale dell'opzione in
riferimento alle altre dello stesso
sondaggio.
answer String Testo dell'opzione
votes int Numero di destinatari che hanno
selezionato questa specifica opzione.