Mail portal API Documentazione (For Developers) ver.beta 1.2

Informazioni

Mail portal API è facile da utilizzare e da sfruttare. Meglio pero' spendere un po' di tempo e leggere la documentazione ;- )

Mail portal API admin

L'applicazione offre una serie di servizi per comunicare con Mail portal attraverso chiamate REST e standard Json. Usa una interfaccia semplice e funzionale che permette di vedere immediatamente i risultati prodotti dai servizi esposti e permette la gestione completa delle funzioni più comuni di Mail portal senza passare dall'interfaccia di gestione di quest'ultima.

Host & Server

Hai bisogno di un host e un server per poter effettuare le chiamate all'applicazione.

Creare delle richieste ai servizi esposti

Di seguito una tabella che riassume i valori da impostare nei metodi HTTP primari in combinazione con i campi->valori della struttura Json e gli URI delle risorse:
GET Determina la richiesta di ottenere informazioni sulle liste e sul singolo utente http://testmailportal.webfrontier.it/services/get/ {"TYPE": 'get',}
PUT Determina l' aggiornamento degli attributi del singolo utente in una determinata lista http://testmailportal.webfrontier.it/services/put/ {"TYPE": 'put',}
DELETE Determina l'annullamento della iscrizione di un utente in una determinata lista http://testmailportal.webfrontier.it/services/delete/ {"TYPE": 'delete',}
POST Determina la creazione di un nuovo utente in una singola lista http://testmailportal.webfrontier.it/services/post/ {"TYPE": 'post',}

Convalida della richiesta

Qualsiasi tipo di richiesta ai servizi esposti di Mail portal API, viene convalidata e salvata in un proprio database.
La prima convalida, viene effettuata sul mittente della richiesta che viene identificato tramite l'indirizzo IP e la combinazione dei campi-> valori seguenti:
PUBLIC_KEY alfanumerico {"PUBLIC_KEY": 'aaaaaBBB1234',}
PRIVATE_KEY alfanumerico {"PRIVATE_KEY": 'aaaaaBBB1234',}

Set Up

Adesso è possibile vedere un primo e semplice esempio di chiamata ad un servizio Mail portal API.
eseguiamo quindi questi semplici passi:
http://testmailportal.webfrontier.it/services/get/ {find only by mail} il nostro oggetto Json sarà cosi composto:
	{
		"TYPE": "get",
		"EMAIL": "marcello.gandola@gmail.com",
		"PUBLIC_KEY": "aaaaaBBB1234",
		"PRIVATE_KEY": "aaaaaBBB1234"
	}
				
La nostra richiesta produrrà quindi la seguente risposta.

Note

La richiesta è valida nei seguenti casi:
- Le Key pubbliche e private corrispondono e la richiesta arriva da un indirizzo IP noto
- Il Json della richiesta è valido.
- È rispettato la modalità case-sensitive di chiavi->valore
- La risposta potrebbe essere diversa poichè dipende dai tipi e dal numero di campi inseriti nella relativa lista

Ottenere informazioni (get)

Come abbiamo visto attraverso l'attibuto {"TYPE": 'get',} ed impostando come URI il percorso http://testmailportal.webfrontier.it/services/get/ è possibile ottenere informazioni di un singolo utente e le sue associazioni alle relative liste di cui è sottoscrittore. Lo stesso concetto è naturalmente replicabile per ottenere informazioni sulle liste.
Vediamo come fare per raggiungere questo obbiettivo.

Puntare all' url dell'Host

Il percorso a cui effettuare la richiesta sarà quindi:
http://testmailportal.webfrontier.it/services/get/
Il tipo di richiesta:
{"TYPE": 'get',}
Le credenziali di accesso
"PUBLIC_KEY": "aaaaaBBB1234",
"PRIVATE_KEY": "aaaaaBBB1234"

Per finire impostiamo ora l'attributo LIST come già visto precedentemente per l'attributo MAIL.
Ecco un esempio in cui chiediamo di ricevere tutte le liste.
http://testmailportal.webfrontier.it/services/get/ {find all list}
(Attenzione ricorda di inserire lo slash '/' alla fine dell'url)
	{
		"TYPE": "get",
		"LIST": "all",
		"PUBLIC_KEY": "aaaaaBBB1234",
		"PRIVATE_KEY": "aaaaaBBB1234"
	}
			
La nostra richiesta produrrà quindi la seguente risposta.

Note

Per brevità l'immagine rappresentante la risposta del servizio è stata tagliata.

Ottenere informazioni sulla singola lista


http://testmailportal.webfrontier.it/services/get/ {find single list}
	{
		"TYPE": "get",
		"LIST": "nd544zkfvr7cf",
		"PUBLIC_KEY": "aaaaaBBB1234",
		"PRIVATE_KEY": "aaaaaBBB1234"
	}
			

Risultato

Considerazioni

A questo punto è facile intuire che la combinazione lista - utente ci permette di ottenere nel metodo GET del servizio Mail portal API tutta una serie di informazioni che possiamo adattare alle nostre esigenze.
Vediamo degli esempi:

Ricerca per email in una singola lista


http://testmailportal.webfrontier.it/services/get/ {get user / find by mail} Use case: Sono noti l'indirizzo mail dell'utente e l'ID della lista
	{
		"TYPE": "get",
		"EMAIL": "marcello.gandola@gmail.com",
		"LIST": "eh339w9sdw9ba",
		"PUBLIC_KEY": "aaaaaBBB1234",
		"PRIVATE_KEY": "aaaaaBBB1234"
	}
Risultato

Ottenere un preciso oggetto


http://testmailportal.webfrontier.it/services/get/ {get user / list} Use case: Sono noti il SUBSCRIBER-UNIQUE-ID dell'utente e l'ID della lista
(Attenzione questo esempio che ci presenta il nuovo attibuto SUBSCRIBER-UNIQUE-ID sarà molto utile in seguito nel metodo PUT quando andremo ad aggiornare le informazioni dell'utente in una data lista)
	{
		"TYPE": "get",
		"SUBSCRIBER-UNIQUE-ID": "sm931qd3pkf6f",
		"EMAIL": "",
		"LIST": "bw723anjoo30a",
		"PUBLIC_KEY": "aaaaaBBB1234",
		"PRIVATE_KEY": "aaaaaBBB1234"
	}
Risultato

Aggiornare informazioni (put)

Come abbiamo visto precedentemente, l'aggiornamento delle informazioni relative ad utenti / liste segue le stesse regole di convalida e viene preceduta sempre da una chiamata di tipo GET a Mail portal API. Questo perchè non può essere noto il numero e il tipo dei custom-field che l'utente con credenziali opportune gestisce direttamente dall'interfaccia di Mail portal.

Impostazioni e set-up

Prima di eseguire ogni operazione di aggiornamento avremmo quindi bisogno di ottenere le informazioni contenute in mail portal relative ad un utente o ad una lista. Proseguiamo quindi con l'esempio finora visto e vediamo come aggiornare le informazioni dell'utente marcello.gandola@gmail.com relativamente alla lista 'lista test object way'
Sarà quindi necessario effettuare una chiamata all'indirizzo http://testmailportal.webfrontier.it/services/put/ed indicare l'attributo {"TYPE": "put",} assieme alle nostre PUBLIC_KEY e PRIVATE_KEY http://testmailportal.webfrontier.it/services/put/ {updateUser}
La nostra prima parte del file Json sarà quindi molto simile a quello già visto, tranne per il fatto che valorizziamo l'attributo TYPE con 'put'.
	{
		"TYPE": "put",
		"PUBLIC_KEY": "aaaaaBBB1234",
		"PRIVATE_KEY": "aaaaaBBB1234"
	}
				
Immaginiamo ora di voler aggiornare uno qualsiasi dei campi dell'oggetto che abbiamo ottenuto dal 'get'.
(rivediamo i campi già mostrati precedentemente)
Decidiamo di aggiornare i seguenti campi:
- "REGIONE"
- "PROVINCIA"
- "COMUNE"
NOTA Naturalmente questo concetto è valido per qualsiasi campo, compreso l'indirizzo e-mail TRANNE CHE per i campi "ID-LIST" e "subscriber_uid" che Mail portal tratta come campi univoci.
In Mail portal i custom-fields hanno un attributo booleano 'Required' nel caso il campo sia impostato a true (SI) il campo deve essere obbligatoriamente passato con il relativo valore. Vediamo quindi il caso in cui i campi sono tutti obbligatori. La nostra chiamata sarà:
	{
		"TYPE": "put",
		"LIST-UNIQUE-ID": "eh339w9sdw9ba",
		"SUBSCRIBER-UNIQUE-ID": "wh902hpyj5c73",
		"EMAIL": "marcello.gandola@gmail.com",
		"NOME": "Marcello",
		"MATRICOLA": "",
		"CELLULARE": 3289074781,
		"REGIONE": "Veneto",
		"PROVINCIA": "Venezia",
		"SETTOREAZIENDA": "media",
		"CONSULENTIPF": "Consulente indipendente",
		"PROFILOREGISTRAZIONEUTENTE": "Giornalista",
		"ISCRIZIONESALONE": "Iscritto al Salone 2012",
		"PARTECIPAZIONESALONE": "Partecipante al Salone 2014",
		"COMUNE": "Chioggia",
		"COGNOME": "Gandola",
		"PUBLIC_KEY": "aaaaaBBB1234",
		"PRIVATE_KEY": "aaaaaBBB1234"
	}
Considerazioni
Come è facile notare, non è importante che l'ordine dei campi sia rispettato.
La risposta del servizio in caso di esito positivo sarà il seguente.
Errori ed eccezioni
Mancanza di campi obbligatori
Si tenta di aggiornare l'id della lista e/o l'id della lista è errato. Si tenta di aggiornare l'id dell' utente e/o l'id dell' utente è errato.

Unsubscribe user (delete)

Questa sezione fornisce le informazioni per la disiscrizione di un utente ad una determinata lista.
Da notare che la disiscrizione di un utente da una lista NON vuol dire la sua cancellazione, ma semplicemente il passaggio di stato da sottoscrittore a NON sottoscrittore.

Impostazioni e set-up

Sarà quindi necessario effettuare una chiamata all'indirizzo http://testmailportal.webfrontier.it/services/delete/ ed indicare l'attributo {"TYPE": "delete",} assieme alle nostre PUBLIC_KEY e PRIVATE_KEY

Nota

DISISCRIVERE un utente, non comporta nessun tipo di invio di e-mail.Nessuna comunicazione verrà inviata all'utente da parte del servizio. La disiscrizione di un utente ad una lista può essere effettuata in 2 modi, sostanzialmente simili, indicandone il suo SUBSCRIBER-UNIQUE-ID oppure il suo indirizzo e-mail.
http://testmailportal.webfrontier.it/services/delete/ {unsubscribe user} - Use case SUBSCRIBER-UNIQUE-ID:
	{
		"TYPE": "delete",
		"LIST-UNIQUE-ID": "eh339w9sdw9ba",
		"SUBSCRIBER-UNIQUE-ID": "wh902hpyj5c73",
		"PUBLIC_KEY": "aaaaaBBB1234",
		"PRIVATE_KEY": "aaaaaBBB1234"
	}
				
- Use case EMAIL:
	{
		"TYPE": "delete",
		"LIST-UNIQUE-ID": "eh339w9sdw9ba",
		"EMAIL": "marcello.gandola@gmail.com",
		"PUBLIC_KEY": "aaaaaBBB1234",
		"PRIVATE_KEY": "aaaaaBBB1234"
	}
				
La risposta del servizio in caso di esito positivo sarà il seguente.

Errori ed eccezioni

La lista non è stata trovata o non è stata passata nell'oggetto Json. L' utente sottoscrittore non è stato trovato o non è stato passato nell'oggetto Json. NOTA questo messaggio sarà identico sia nel caso viene passato il parametro 'EMAIL' che nel caso venga passato il parametro 'SUBSCRIBER-UNIQUE-ID'.

Creazione utente / lista (post)

Questa sezione fornisce le informazioni per la iscrizione di un utente ad una determinata lista e/o la creazione di una nuova lista.

Impostazioni e set-up

Come abbiamo visto in precedenza sarà necessario impostare il percorso di invio della richiesta puntando alla cartella POST. Nel nostro esempio sarĂ  quindi: http://testmailportal.webfrontier.it/services/post/ e chiamare il metodo {"TYPE": 'post',}.
Vediamo come fare:
http://testmailportal.webfrontier.it/services/post/ {create user} - Use case ISCRIZIONE DI UN NUOVO UTENTE AD UNA LISTA NOTA.

	{
		"TYPE": "post",
		"LIST-UNIQUE-ID": "eh339w9sdw9ba",
		"ID": 123456,// campo obbligatorio
		"EMAIL": "mario.rossi@gmail.com",
		"FNAME": "Mario",
		"LNAME": "Rossi",
		"PUBLIC_KEY": "aaaaaBBB1234",
		"PRIVATE_KEY": "aaaaaBBB1234"
	}
				
Nota: Eventuali campi obbligatori devono essere valorizzati. Altri campi non obbligatori possono essere aggiornati in seguito.
La risposta del servizio in caso di esito positivo, sarà il seguente:

Errori ed eccezioni

- Use Case: UTENTE GIA' IN LISTA. - Use Case: LA LISTA NON ESISTE. - Use Case: CAMPO OBBLIGATORIO NON PASSATO

Creazione di una nuova lista


La creazione di una nuova lista richiede parametri finora non visti. Nei fatti una nuova lista per essere creata ha bisogno di conoscere da chi parte la mail (from_email) a chi indirizzare la risposta (reply_to) ed altri campi, alcuni di questi opzionali, che vediamo meglio in dettaglio.
http://testmailportal.webfrontier.it/services/post/ {create list} Il nostro Json sarà così composto:

	{	// required
		"TYPE":{
			"type": "post",
			"PUBLIC_KEY": "aaaaaBBB1234",
			"PRIVATE_KEY": "aaaaaBBB1234"
		},
		// required
		"general": {
			"name": "My list created from the API",
			"description": "This is a test list, created from the API."
		},
		// required
		"defaults": {
			"from_name": "John Doe",
			"from_email": "johndoe@doe.com",
			"reply_to": "johndoe@doe.com",
			"subject": "Hello!"
		},
		// optional
		"notifications": {
			"subscribe": "yes",
			"unsubscribe": "yes",
			"subscribe_to": "johndoe@doe.com",
			"unsubscribe_to": "johndoe@doe.com"
		},
		// optional, se non impostato verranno utilizzati i dati aziendali di default
		"company": {
			"name": "John Doe INC",
			"country": "United States",
			"zone": "New York",
			"address_1": "Some street address",
			"address_2": "",
			"zone_name": "",
			"city": "New York City",
			"zip_code": "10019"
		}
	}

				

La risposta del servizio in caso di esito positivo, sarà il seguente:

Errori ed eccezioni comuni

Di seguito vengono elencati gli errori e le eccezioni comuni a tutti i servizi.

Attributo TYPE non valido

	{
		"TYPE": "put",
		...
	}
				
Si stà tentando di inviare una richiesta di tipo 'put' ad un uri di altro tipo. es. http://testmailportal.webfrontier.it/services/get/

Json non valido

	{
		...
		EMAIL: "mario.rossi@gmail.com",
		...
	}
		
il campo deve essere racchiuso tra doppi apici.

PUBLIC_KEY E/O PRIVATE_KEY non valido

	{
		...
		"PUBLIC_KEY": "XXXXXXXXX",
		"PRIVATE_KEY": "XXXXXXXX"
		...
	}
	
Le chiavi pubbliche/private di accesso non sono state riconosciute.

Indirizzo IP non abilitato

Non hai trovato le tue risposte ?

Hai altre domande ?