Specifiche API

voxmail.info

Ottiene un array contenente diverse informazioni sul servizio.

credits

Numero di crediti disponibili (-1 se non applicabile)

privacy_policy

Testo della privacy impostato

users

Numero di utenti registrati

voxmail.newsletter.load

Ritorna i dati della newsletter richiesta, se presente.
L'array ottenuto con questa funzione contiene le seguenti chiavi:

nid

Identificativo univoco della newsletter

created

Data di creazione, in formato timestamp unix (numero di secondi dal 1/1/1970).

changed

Data di ultima modifica, in formato timestamp unix (numero di secondi dal 1/1/1970).

title

Soggetto

body

Testo, in formato HTML.

body_alt

Testo alternativo in formato testo semplice, se presente

body_alt_generate

Indica se è prevista una autogenerazione del testo alternativo semplice (0|1)

audience

Elenco separato da "," di identificativi univoci di audience, che formano il gruppo destinatario della newsletter

cid

Identificativo univoco della campagna che contiene la newsletter

credits

Numero di crediti usati per la spedizione della newsletter

template_nid

Identificativo univoco di modello (se presente)

from_name

Nome da inserire come mittente

from

Indirizzo e-mail usato come mittente

to

Nome usato come destinatario

track_open

Indica se è attivo il tracciamento delle aperture (0|1)

track_all_links

Indica se è attivo il tracciamento dei clic su tutti i link presenti nel testo (0|1)

Argomenti

int nid (obbligatorio)

Identificativo univoco della newsletter

array fields (facoltativo)

Array di campi da includere nella risposta (per un elenco dei campi vedi la chiamata newsletter.load)

voxmail.newsletter.create

Crea una nuova newsletter con i dati inseriti (viene inserita come bozza e NON inviata).
La chiamata ritorna l'identificativo univoco della newsletter generata.

Argomenti

struct data (obbligatorio)

Un array contenente i dati della newsletter da generare.
I dati sono nello stesso formato usato per il risultato della chiamata newsletter.load

voxmail.newsletter.update

Modifica i dati di una newsletter con quelli passati.
La newsletter deve già esistere e non deve essere spedita (quindi deve essere in stato bozza)

Argomenti

int nid (obbligatorio)

Identificativo univoco della newsletter

struct data (obbligatorio)

Un array contenente i dati da modificare
I dati sono nello stesso formato usato per il risultato della chiamata newsletter.load.
I parametri non passati vengono mantenuti inalterati.

voxmail.newsletter.delete

Elimina una newsletter generata, purchè in stato di bozza (non inviata).

Argomenti

int nid (obbligatorio)

Identificativo univoco della newsletter

voxmail.newsletter.duplicate

Crea una copia esatta della newsletter con l'identificativo specificato, mettendola in stato bozza (quindi pronta per essere modificata e/o inviata).
La chiamata ritorna l'identificativo univoco della nuova newsletter

Argomenti

int nid (obbligatorio)

Identificativo univoco della newsletter

voxmail.newsletter.check

Effettua una verifica sulla newsletter ancora da inviare, per identificare eventuali problemi per l'invio.
Il risultato è composto da un array con 4 chiavi: checks, details, data e errors.
Questo il significato di ognuna:

checks

Contiene un array che associa una tipologia di controllo al suo risultato. Questo risultato può essere:
ok, info, warn, error.
In caso di error il controllo ha riportato un errore bloccante che ne pregiudica l'invio.

details

Contiene un array che associa a ognuna della 4 tipologie di risultati (ok, info, warn, error) un elenco di controlli che hanno riportato tale risultato e la descrizione estesa del controllo

data

Contiene, in forma di array, alcuni dati aggiuntivi derivati dalla verifica. Tra questi:
urls_detected: il numero di url diversi individuati nella newsletter
urls_tracked: il numero di url tracciati individuati nella newsletter
urls_tracked_array: un array di url individuati nella newsletter e tracciati
credits: Il numero di crediti che verranno scalati per l'invio della newsletter

errors

Indica se la verifica complessiva ha individuato degli errori che pregiudicano l'invio (0|1)

Argomenti

int nid (obbligatorio)

Identificativo univoco della newsletter

voxmail.newsletter.send

Invia la newsletter specificata.
Ritorna TRUE in caso di successo.

Argomenti

int nid (obbligatorio)

Identificativo univoco della newsletter

int timestamp (facoltativo)

*.timestamp

voxmail.newsletter.csend

Crea la newsletter, la controlla e se valida la invia.
Il risultato è lo stesso di newsletter.check, con l'aggiunta di 2 chiavi: nid, sent.

nid

L'identificatore univoco di newsletter generato

sent

Indica se è stata effettivamente spedita o meno, in genere se non spedita indica un errore di verifica

Argomenti

struct data (obbligatorio)

Un array contenente i dati della newsletter da generare.
I dati sono nello stesso formato usato per il risultato della chiamata newsletter.load

int timestamp (facoltativo)

*.timestamp

voxmail.newsletter.send_test

Invia un test della newsletter.
Ritorna TRUE in caso di successo.

Argomenti

int nid (obbligatorio)

Identificativo univoco della newsletter

voxmail.newsletter.results

Permette di consultare l'insieme dei risultati relativi alla spedizione di una newsletter.
Il metodo ritorna un array con le seguenti chiavi:

sent

Data effettiva di invio, in formato timestamp unix (numero di secondi dal 1/1/1970).

recipients

Numero complessivo di destinatari, ossia di componenti degli audience di destinazione.

delivered

Numero di destinatari per i quali la newsletter è da considerarsi consegnata (in quanto non hanno riportato errori).

failed

Numero di destinatari che hanno riportato un errore di spedizione.

delaying

Numero di destinatari che sono contrassegnati come da riprovare (il cui invio è stato ritardato dal server di destinazione, in genere per politiche antispam o per errori temporanei).

opens

Numero complessivo di aperture rilevate (vengono quindi conteggiate anche le aperture multiple dello stesso destinatario).

firstopen

Data della prima apertura rilevata, in formato timestamp unix (numero di secondi dal 1/1/1970).

lastopen

Data dell'ultima apertura rilevata, in formato timestamp unix (numero di secondi dal 1/1/1970).

readers

Numero di destinatari per i quali è stata rilevata l'effettiva apertura della newsletter.

clickers

Numero di destinatari per i quali è stata rilevato un clic su uno dei link tracciati.

unsubs

Numero di destinatari che hanno richiesto la disiscrizione del servizio attraverso un link presente nella newsletter.

imgviews

Numero di destinatari per i quali è stata rilevata la visualizzazione delle immagini presenti nella newsletter (una delle tecniche usate per il tracciamento delle aperture).

tried

Numero complessivo di destinatari ai quali è stata spedita la newsletter (può essere usato durante l'invio per controllare lo stato di avanzamento).

stats

Un array che contiene delle tabelle con ulteriori dettagli sui risultati. Il contenuto di stats dipende dal valore impostato per il parametro section.

L'array stats a sua volta può contenere le seguenti chiavi:

failures

Tabella degli errori (contenente tipologia degli errori e numero di riscontri per tipo).

opentimes

Tabelle delle aperture orarie (a partire dall'ora di invio)

clicks

Tabella dei click rilevati (conenente url e numero di clic relativi)

clicksh

Tabella dei clic orari

Argomenti

int nid (obbligatorio)

Identificativo univoco della newsletter

string section (facoltativo)

Permette di specificare quali sezioni dell'array stats del risultato devono essere compilate.
Può assumere il valore all se si desidera ottenere tutti i dettagli, altrimenti occorre inserire il nome della chiave che si desidera avere, tra questi: failures, opentimes, clicks, clicksh.
Non inserendo alcun valore la sezione stats non sarà compilata.

voxmail.newsletter.list

Accede all'elenco delle newsletter che soddisfano i criteri specificati.
Il risultato è un array contenente le newsletter richieste. Ogni newsletter è nel formato ottenuto dal metodo newsletter.load

Argomenti

array filters (facoltativo)

Permette di specificare un array di filtri da utilizzare per la ricerca.
I filtri supportati al momento sono:
cid: Imposta l'identificativo di campagna, in modo da ottenere le newsletter solo della campagna specificata.
status: Permette di filtrare in baso allo stato della newsletter. Può assumere uno di questi valori: ready, scheduled, sending, sent, error.

string order (facoltativo)

(Parametro non supportato)

int pageLength (facoltativo)

Numero di risultati che si desidera ottenere

int pageNo (facoltativo)

(Parametro non supportato)

voxmail.user.load

Carica i dati relativi a un utente presente nel sistema.
Il risultato, nel caso l'utente richiesto viene trovato, è un array contenente questi dati:

uid

Indentificativo univoco dell'utente.

mail

Indirizzo e-mail.

created

Data di registrazione dell'utente, in formato timestamp unix (numero di secondi dal 1/1/1970).

access

Ultimo accesso dell'utente al suo pannello di controllo (l'accesso viene eseguito anche in caso di conferma di iscrizione, visualizzazione di una newsletter tramite web o in generale qualunque richiesta che necessiti di autentificazione), in formato timestamp unix (numero di secondi dal 1/1/1970).

login

Ultima data di autentificazione, in formato timestamp unix (numero di secondi dal 1/1/1970).

mail_disable

Stato di disabilitazione della mail dell'utente (0 = mail attiva, 1 = utente disiscritto, 2 = utente disabilitato da amministratore, 3 = utente disabilitato automaticamente)

audiences

Lista di identificativi di audience, separati da ",", alle quali l'utente appartiene.

Oltre a questi dati vengono riportati i valori dei campi profilo impostati.

Argomenti

string uid_mail (obbligatorio)

Puoi inserire sia l'identificativo numerico dell'utente, che il suo indirizzo email

array fields (facoltativo)

Array di campi da includere nella risposta (per un elenco dei campi vedi la chiamata newsletter.load)

voxmail.user.login

Come user.load ma fa una verifica sulla password e ritorna i dati utente solo se corretta
Attenzione: questo metodo non cambia il valore del campo dell'utente login

Argomenti

string uid_mail (obbligatorio)

Puoi inserire sia l'identificativo numerico dell'utente, che il suo indirizzo email

string pass (obbligatorio)

Password dell'utente da ottenere

array fields (facoltativo)

Array di campi da includere nella risposta (per un elenco dei campi vedi la chiamata newsletter.load)

voxmail.user.subscribe

Iscrive un nuovo utente nel sistema.
Questa chiamata deve essere eseguita in caso di iscrizione standard da parte dell'utente stesso. Per questo motivo è previsto che tra i dati obbligatori, oltre all'indirizzo e-mail, sia presente l'accettazione dei termini della privacy, attraverso l'impostazione del campo privacy al valore "1".
Inoltre è prevista la possibilità di passare l'indirizzo IP dal quale viene effettuata la richiesta (che verrà memorizzato tra i dati autentificativi dell'iscritto).
Dopo la chiamata a questo metodo, se non sono presenti errori (mail già presente o dati non validi), verrà inviata all'indirizzo e-mail la richiesta di conferma di iscrizione (opt-in).

Argomenti

struct data (obbligatorio)

Un array contenente tutti i dati dell'utente da memorizzare. Deve contenere almeno l'indirizzo e-mail (nel campo mail) e il campo privacy deve essere impostato a "1". Inoltre possono essere passati i valori dei campi profilo aggiuntivi da memorizzare

string ip (facoltativo)

Indirizzo IP da considerare come origine della chiamata (Attenzione: ogni abuso nell'uso di questo campo puo' comportare la disattivazione del servizio)

voxmail.user.unsubscribe

Effettua la disiscrizione di un utente dal sistema
Chiamare questo metodo equivale all'azione di disiscrizione che può fare un utente dal relativo link in una newsletter spedita (con la differenza che non è una disiscrizione collegata a una newsletter specifica).

Argomenti

string uid_mail (obbligatorio)

Puoi inserire sia l'identificativo numerico dell'utente, che il suo indirizzo email

string ip (facoltativo)

Indirizzo IP da considerare come origine della chiamata (Attenzione: ogni abuso nell'uso di questo campo puo' comportare la disattivazione del servizio)

voxmail.user.disable_mail

Disabilita le spedizioni verso un particolare utente.
Chiamando questo metodo l'utente verrà escluso da qualunque invio successivo, finchè non riabilitato.

Argomenti

string uid_mail (obbligatorio)

Puoi inserire sia l'identificativo numerico dell'utente, che il suo indirizzo email

string type (facoltativo)

La tipologia di disabilitazione da effettuare, può assumere il valore admin (valore standard, usato per le disabilitazioni amministrative) e system (per le disabilitazioni automatiche effettuate dal sistema). E' consigliabile usare sempre il valore "admin".

string ip (facoltativo)

Indirizzo IP da considerare come origine della chiamata (Attenzione: ogni abuso nell'uso di questo campo puo' comportare la disattivazione del servizio)

voxmail.user.enable_mail

Abilita le spedizioni verso un particolare utente precedentemente disabilitato.
E' consentito riabilitare solo utenti precedentemente disabilitati da amministratore o da sistema. Nel caso di utenti che hanno chiesto la disiscrizione è consentita la riabilitazione solo se esplicitamente richiesta dagli utenti.
(Attenzione: ogni abuso nell'uso di questo comando puo' comportare la disattivazione del servizio)

Argomenti

string uid_mail (obbligatorio)

Puoi inserire sia l'identificativo numerico dell'utente, che il suo indirizzo email

string ip (facoltativo)

Indirizzo IP da considerare come origine della chiamata (Attenzione: ogni abuso nell'uso di questo campo puo' comportare la disattivazione del servizio)

voxmail.user.create

Genera un nuovo utente (saltando la procedura standard di iscrizione)
La chiamata al metodo equivale alla creazione diretta di un utente da parte di un amministratore (o all'importazione di un utente), che quindi non gestisce la conferma (opt-in) dell'utente. (Lo stato di utente non confermato è comunque presente all'interno del sistema e potrebbe essere considerato in caso di abusi).
Per questo motivo la chiamata non prevede, a differenza del metodo user.subscribe, la conferma della privacy, la possibilità di inserire indirizzo IP e non invia alcuna mail all'utente creato.

Argomenti

struct data (obbligatorio)

Un array contenente tutti i dati dell'utente da memorizzare. Deve contenere almeno l'indirizzo e-mail (nel campo mail). Inoltre possono essere passati i valori dei campi profilo aggiuntivi da memorizzare

voxmail.user.update

Modifica i dati di utente.
Permette di cambiare i dati di iscrizione di un utente (indirizzo e-mail o i campi di profilo aggiuntivi) già presente nel sistema.
Il nome dei campi da usare è lo stesso ottenuto dalla chiamata user.load.
Oltre a questi campi è possibile usare alcuni campi aggiuntivi per specificare alcuni dati estesi:

audiences

Impostando un elenco di identificativi di audience separati da , è possibile cambiare tutti i gruppi ai quali l'utente appartiene (l'utente viene eliminato da tutti gli audience in cui è presente e viene aggiunto solo a quelli qui specificati).

+audiences

Permette di aggiungere l'utente agli audience specificati (tramite lista di identificativi separati da ","), mantenendo inalterati gli altri gruppi ai quali l'utente apparteneva in precedenza.

-audiences

Permette di rimuovere l'utente dagli audience specificati (tramite lista di identificativi separati da ","), mantenendo inalterati gli altri gruppi ai quali l'utente apparteneva in precedenza.

Argomenti

string uid_mail (obbligatorio)

Puoi inserire sia l'identificativo numerico dell'utente, che il suo indirizzo email

struct data (obbligatorio)

Un array contenente i dati da modificare. I dati non specificati non verranno alterati.

boolean create_if_not_exists (facoltativo)

Può assumere valore 0 o 1. Se assume valore 1 nel caso non venisse trovato l'utente da modificare ne verrà creato uno nuovo con i dati specificati. In questo caso i dati dovranno contenere tutti i campi necessari per la creazione.

voxmail.user.erase

Elimina un utente dal sistema.
Una volta usata questa operazione non sarà più possibile ottenere alcun dato dell'utente

Argomenti

string uid_mail (obbligatorio)

Puoi inserire sia l'identificativo numerico dell'utente, che il suo indirizzo email

voxmail.user.mass_update

Effettua una operazione massiva di modifica dei dati degli utenti.
Permette di effettuare una chiamata equivalente alla "user.update" specificando i dati di più utenti contemporaneamente.
Tramite il parametro create_if_not_exists è possibile specificare un intero set di utenti, aggiornando quelli già presenti nel sistema e creando gli altri, in modo da sincronizzare l'insieme utenti con una sorgente esterna.

Argomenti

struct data (obbligatorio)

Deve contenere un array, nel quale ogni elemento è a sua volta un array specificato con lo stesso formalismo usato per la chiamata a user.update

int create_if_not_exists (facoltativo)

Può assumere valore 0 o 1. Se assume valore 1 nel caso non venisse trovato l'utente da modificare ne verrà creato uno nuovo con i dati specificati. In questo caso i dati dovranno contenere tutti i campi necessari per la creazione.

voxmail.user.list

Riporta una lista di utenti registrati nel sistema, eventualmente filtrata da alcuni parametri di ricerca.

Argomenti

array filters (facoltativo)

(Parametro non supportato)

string order (facoltativo)

Permette di specificare l'ordine dei risultati. I valori utilizzabili sono 2, uid o mail, eventualmente seguiti dal tipo di ordinamento (asc per crescente, desc per decrescente).

int pageLength (facoltativo)

Per specificare un limite di lunghezza di una pagina di risultati.

int pageNo (facoltativo)

In caso di presenza dell'opzione pageLength, permette di individuare quale pagina ottenere (0 = prima pagina)

voxmail.user.profile_fields.list

Ottiene un elenco di campi profilo gestiti dal sistema
Il risultato è un array in cui ogni elemento è a sua volta un array con queste chiavi:

name

Nome del campo (usato nelle diverse operazioni di user.load, user.create ...)

title

Nome esteso del campo (mostrato nei moduli di registrazione e nel pannello utente)

description

Descrizione del campo

type

Tipologia (textfield, textarea, select...)

visibility

Visibilità (1 = campo privato, 2 = campo pubblico)

options

In caso la tipologia preveda una scelta tra vari valori (come nel caso di select) qui sono presenti questi valori

required

Indica se la compilazione del campo è obbligatoria (0|1)

register

Indica se il campo appare nel modulo di registrazione (o al contrario se appare solo nel pannello utente) (0|1)

voxmail.audience.reset

Svuota uno o più audience da tutti i suoi partecipanti

Argomenti

string aidlist (obbligatorio)

Un elenco separato da "," di identificativi univoci di audience (aid)

voxmail.audience.list

Riporta la lista completa di audience presenti nel sistema
Il risultato è un array, in cui ogni valore è un nuovo array che contiene le chiavi:

aid

Identificativo univoco dell'audience

caption

Nome descrittivo associato all'audience

handler*

Tipologia di audience (servicesubscription per i gruppi di utenti e query per le ricerche salvate)

Argomenti

array filters (facoltativo)

*.filters

voxmail.audience.create

Crea un nuovo audience con i dati specificati

Argomenti

struct data (obbligatorio)

Un array contenente tutti i dati dell'audience da generare. Deve contenere almeno il campo caption. Per l'elenco dei campi vedi audience.list.

voxmail.audience.delete

Elimina l'audience specificato

Argomenti

string aid (obbligatorio)

Identificativo univoco dell'audience