User API - Guida all'utilizzo dei Web Service - 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:
|
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
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:
|
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:
|
lastnameFlag | String | Un carattere indicante il comportamento del campo cognome nel form di sottoscrizione:
|
contentChoiceFlag | String | Un carattere indicante il comportamento del campo scelta del contenuto nel form di sottoscrizione:
|
privacyFlag | String | Un carattere indicante il comportamento del campo accettazione della normativa sulla privacy nel form di sottoscrizione:
|
privacyText | String | Testo specifico della normativa sulla privacy associato alla lista |
formFields | FormFieldWs[] | Elenco degli eventuali campi opzionali del form. |
FormFieldWs
Un oggetto di questo tipo rappresenta un generico campo opzionale del form.
Campi
- idField
- name
- type
- required
- sequenceNumber
- options
Campo | Tipo | Descrizione |
idField | long | Id univoco di uno specifico campo del form di sottoscrizione alla mailing list. |
name | String | Nome del campo |
type | String | Tipo del campo del form. I valori possibili:
|
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
Campo | Tipo | Descrizione |
idOption | long | Id univoco di una specifica opzione. |
value | int | Valore numerico dell'opzione. Serve ad indicare l'ordine di comparizione dell'opzione stessa tra tutte quelle disponibili per lo specifico campo del form. |
text | String | Testo dell'opzione. |
AccountReaderWs
Un oggetto di questo tipo rappresenta unicamente un generico utente del sistema ed il suo stato di condivisione con una specifica lista. L'oggetto presenta unicamente le minime informazioni necessarie per identificare l'utente.
Campi
- id
- firstname
- lastname
- shared
Campo | Tipo | Descrizione |
id | long | Elenco di accoppiamenti nome-valore |
firstname | String | Nome dell'utente |
lastname | String | Cognome dell'utente. |
shared | boolean | Stato di condivisione. true la lista è condivisa con l'utente. false la lista non è condivisa con l'utente |
RecipientWs
Un oggetto di questo tipo rappresenta un generico destinatario appartenente ad una lista base.
Campi
- id
- idMailingList
- firstname
- lastname
- contentChoice
- fields
- blocked
- blockedType
- subscribed
- reportMessage
Campo | Tipo | Descrizione |
id | long | id univoco del destinatario |
idMailingList | long | id univoco della mailing list a cui appartiene il destinatario |
String | indirizzo email del destinatario | |
firstname | String | nome del destinatario |
lastname | String | cognome del destinatario |
contentChoice | String | tipo di contenuto scelto dal destinatario |
fields | RecipientFieldWs[] | elenco dei campi opzionali definiti per il form di sottoscrizione, con le eventuali risposte |
blocked | Boolean | se è bloccato true o meno false |
blockedType | String | il tipo di blocco |
subscribed | Boolean | se il destinatario è iscritto true o meno false |
reportMessage | String | eventuale messaggio dell'errore che si è verificato nella richiesta addRecipientList o updateRecipientList quando si è tentato di processare il destinatario rappresentato da questo oggetto |
RecipientFieldWs
Un oggetto di questo tipo rappresenta il generico campo opzionale di un form di sottoscrizione comprensivo dei valori specifici scelti dall'utente. Un oggetto di questo tipo ha sempre un corrispondente FormFieldWs riferito alla stessa lista. L'elenco dei valori specifici che assume il campo in questione è un sottoinsieme delle opzioni definite come FormFieldOptionsWs, semprein riferimento allo stesso campo.
Campi
- id
- fieldName
- answers
Campo | Tipo | Descrizione |
id | long | Id univoco di uno specifico campo del form di sottoscrizione alla mailing list. |
fieldName | String | Nome del campo |
answers | RecipientAnswerWs[] | Elenco dei valori assunti da tale campo per uno specifico utente. Se si tratta di un campo a scelta singola (radio button o drop-down selection) o testo libero sarà disponibile al più un unico elemento. |
RecipientAnswerWs
Un singolo valore assunto da uno specifico campo del form per uno specifico destinatario. Per chiarimenti su come questi oggetti sono legati con gli oggetti FormFieldOptionsWs vedere l'esempio.
Campi
- idOption
- value
- text
Campo | Tipo | Descrizione |
idOption | long | Id univoco di uno specifica opzione. |
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. |
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
Campo | Tipo | Descrizione |
fieldName | String | Nome del campo. Esso può essere uno tra:
|
idField | long | Id univoco di uno specifico campo del form di sottoscrizione alla mailing list. per quanto riguarda i campi fissi (email, firstname, lastname) il assume un valore nullo, mentre riveste fondamentale importanza per i campi opzionali. |
SearchResultWs
Rappresenta il risultato di una ricerca.
Campi
- recipients
- page
- maxRecipientsPerPage
- totalRecipients
Campo | Tipo | Descrizione |
recipients | RecipientWs[] | Elenco dei risultati di una ricerca, fino ad un massimo di maxRecipientsPerPage (250) 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
- description
- footerHtml
- footerTxt
- footerViralHtml
- headerHtml
- headerPollsHtml
- headerPollsTxt
- headerTxt
- headerViralHtml
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 |
FileWs
Questo tipo di data-object vuole rappresentare un generico file; nello specifico esso contiene unicamente due informazioni: un nome ed il suo contenuto.
Campi
- fileName
- fileData
Campo | Tipo | Descrizione |
fileName | String | Il nome del file. O in maniera più generale il nome con cui associare lo stream di byte specificati nell'attributo fileData. |
fileData | xs:base64Binary | Lo stream di byte corrispondente al contenuto binario del file. |
LayoutWs
Un oggetto che rappresenta un generico layout. Questo oggetto non contiene le informazioni riguardanti i campi che compongono il layout stesso. Tali informazioni sono tuttavia disponibili all'interno degli oggetti NewsletterWs (ad esclusione di quelli restituiti dalle richieste listDrafts, listOutbox, listSent e listQueue che presentano unicamente le informazioni base senza il contenuto) e si riferiscono al layout su cui la specifica newsletter è basata.
Campi
- idLayout
- name
- plainText
Campo | Tipo | Descrizione |
idLayout | long | Id univoco del layout. |
name | String | Nome del layout |
plainText | boolean | true se il layout è di testo semplice, false altrimenti. |
NewsletterWs
Rappresenta una qualsiasi newsletter.
Non sempre tutti gli attributi di oggetti di questo tipo, che vengono restituiti dalle richieste dei servizi, hanno un valore; le richieste che ritornano delle liste di newsletter, per esempio, restituiscono unicamente le informazioni base, trascurando volutamente di recuperare (e quindi di restituire) le informazioni riguardo al contenuto. Anche lo stato di una newsletter influisce nella costruzione degli oggetti restituiti. Ad esempio gli oggetti che rappresentano newsletter non ancora spedite (bozze) non presentano alcun valore per gli attributi recipients, mailsent, idMailingList, scheduledTime, senderName, senderAddress e subject.
Nella descrizione di ciascun campo sarà comunque indicato quando quello specifico campo è (o dovrebbe essere in genere) presente.
Campi
- idNewsletter
- title
- status
- layout
- fields
- preview
- idMailingList
- senderName
- senderAddress
- subject
- scheduledTime
- recipients
- mailsent
Campo | Tipo | Descrizione |
idNewsletter | long | Id univoco della newsletter. |
title | String | Titolo della newsletter. Il titolo non è necessariamente 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:
|
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. |
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
Campo | Tipo | Descrizione |
idField | long | Id univoco del campo del layout. |
type | String | Tipo di campo. I valori possibili sono:
|
empty | boolean | true se il campo non presenta alcun contenuto in riferimento alla newsletter alla newsletter specifica. false altrimenti. |
textualContent | String | Il contenuto testuale del campo in riferimento alla specifica newsletter. Ha significato solamente per i campi di tipo Textual. |
imageSource | String | Indirizzo relativo dell'immagine all'interno del sistema. Ha significato solamente per i campi di tipo Image. |
imageLink | String | Eventuale link a cui si rimanda se si seleziona l'immagine. Ha significato solamente per i campi di tipo Image. |
imageAlt | String | Eventuale testo alternativo dell'immagine. Ha significato solamente per i campi di tipo Image. |
SenderWs
Un oggetto di questo tipo rappresenta un mittente valido che può essere utilizzato nell'invio di una newsletter.
Campi
- senderName
- senderAddress
Campo | Tipo | Descrizione |
senderName | String | Nome di un mittente valido. |
senderAddress | String | Indirizzo di posta elettronica di un mittente valido. |
NewsletterStatisticsWs
Un oggetto di questo tipo racchiude tutte le statistiche generalizi un invio (newsletter inviata).
Campi
- newsletter
- firstSpedition
- lastSpedition
- speditions
- speditionErrors
- opened
- totalOpened
- unsubscriptions
- viralSenders
- viralSents
- viralOpened
- viralSubscriptions
- linkStatistics
- pollStatistics
Campo | Tipo | Descrizione |
newsletter | NewsletterWs | Newsletter a cui si riferiscono le statistiche di invio. |
firstSpedition | Date(xs:dateTime) | Data e ora del primo invio effettivo |
lastSpedition | Date(xs:dateTime) | Data e ora dell'ultimo invio effettivo. |
speditions | int | Numero di email inviate |
speditionErrors | int | Numero di errori di spedizione (bouncing). |
opened | int | Numero di destinatari che hanno aperto la newsletter. |
totalOpened | int | Numero totale di aperture. |
unsubscriptions | int | Numero di destinatari che si sono iscritti utilizzando il link di deiscrizione presente nella newsletter ricevuta. |
viralSenders | int | Numero di destinatari che hanno segnalato la newsletter ad un potenziale nuovo sottoscrittore. |
viralSents | int | Numero totale di messaggi di viral marketing inviati. |
viralOpened | int | Numero totale dei destinatari del viral marketing, che hanno visualizzato la newsletter. |
viralSubscriptions | int | Numero totale dei destinatari che si sono iscritti alla mailing list dopo aver ricevuto un messaggio di viral marketing. |
linkStatistics | LinkStatisticsWs[] | Elenco dei link presenti nel corpo della newsletter e le rispettive statistiche. |
pollStatistics | PollStatisticsWs[] | Elenco dei sondaggi presenti nella newsletter e le rispettive statistiche. |
LinkStatisticsWs
Un oggetto di questo tipo rappresenta un singolo link, e relative statistiche, presente all'interno del corpo di una specifica newsletter.
Campi
- idLink
- url
- clicks
- totalClicks
Campo | Tipo | Descrizione |
idLink | long | Id univoco del link. |
url | String | Indirizzo del link. |
clicks | int | Numero di utenti che hanno selezionato il link. |
totalClicks | int | Numero totale di volte che il link è stato selezionato. |
PollStatisticsWs
Un oggetto di questo tipo rappresenta un singolo sondaggio,e relative statistiche, presente all'interno del corpo di una specifica newsletter.
Campi
- idPoll
- name
- question
- multipleChoice
- voters
- answers
Campo | Tipo | Descrizione |
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. |
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
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. |