Manuale API - Infomail

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



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.



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.



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)



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



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



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.



Parametri

token String Il token che si vuole invalidare.

Risposta

Nessuna



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.



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


corrente.

name String Il nome della lista che si vuole creare.

comment String Opzionale. Un breve commento, nota mnemonica sulla

lista.

firstnameFlag String Opzionale. Una stringa di un carattere che indica come

l'applicazione si deve comportare nella definizione del form

di sottoscrizione in relazione al campo firstname (nome). I

valori possibili sono:

• H(idden) il campo nome non viene mostrato



• R(equired) il campo nome è obbligatorio

• O(ptional) il campo nome è opzionale

Se omesso si assumerà il valore di default pari a O(ptional)

lastnameFlag String Opzionale. Una stringa di un carattere che indica come


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


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


di sottoscrizione in relazione al checkbox sull'accettazione

della normativa sulla privacy. I valori possibili sono:

• H(idden) l'accettazione della privacy non viene



mostrata

• R(equired) l'accettazione della privacy è

obbligatoria

• O(ptional) l'accettazione della privacy è opzionale

Se omesso si assumerà il valore di default pari a R(equired)

privacyText String Opzionale. Il testo della normativa sulla privacy da

visualizzare. Se assente verrà preimpostato il testo generico

definito nell'applicazione.

formFields FormFieldWs[] Un elenco di campi opzionali da inserire per ogni elemento

della lista e da mostrare nel form di sottoscrizione. Nella

definizione di nuovi campi del form solo i seguenti

attributi dell'Oggetto FormFieldWs vengono presi in

considerazione:

• name: il nome del campo

• type: tipo del campo. I valori possibili sono:

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.



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


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


di sottoscrizione in relazione al campo firstname (nome). I


• 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


di sottoscrizione in relazione al campo lastname (nome). I


• H(idden) il campo cognome non viene mostrato

• R(equired) il campo cognome è obbligatorio

• O(ptional) il campo cognome è opzionale


contentChoiceFlag String Opzionale. Una stringa di due caratteri che indica come




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


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


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


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.



deleteMailingList

Elimina una mailing list.


deleteMailingList non permette di eliminare la lista di test e le liste di altri utenti condivise


Parametri


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.


addFormField non permette di modificare la lista di test e le liste di altri utenti condivise all'utente

corrente.

Parametri


idMailingList long L'id univoco della mailing list di cui si vuole modificare il

form di sottoscrizione.

fieldName String Il nome del campo che si vuole aggiungere.

fieldType String Il tipo di campo che si vuole aggiungere. I valori possibili

sono:

• S campo a scelta singola; realizzato per mezzo di

radio buttons



• D campo a scelta singola;realizzato per mezzo di

tendina di selezione (drop-down selection)

• M campo a scelta multipla; realizzato tramite

checkbox

• F campo di testo libero; realizzato da un semplice

campo di testo.

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


apportate.

updateFormField

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


updateFormField non permette di modificare la lista di test e le liste di altri utenti condivise


Parametri




idFormField long L'id univoco del campo del form che si vuole modificare.

fieldName String Opzionale. Il nuovo nome che si vuole dare al campo. Se

omesso verrà mantenuto il nome precedente.

required boolean Opzionale. L'obbligatorietà del campo all'atto della



compilazione del form di sottoscrizione. Se true il campo è

obbligatorio. Se omesso verrà mantenuto il valore

precedentemente definito.

Risposta


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.


moveFormField non permette di modificare la lista di test e le liste di altri utenti condivise


Parametri





decreasePosition boolean La posizione del campo nel form di sottoscrizione è

rappresentata dal valore dell'attributo sequenceNumber

dell'oggetto FormFieldWs che rappresenta il campo stesso.

Il valore 0 rappresenta il primo tra i campi opzionali del

form(vengono prima di tutti i campi nome, cognome, email ed

eventualmente scelta del contenuto), 1 il secondo e così via.

Se decreasePosition è pari a true il valore assunto da

sequenceNumber del campo specifico diminuisce di 1 (minimo

0) mentre il campo immediatamente prima aumenta il proprio

sequenceNumber di 1. Ottenendo in questa maniera lo scambio



di posizione tra il campo in esame con quello subito prima.

Se decreasePosition è pari a false avviene l'esatto contrario.

Se il campo è il primo della lista (sequenceNumber uguale a 0)

l'operazione con decreasePosition true non ha alcun

effetto.

Se il campo è l'ultimo della lista (sequenceNumber uguale al

numero totale dei campi meno 1) l'operazione con

decreasePosition false non ha alcun effetto.

Risposta


apportate.

deleteFormField

Elimina un campo del form.


deleteFormField non permette di modificare la lista di test e le liste di altri utenti condivise


Parametri


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


apportate.



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.


addOptionFormField non permette di modificare la lista di test e le liste di altri utenti condivise


Parametri





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.


deleteOptionFormField non permette di modificare la lista di test e le liste di altri utenti condivise


Parametri




idMailingList long L'id univoco della mailing list di cui si vuole modificare il form

di sottoscrizione.


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


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.



Risposta

AccountReaderWs[] L'elenco di tutti gli account e il loro specifico stato di condivisione attuale.



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




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




corrente.

idMailingList Long L'id univoco della mailing list a cui si vuole aggiungere il

destinatario.

email String L'indirizzo email del destinatario. L'indirizzo email deve

avere una forma valida.

firstname String Opzionale. Il nome del destinatario

lastname String Opzionale. Il cognome del destinatario

blocked Boolean Opzionale. Se il destinatario deve essere creato in stato

bloccato. Se omesso il destinatario viene creato attivo.

subscribed Boolean Opzionale. Se il destinatario deve essere creato in stato

subscribed (iscritto). Se omesso viene creato in stato

subscribed (iscritto)

contentChoice String Opzionale. Il tipo del contenuto scelto dallo specifico

destinatario. I valori possibili sono:

• M Multipart

• P Plaintext

Se l'utente corrente non ha il modulo corrispondente attivo,

viene impostato comunque a M.

Se l'utente ha il modulo attivo e tale parametro viene

omesso viene impostato il valore di default definito per la

lista (vedi createMailingList e updateMailingList su

MailingListService).

fields RecipientFieldWs[] La lista dei valori assunti per lo specifico destinatario dai

campi opzionali definiti nel form di sottoscrizione alla

mailing list.

Per ciascuno dei campi opzionali che si vuole valorizzare

con una (o più nel caso di campi a scelta multipla) delle

opzioni disponibili deve essere definito un

RecipientFieldWs valorizzando unicamente gli attributi:

• id: l'id univoco del campo del form

• answers: l'elenco delle risposte per tale campo.



Le risposte sono oggetti di tipo RecipientAnswerWs. La

risposta può essere individuata vari modi. Le varie modalità

sono descritte qui (1) .

Risposta

RecipientWs Il destinatario appena creato.

(1) In fase di inserimento le risposte ad un campo del form devono essere segnalate nei seguenti

modi:

• 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


recipients RecipientWs[] L'elenco dei destinatari da aggiungere. Non tutti gli attributi

degli elementi della richiesta devono essere valorizzati, in

riferimento alla richiesta addRecipient i seguenti attributi

sono obbligatori:

• idMailingList

• email



I seguenti attributi sono invece opzionali (riferirsi

eventualmente alla richiesta addRecipient per conoscere i

valori di default) :

• firstname

• lastname

• blocked

• subscribed

• contentChoice

• fields

Risposta

RecipientWs[] Diversamente da quanto capita per l'aggiunta di un singolo destinatario, questa

richiesta non restituisce un fault per le motivazioni esposte in riferimento alla

richiesta addRecipient.

Tuttavia, tali errori, vengono segnalati nella risposta, tramite l'attributo

reportMessage dei singoli destinatari.

In caso di eventuali errori durante l'aggiunta di uno specifico elemento della

richiesta, l'elemento viene restituito nella risposta così come è stato ricevuto e con

l'attributo sopra indicato valorizzato alla motivazione dell'eventuale errore.

Se l'inserimento del singolo destinatario va a buon fine l'elemento corrispondete

restituito ha tale attributo non valorizzato.

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.






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


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



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


recipients RecipientWs[] L'elenco dei destinatari da modificare. Non tutti gli attributi

degli elementi della richiesta devono essere valorizzati,

riferirsi alla richiesta updateRecipient per sapere quali



attributi (e come) valorizzarli. Gli attributi definiti negli

elementi di questo elenco vengono in sintesi trasposti nei

parametri di singole richieste updateRecipient.

Risposta

RecipientWs[] Analogamente alla richiesta addRecipientList gli elementi della risposta

presentano l'attributo reportMessage valorizzato qualora la modifica del

destinatario definito da quello specifico elemento abbia generato un errore.

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.




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


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



boolean true se l'eliminazione è andata a buon fine.

removeRecipientList

Elimina in un'unica richiesta un elenco di destinatari.

Parametri


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

• email

• nome

• cognome

• eventuali campi del form opzionali



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

servizio MailingListService.

Parametri


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



ricerca, selezionare una particolare pagina (blocco di 250 risultati), se la ricerca producesse più di

250 destinatari.

Parametri


idMailingList Long L'id univoco della lista su cui si vuole effettuare la ricerca.

searchField SearchFieldWs Il campo su cui effettuare la ricerca: vedere il risultato della

richiesta getSearchFields per veder quali campi sono

disponibili.

searchString String Stringa da cercare per il campo in questione. Se non si

specifica alcuna stringa questo equivale a non definire alcun

vincolo per il campo in questione.

blockFilter String[] Opzionale. Un filtro sullo stato di blocco dei destinatari. Nel

risultato compariranno solo coloro il cui stato di blocco è tra

quelli elencati nel filtro. Il non specificare alcun filtro sul

blocco equivale al non voler filtrare i risultati in base a tale

valore. I valori possibili del filtro sono:

• A destinatari attivi (non bloccati)

• BG destinatari bloccati manualmente (compresi

quelli in black list)

• BB destinatari bloccati dal bouncing

• BA destinatari bloccati in attesa della conferma di

sottoscrizione.

subscribedFilter String[] Opzionale. Un filtro sullo stato di sottoscrizione dei

destinatari. Nel risultato compariranno solo coloro il cui

stato di iscrizione è tra quelli elencati nel filtro. Il non

specificare alcun filtro sullo stato di iscrizione equivale al

non voler filtrare i risultati in base a tale valore. I valori

possibili del filtro sono:

• true destinatari iscritti

• false destinatari che hanno chiesto la deiscrizione ma

non hanno ancora confermato tale scelta (compresi



quelli deiscritti manualmente dall’utente possessore

della lista).

contentFilter String[] Opzionale. Un filtro sulla tipo di contenuto scelto dal

destinatario. Tale filtro viene preso in considerazione solo se

l'utente ha il modulo corrispondente attivo. Il non specificare

alcun filtro sul tipo di contenuto equivale al non voler

filtrare i risultati in base a tale valore. I valori possibili del

filtro sono:

• M destinatari che hanno scelto di ricevere mail

multipart

• P destinatari che hanno scelto di ricevere email solo

testo

page int Opzionale. Il numero della pagina (o blocco) di risultati. Se

non venisse specificato, qualora la ricerca producesse più di

250 risultati solamente i primi 250 comparirebbe nella

risposta (page = 0).

Risposta

SearchResultWs Il risultato della ricerca comprensivo di:

• Numero totale dei destinatari che rispettano i criteri di ricerca.

• Pagina corrente

• Numero dei risultati per pagina

• Elenco dei destinatari (massimo 250)

Qualora un destinatario rispecchiasse i criteri di ricerca ma il suo indirizzo email

fosse presente nella black list, verrebbe comunque restituito un elemento per tale

destinatario ma con dati oscurati.



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



• 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


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




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


corrente.

Risposta

NewsletterWs[] Elenco delle newsletter in uscita.

listSent

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

Parametri


corrente.

Risposta

NewsletterWs[] Elenco delle newsletter spedite.



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


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


corrente.

idNewsletter long Id univoco della newsletter di cui si vogliono ricevere i

dettagli.

Risposta



NewsletterWs La newsletter ricercata

createNewsletter

Crea una nuova newsletter vuota.

Parametri


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


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.



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


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




corrente.


contenuto.

field NewsletterFieldWs Il campo di cui si vuole eliminare il contenuto. Nello

specifico è obbligatorio specificare unicamente l'attributo

idField.

Risposta


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


corrente.


contenuto.

field NewsletterFieldWs Il nuovo contenuto per il campo in questione.

Nello specifico è obbligatorio specificare i seguenti

attributi:

• idField: id del campo di cui si vuole aggiornare il

contenuto

I seguenti attributi sono opzionali:



• imageLink: il link a cui si rimanda se si seleziona

l'immagine. Default nessuno

• imageAlt: il testo alternativo dell'immagine. Viene

visualizzato se l'utente finale ha le immagini

disabilitate. Default nessuno.

Gli altri attributi non sono necessari.

imageFile FileWs Il file (binario) con l'immagine che si vuole caricare.

Risposta


clearImageField

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

ancora inviata.

Parametri


corrente.


contenuto.

field NewsletterFieldWs Il campo di cui si vuole eliminare il contenuto. Nello


idField.

Risposta


uploadHtml

Con questa richiesta è possibile aggiornare il contenuto di un campo testuale (HTML), in funzione

del contenuto dell'archivio archivio Zip mandato come parametro della richiesta. Si rimanda alla



documentazione dell'applicazione per sapere come deve essere formato il contenuto dell'archivio

Zip.

Parametri


corrente.


contenuto.

field NewsletterFieldWs Il campo di cui si vuole aggiornare il contenuto. Nello


idField.

zipFile FileWs Il file (binario) che rappresenta l'archivio Zip contente i file

necessari a costruire il contenuto per il campo specificato.

Risposta


listSenders

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

newsletter.

Parametri


corrente.

Risposta

SenderWs[] L'elenco dei mittenti validi dell'utente specifico.

sendTest

Effettua l'invio di test di una bozza.



Un invio di test viene effettuato con questi parametri:

• Lista utilizzata: Lista di test dell'account specifico

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

dell'account).

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

creazione.

• Data di invio: immediato.

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

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

uscita).

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

sono disabilitati.

Parametri


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').



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


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.



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


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.



Parametri


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


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.



listHeaderFooter

Restituisce l’elenco degli Header e Footer disponibili.

Parametri


Risposta

HeadersAndFootersWs[] L’elenco degli Header e Footer disponibili.

setHeadersAndFooters

Consente di assegnare ad una newsletter un Header e Footer.

Parametri


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.



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


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.



Parametri


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.



Guida agli oggetti

• MailingListWs

• EnhancedMailingListWs

• FormFieldWs

• FormFieldOptionsWs

• AccountReaderWs

• RecipientWs

• RecipientFieldWs

• RecipientAnswerWs

• SearchFieldWs

• SearchResultWs

• HeaderAndFootersWs

• FileWs

• LayoutWs

• NewsletterWs

• NewsletterFieldWs

• SenderWs

• NewsletterStatisticsWs

• LinkStatisticsWs

• PollStatisticsWs

• AnswerStatisticsWs



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.



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


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



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



• 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


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



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


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



• id

• firstname

• lastname

• shared


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

• email

• firstname

• lastname

• contentChoice

• fields

• blocked

• blockedType

• subscribed

• reportMessage


id long id univoco del destinatario

idMailingList long id univoco della mailing list a cui



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




id long Id univoco di uno specifico campo del


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


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.



Campi

• fieldName

• idField


fieldName String Nome del campo. Esso può essere uno

tra:

• email

• firstname

• lastname

oppure il nome di un generico campo

opzionale come ad esempio hobbies.

idField long Id univoco di uno specifico campo del


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


recipients RecipientWs[] Elenco dei risultati di una ricerca, fino

ad un massimo di

maxRecipientsPerPage (250)



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


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



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


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


idLayout long Id univoco del layout.

name String Nome del layout



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


idNewsletter long Id univoco della newsletter.

title String Titolo della newsletter. Il titolo non è necessariamente



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.


status O, S e U.

senderAddress String Indirizzo di posta elettronica del mittente utilizzato nella

spedizione della newsletter.


status O, S e U.

subject String Oggetto della newsletter che si sta inviando.


status O, S e U.



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.


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).


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



• imageAlt


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.


imageAlt String Eventuale testo alternativo dell'immagine.


SenderWs

Un oggetto di questo tipo rappresenta un mittente valido che può essere utilizzato nell'invio di una

newsletter.

Campi

• senderName

• senderAddress


senderName String Nome di un mittente valido.

senderAddress String Indirizzo di posta elettronica di un

mittente valido.



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


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



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


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 è



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


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



• answer

• votes


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.

Manuale API - Infomail

Documents

Transcript of Manuale API - Infomail