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

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

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.
Torna su ^

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

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.
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.
Torna su ^

FormFieldWs

Un oggetto di questo tipo rappresenta un generico campo opzionale del form.

Campi

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 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.
Torna su ^

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

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.
Torna su ^

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

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
Torna su ^

RecipientWs

Un oggetto di questo tipo rappresenta un generico destinatario appartenente ad una lista base.

Campi

Campo Tipo Descrizione
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
Torna su ^

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

Campo Tipo Descrizione
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.
Torna su ^

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

Campo Tipo Descrizione
idOption long Id univoco di uno specifica opzione.
value int Valore numerico dell'opzione. Analogo al campo value di FormFieldOptionsWs.
text String Testo dell'opzione e quindi della risposta per uno specifico utente.
Torna su ^

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

Campo Tipo Descrizione
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 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.
Torna su ^

SearchResultWs

Rappresenta il risultato di una ricerca.

Campi

Campo Tipo Descrizione
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.
Torna su ^

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 String 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
Torna su ^

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

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.
Torna su ^

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

Campo Tipo Descrizione
idLayout long Id univoco del layout.
name String Nome del layout
plainText boolean true se il layout è di testo semplice, false altrimenti.
Torna su ^

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

Campo Tipo Descrizione
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
  • N 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.
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.
Torna su ^

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

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.
Torna su ^

SenderWs

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

Campi

Campo Tipo Descrizione
senderName String Nome di un mittente valido.
senderAddress String Indirizzo di posta elettronica di un mittente valido.
Torna su ^

NewsletterStatisticsWs

Un oggetto di questo tipo racchiude tutte le statistiche generalizi un invio (newsletter inviata).

Campi

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 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.
Torna su ^

LinkStatisticsWs

Un oggetto di questo tipo rappresenta un singolo link, e relative statistiche, presente all'interno del corpo di una specifica newsletter.

Campi

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 è stato selezionato.
Torna su ^

PollStatisticsWs

Un oggetto di questo tipo rappresenta un singolo sondaggio,e relative statistiche, presente all'interno del corpo di una specifica newsletter.

Campi

Campo Tipo Descrizione
idLink long Id univoco del sondaggio.
url String Nome del sondaggio.
clicks String Domanda del sondaggio.
totalClicks boolean true se il sondaggio è a scelta multipla, false se è a scelta singola.
totalClicks int Numero totale di votanti.
totalClicks AnswerStatisticsWs[] Elenco delle risposte possibili per il sondaggio in questione e relative statistiche.
Torna su ^

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

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.
Torna su ^