System API - SqualoMail

L‘API di sistema è progettato per integrare la tua applicazione con SqualoMail.

Principi di base

L’API è disponibile su http://api.squalomail.com/v1/help
Per l’accesso è necessaria una password (api_key).
Tutte le funzionalità sono disponibili tramite il protocollo REST. La comunicazione può essere effettuata tramite formati JSON o XML.
Una dettagliata specificazione è disponibile su https://api.squalomail.com/v1/help

Operazioni disponibili

Tutte le funzioni richiedono sempre l’invio del parametro api_key! Perciò in seguito questo non verrà più ripetuto. Le funzioni disponibili sono:

1. 1. 1. create-list
    2. update-list
    3. get-lists
    4. get-lists-details
    5. create-newsletter
    6. create-newsletter-from-template
    7. create-recipient
    8. delete-newsletter
    9. delete-recipient
    10. delete-recipient-by-email
    11. delete-recipients-by-list
    12. delete-list
    13. get-app-id
    14. get-data
    15. get-recipients-with-custom-fields
    16. get-recipients-with-tags
    17. get-invalid-recipients
    18. get-subscribed-recipients
    19. get-unsubscribed-recipients
    20. subscribe-recipient
    21. subscribe-recipient-by-email
    22. unsubscribe-recipient
    23. unsubscribe-recipient-by-email
    24. send-newsletter
    25. update-newsletter
    26. update-recipient
    27. import-recipients-async
    28. grant-gdpr-consent
    29. grant-gdpr-consent-by-email
    30. revoke-gdpr-consent
    31. revoke-gdpr-consent-by-email
    32. cancel-sending-newsletter
    33. custom-event
    34. custom-event/order
    35. custom-event/abandoned-checkout

1. create-list

Funzione di invio: POST

Con questa funzione puoi creare una nuova lista di destinatari. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
name – il nome della lista
description – la descrizione della lista
color – il colore in hex della lista
ordering – il ordine della lista come viene visualizzata nel GUI – da 0 a 2147483647
published – la lista è pubblicata o no (boolean)
listTags – il tag della lista

Esempio:

{
    "apiKey": "String content",
    "name": "String content",
    "description": "String content",
    "color": "String content",
    "ordering": 2147483647,
    "published": true
    "listTags": ["Italia", "Slovenia", "Croazia"]
}

2. update-list

Funzione di invio: POST

Con questa funzione puoi aggiornare una lista esistente di destinatari. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
name – il nome della lista
description – la descrizione della lista
color – il colore in hex della lista
ordering – il ordine della lista come viene visualizzata nel GUI – da 0 a 2147483647
published – la lista è pubblicata o no (boolean)
listTags – il tag della lista

Esempio:

{
    "apiKey": "String content",
    "name": "String content",
    "description": "String content",
    "color": "String content",
    "ordering": 2147483647,
    "published": true
    "listTags": ["Italia", "Slovenia", "Croazia"]
}

3. get-lists

Funzione di invio: POST

Con questo metodo, è possibile ottenere tutte le informazioni disponibili, nel sistema SqualoMail, riguardo le liste dei destinatari. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
listIds – numeri ID delle liste: questo parametro è facoltativo. Se si omette il valore/lo si lascia in bianco, il sistema acquisirà tutti i numeri ID
listNames – nomi delle liste – questo parametro è facoltativo. Se si omette il valore/lo si lascia in bianco, il sistema acquisirà tutti i nomi degli elenchi
listTags: tag/categorie delle liste – questo parametro è facoltativo. Se si omette il valore/lo si lascia in bianco, il sistema acquisirà tutti i tag/categorie delle liste.

Esempio:

{
    "apiKey": "String content",
    "listIds": [1, 2, 3],
    "listNames": ["Nome1", "Nome2", "Nome3"],
    "listTags": ["Italia", "Slovenia", "Croatia"]
}

4. get-lists-details

Funzione di invio: POST

Con questo metodo, è possibile ottenere le informazioni dettagliate disponibili, nel sistema SqualoMail, riguardo le liste dei destinatari con il numero di destinatari iscritti, disiscritti e disabilitati. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
listIds – numeri ID delle liste: questo parametro è facoltativo. Se si omette il valore/lo si lascia in bianco, il sistema acquisirà tutti i numeri ID
listNames – nomi delle liste – questo parametro è facoltativo. Se si omette il valore/lo si lascia in bianco, il sistema acquisirà tutti i nomi degli elenchi
listTags: tag/categorie delle liste – questo parametro è facoltativo. Se si omette il valore/lo si lascia in bianco, il sistema acquisirà tutti i tag/categorie delle liste.
page: numero da 0 a n – se non impostato verrà utilizzato il valore predefinito di 0. Questo rappresenta quale pagina delle liste che dovrebbe essere “visualizzata”.
pageSize: numero da 1 a 100 – se non impostato verrà utilizzato il valore predefinito di 10. Questo rappresenta quante liste per pagina dovrebbero essere recuperate. Se sono impostate più di 100, ne verranno recuperate solo 100 (limite massimo).

Esempio:

{
    "apiKey": "String content",
    "listIds": [1, 2, 3],
    "listNames": ["Nome1", "Nome2", "Nome3"],
    "listTags": ["Italia", "Slovenia", "Croatia"]
    "page": 1
    "pageSize": 10
}

5. create-newsletter

Funzione di invio: POST

Con questa funzione puoi creare una nuova newsletter e decidere su quale lista verrà inviata. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
subject – Oggetto (Subject) della newsletter
body – testo della newsletter
altBody – versione testuale del contenuto della newsletter
fromEmail – indirizzo email del mittente (facoltativo, altrimenti viene configurato quello predefinito)
fromName – nome del mittente, come lo vede il destinatario (facoltativo, altrimenti viene configurato quello predefinito)
replyToEmail – indirizzo email per la risposta (facoltativo, altrimenti viene configurato quello predefinito)
replyToName – nome del mittente per la risposta, come lo vede il destinatario (facoltativo, altrimenti viene configurato quello predefinito)
language – lingua della newsletter. Puoi scegliere tra DE, EN, ES, FR, HR, IT e SL (facoltativo, predefinito è lo SL (sloveno))
listIds – ID numeri delle liste, alle quali verrà inviata la newsletter (l’invio viene fatto dopo con un’altra funzione). L’esempio del formato è il seguente: [4,6]. L’ID della lista lo trovi tramite queste istruzioni.
visible – se la newsletter è visibile ai destinatari (si possono iscrivere/disiscrivere da soli). I possibili valori sono true o false.
addUtm – se aggiungere i parametri UTM alla newsletter. I possibili valori sono true o false.
utmMedium – il valore del parametro UTM medium
utmSource – il valore del parametro UTM source
utmCampaign – il valore del parametro UTM campaign
utmId – il valore del parametro UTM id
utmTerm – il valore del parametro UTM term
utmContent – il valore del parametro UTM content

Esempio:

{
	"apiKey":"String content",
	"altBody":"String content",
	"body":"String content",
	"fromEmail":"String content",
	"fromName":"String content",
	"language":"String content",
	"listIds":[2147483647],
	"replyToEmail":"String content",
	"replyToName":"String content",
	"subject":"String content",
	"visible":true,
        "utmMedium": "String content",
        "utmSource": "String content", 
        "utmCampaign": "String content",
        "utmId": "String content",
        "utmTerm": "String content",
        "utmContent": "String content",
        "addUtm": true,
}

6. create-newsletter-from-template

Metodo di invio: POST

Questa funzione ti permette di creare una nuova newsletter usando una già esistente. La bozza per il template può essere qualunque newsletter già esistente.

A disposizione hai i seguenti parametri:

apiKey – parola chiave per accedere all’API
subject – Oggetto (Subject) della newsletter
fromEmail – indirizzo email del mittente (facoltativo, altrimenti viene configurato quello predefinito)
fromName – nome del mittente, come lo vede il destinatario (facoltativo, altrimenti viene configurato quello predefinito)
replyToEmail – indirizzo email per la risposta (facoltativo, altrimenti viene configurato quello predefinito)
replyToName – nome del mittente per la risposta, come lo vede il destinatario (facoltativo, altrimenti viene configurato quello predefinito)
language – lingua della newsletter. Puoi scegliere tra DE, EN, ES, FR, HR, IT e SL (facoltativo, predefinito è lo SL (sloveno))
listIds – ID numeri delle liste, alle quali verrà inviata la newsletter (l’invio viene fatto dopo con un’altra funzione). L’esempio del formato è il seguente: [4,6]. L’ID della lista lo trovi tramite queste istruzioni.
addUtm – se aggiungere i parametri UTM alla newsletter. I possibili valori sono true o false.
utmMedium – il valore del parametro UTM medium
utmSource – il valore del parametro UTM source
utmCampaign – il valore del parametro UTM campaign
utmId – il valore del parametro UTM id
utmTerm – il valore del parametro UTM term
utmContent – il valore del parametro UTM content
templateId – ID numero della newsletter già esistente, che verrà usata come base per la creazione delle nuova.
templateCustomAttributes – Attributi su misura, che vengono inseriti nel corpo (body) della newsletter già esistente ovvero nella bozza dalla quale viene creata la nuova newsletter.

TemplateCustomAtrributes

Questo insieme di parametri ti permette di preparare in anticipo la bozza nel sistema SqualoMail e di inserire una tag specifica (template tag), che con la chiamata di questa funzione verrà sostituita con un valore concreto.

Lo scenario, con il quale questa funzionalità può essere utilizzata, è quando desideri usare il Drag&Drop editore di SqualoMail per preparare la forma della newsletter e poi automatizzare l’inserimento del contenuto.

Il template tag viene segnato con delle doppie parentesi graffe – {{template_tag}}. Hai a disposizione due template tag basilari:

texts – con il suo aiuto puoi inserire ad un determinata locazione un tuo testo desiderata o HTML.
images – con il suo aiuto puoi sostituire le immagine selezionate nella bozza con le immagini desiderate della newsletter finale.

Texts

Definisci i testi come una tabella (array) di identificatori desiderati (p.es.: heading, subheading, ecc.) e valori, che verranno inseriti. I nomi degli identificatori sono a tua scelta – l’importante è solamente essere consistenti nella creazione della bozza di base e poi anche dalla chiamata di questa funzione.

Esempio:

Nel Drag&Drop editore inserisci il testo sottostante:

Dopo la chiamata con i parametri che seguono:

{
    "templateCustomAttributes": {
        "texts": [{
                "itemId": "column1-heading",
                "itemContent": {
                    "value": "NEW items for better zzzzzzs"
                }
            },
            {
                "itemId": "column1-subheading",
                "itemContent": {
                    "url": "http://www.google.com",
                    "value": "Everybody deserves a good night sleep :)"
                }
            },
            {
                "itemId": "column1-text",
                "itemContent": {
                    "value": "Fusce at tristique urna, sit amet elementum odio.    Nullam vulputate at felis ut eleifend. Pellentesque euismod libero diam, viverra placerat risus vestibulum non. Praesent at rutrum odio. Quisque vel suscipit sem."
                }
            }
        ]
    }
}

e riceverai:

Qui c’è da sottolineare che se desideri stilizzare i link, non è possibile farlo nel Drag&Drop editore, ma lo devi fare senza aggiungere il parametro “url”, quindi aggiungi solamente <a style=”…

Images

Con l’attributo template “images” puoi aggiungere nelle locazioni selezionate della bozza di base le immagini dall’URL.

“Seleziona” le immagini nel Drag&Drop editore, scegliendo l’immagine da /images/SqualoMail-templates/_placeholders/.

All’interno della cartella troverai delle sottocartelle segnate da 0 a 9. Questi numeri rappresentano il numero ID dell’immagine e ognuno di questi numeri rappresenta una immagine nella bozza. Questo significa, che devi per ogni locazione selezionata scegliere l’immagine dall’altra sottocartella.

In ogni sottocartella hai a disposizione più dimensioni di immagini, che si differenziano a seconda della proporzione dei lati (aspect ratio). Devi scegliere l’immagine, che ha per te la corretta proporzione dei lati, dopodiché come fatto abitualmente, adegua le sue dimensioni con il cursore del Drag&Drop editore.

Le dimensioni dell’immagine che inserirai non è così importate, infatti le dimensioni verranno adeguate a quello che hai impostato con il cursore. Più importate è l’inserimento dell’immagine con la giusta proporzione dei lati, altrimenti saranno allungate.

All’immagine puoi anche aggiungere un link con il parametro “url”.

Esempio:

1. Bozza

2. La chiamata della funzione ha i seguenti parametri:

{
	"templateCustomAttributes": {
		"images": [{
				"itemId": "0",
				"itemContent": {
					"url": "https://www.google.com",
					"value": "https://11.squalomail.net/images/image-3-column-placement-1-5x4.png"
				}
			},
			{
				"itemId": "1",
				"itemContent": {
					"url": "https://www.yahoo.com",
					"value": "https://11.squalomail.net/images/image-3-column-placement-2-5x4.png"
				}
			},
			{
				"itemId": "2",
				"itemContent": {
					"url": "https://www.apple.com",
					"value": "https://11.squalomail.net/images/image-3-column-placement-3-5x4.png"
				}
			}
		]
	}
}

3. Risultato:

Un esempio di tutte le possibilità che offre la funzione

{
    "apiKey": "String content",
    "fromEmail": "String content",
    "fromName": "String content",
    "language": "String content",
    "listIds": [2147483647],
    "published": true,
    "replyToEmail": "String content",
    "replyToName": "String content",
    "subject": "String content",
    "visible": true,
    "utmMedium": "String content",
    "utmSource": "String content", 
    "utmCampaign": "String content",
    "utmId": "String content",
    "utmTerm": "String content",
    "utmContent": "String content",
    "addUtm": true,
    "templateId": 2147483647,
    "templateCustomAttributes": {
        "images": [{
            "itemId": "String content",
            "itemContent": {
                "url": "String content",
                "value": "String content"
            }
        }],
        "texts": [{
            "itemId": "String content",
            "itemContent": {
                "url": "String content",
                "value": "String content"
            }
        }]
    }
}

7. create-recipient

Metodo di invio: POST

Con questa funzione crei un nuovo destinatario e allo stesso tempo lo aggiungi su nessuna o più liste. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
email – indirizzo email del destinatario
name – nome del destinatario
surname – cognome del destinatario
gender – sesso del destinatario
phone – numero di telefono del destinatario
listIds – ID numeri delle liste, alle quali il destinatario sarà iscritto. L’esempio del formato è il seguente: [4,6]. L’ID della lista lo trovi tramite queste istruzioni
html – se il destinatario accetta i messaggi in formato HTML oppure solo in quello testuale
confirmed – se il destinatario consente di accettare i messaggi (i messaggi saranno comunque inviati)
enabled – se il destinatario è abilitato (i destinatari non abilitati non esistono)
accept – se il destinatario accetta i messaggi
gdprCanSend – il consenso per l’invio
gdprCanTrack – il consenso per la profilazione
ip – il indirizzo IP dal quale il destinatario e stato creato
customAttributes – lista delle coppie di chiavi, valori (key, value) per i campi personalizzati del destinatario su misura. Per il nome del campo usa lo spazio »NOME DEL CAMPO PERSONALIZZATO«, che è disponibile tramite l’interfaccia utente grafica.

Esempio:

{
	"apiKey":"String content",
	"accept":true,
	"confirmed":true,
	"customAttributes":[
		{
		"name":"firstname",
		"value":"John"
		},
		{
		"name":"lastname",
		"value":"Smith"
		}
	],
	"email":"String content",
	"enabled":true,
	"html":true,
	"listIds":[2147483647],
	"name":"String content"
        "surname": "String content",
        "gender": "null | male | female | other",
        "phone": "+39l0481980021",
        "gdprCanSend": true,
        "gdprCanTrack": true,
        "ip": "123.123.123.123"
}

8. delete-newsletter

Funzione di invio: GET

Con questa funzione puoi cancellare la newsletter. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
newsletterId – ID numero della newsletter, che desideri cancellare

Esempio:

{
	"apiKey":"String content",
	"newsletterId":2147483647
}

9. delete-recipient

Funzione di invio: POST

Con questa funzione puoi cancellare il destinatario, in base al suo ID. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
recipientId – ID numero del destinatario, che desideri cancellare

Esempio:

{
	"apiKey":"String content",
	"recipientId":2147483647
}

10. delete-recipient-by-email

Funzione di invio: GET – POST

Con questa funzione puoi cancellare il destinatario, in base alla sua email. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
email – email del destinatario, che desideri cancellare

Esempio:

{
	"apiKey": "String content",
	"email": "String content"
}

11. delete-recipients-by-list

Funzione di invio: GET – POST

Con questa funzione puoi cancellare il destinatario, in base alla lista a cui è iscritto. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
listId – l’ID della lista, in cui è iscritto il destinatario che vuoi cancellare
deleteIfOnMUltipleLists – valore true/false, scegli se eliminare il destinatario se iscritto a più liste
deleteList – valore true/false, scegli se eliminare la lista a cui il destinatario è iscritto

Esempio:

{
	"apiKey": "String content",
	"listId": 123,
        "deleteIfOnMUltipleLists": true,
        "deleteList": true,
}

12. delete-list

Funzione di invio: GET

Con questa funzione puoi cancellare la lista. La funzione accetta solo un parametro:

apiKey – parola chiave per accedere all’API
listId – ID della lista, che desideri cancellare

Esempio:

{
    "apiKey":"String content",
    "listId":25
}

13. get-app-id

Funzione di invio: GET

Con questa funzione puoi ottenere l’id della tua applicazione squalomail. La funzione accetta solo un parametro:

apiKey – parola chiave per accedere all’API

Esempio:

{
    "apiKey":"String content",
}

14. get-data

Funzione di invio: GET oppure POST

Con questa funzione puoi ottenere tutti i dati, che sono disponibili nel sistema SqualoMail. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
entity – segna l’entità, che definirà il tipo di elemento, che desideri ottenere. Hai a disposizione le entità Field, History, List, ListMail, ListSub, Mail, Recipient, Stats, Url, UrlClick, UserStats. Le informazioni dettagliate le trovi di sotto.
filter – con questo parametro definisci quali entità (a seconda dei campi personalizzati), desideri ottenere.

Esempio:

http://api.squalomail.com/v1/get-data?apiKey={APIKEY}&entity=Recipient&filter=email.Endswith(%22gmail.com%22)

In seguito presenteremo le entità che sono disponibili, quali campi personalizzati hanno e quali filtri puoi usare.

ENTITÀ E CAMPI PERSONALIZZATI
FILTRI

ENTITÀ E CAMPI PERSONALIZZATI

Qui sono elencate tutte le entità e i loro campi personalizzati, che vengono usati quando costruisci un filtro per la funzione get-data.

Field

Questa entità rappresenta i campi personalizzati di destinatario su misura di SqualoMail (come sono nominati in GUI). Questa entità supporta i seguenti campi personalizzati:

fieldid – ID numero del campo personalizzato su misura
fieldname – tag del campo personalizzato (un bel nome per gli utenti)
namekey – nome del campo personalizzato (sistematico, senza spazi)
type – il tipo può essere text, checkbox, radio o textarea
value – valore predefinito del campo personalizzato su misura
published – se il campo personalizzato è disponibile per l’uso.
ordering – l’ordine in confronto agli altri – numero naturale

History

Le entità di questo tipo sono gli eventi, che hanno fatto i destinatari nel sistema SqualoMail. Per esempio abbiamo i click sui collegamenti, le email aperte, la cancellazione, l’aggiunta alla lista ecc. I parametri disponibili sono:

subid – ID numero del destinatario
date – data, quando è avvenuto l’evento nel fromato UNIX Timestamp
action – l’azione, che è avvenuta

List

L’entità list rappresenta la Lista. Disponibili sono i seguenti campi personalizzati:

listid – ID numero della lista
name – nome della lista
category – nome della categoria della lista
color – il colore in GUI
visible – se la lista è visibile ai destinatari.
alias – il valore del parametro Google analytics utm_campaign

Mail

Questa entità rappresenta la newsletter. Disponibili sono i seguenti campi personalizzati:

mailid – ID numero della newsletter
subject – oggetto (subject) della newsletter
body – contenuto della newsletter
altbody – versione testuale del contenuto
published – “0” significa, che non è pubblicato, “1”, che è pubblicato (visibile ai destinatari), “2”, che è in lista d’attesa per l’invio
senddate – data di invio nel formato UNIX Timestamp
created – data, quando è stata creata la newsletter nel formato UNIX Timestamp
fromemail – indirizzo email del mittente. Se è vuoto verrà usato quello predefinito.
fromname – nome del mittente. Se è vuoto verrà usato quello predefinito.
replytoemail – indirizzo email per la risposta. Se è vuoto verrà usato quello predefinito.
replytoname – nome per la risposta, visibile al destinatario. Se è vuoto verrà usato quello predefinito.
language – lingua della newsletter; può essere uno tra de, en, es, fr, hr, it oppure sl.

Recipient

Questa entità rappresenta il destinatario. Questa funzione permette la ricerca tramite i campi personalizzati del destinatario su misura. Disponibili sono i seguenti campi personalizzati:

subid – ID numero del destinatario
email – indirizzo email del destinatario
name – nome del destinatario
enabled – se il destinatario è abilitato (se probabilmente non esiste)
ip – indirizzo IP del destinatario
html – se il destinatario accetta i messaggi in formato HTML
accept – se il destinatario accetta i messaggi (non ha cancellato l’iscrizione)
created – data, quando è stato creato il destinatario nel formato UNIX Timestamp
confirmed – se il destinatario ha confermato l’iscrizione
confirmed_date – data, quando il destinatario ha confermato l’iscrizione nel formato UNIX Timestamp
lastopen_date – data, quando il destinatario ha aperto l’ultima volta qualche newsletter nel formato UNIX Timestamp
lastclick_date – data, quando il destinatario ha cliccato l’ultima volta su qualche link nella newsletter nel formato UNIX Timestamp
lastsent_date – data, quando è stata inviata qualche newsletter nel formato UNIX Timestamp.

ListMail

Entità di collegamento tra le entità List e Mail per la realizzazione del rapporto many-to-many. Disponibili sono i seguenti campi personalizzati:

listid – ID numero della lista
mailid – ID numero della newsletter

ListSub

Entità di collegamento tra le entità List e Recipient per la realizzazione del rapporto many-to-many. Disponibili sono i seguenti campi personalizzati:

listid – ID numero della lista
subid – ID numero del destinatario
subdate – data, quando il destinatario si è iscritto alla lista nel formato UNIX Timestamp
unsubdate – data, quando il destinatario ha cancellato l’iscrizione dalla lista nel formato UNIX Timestamp
status – “1” significa iscritto, “-1” significa disiscritto

Stats

L’entità Stats rappresenta la statistica della newsletter individuale. I campi personalizzati disponibili sono:

mailid – ID numero di newsletter
senthtml – numero di messaggi inviati nel formato HTML
senttext – numero di messaggi inviati nel formato testuale
senddate – data di invio nel formato UNIX Timestamp
openunique – numero di aperture mail univoche (se un destinatario ha aperto un messaggio più volte, questa azione verrà annotata solo una volta)
opentotal – numero di messaggi aperti (se il destinatario ha aperto lo stesso messaggio più volte, questa azione verrà annotata più volte)
cliclunique – numero dei click unici (se un destinatario ha cliccato su uno stesso link più volte, questa azione verrà annotata solo una volta)
clicktotal – numero di tutti i click (se il destinatario ha cliccato su uno stesso link più volte, l’azione verrà anche annotata più volte)
bounceunique – numero di rimbalzi (hard + soft bounces)
fail – numero di messaggi non consegnati
unsub – numero di cancellazioni di iscrizione
forward – numero di messaggi inoltrati

UserStats

Questa entità rappresenta i dati statistici di ogni utente a seconda della newsletter. Disponibili sono i seguenti campi personalizzati:

subid – ID numero del destinatario
mailid – ID numero della newsletter
open – se il destinatario ha aperto la newsletter
opendate – quando il destinatario ha aperto la newsletter
bounce – se il messaggio è stato respinto
fail – se l’invio del messaggio non è riuscito
browser – quale browser usa il destinatario (a disposizione solamente se il destinatario ha aperto il messaggio con: firefox, chorme, msie, …)
browser_version – la versione del browser (a disposizione solamente se il destinatario ha aperto il messaggio)
is_mobile – se il destinatario ha aperto il messaggio con un dispositivo mobile
mobile_os – con quale sistema operativo il destinatario ha aperto il messaggio
user_agent – informazioni sul browser del destinatario

UrlClick

Questa entità rappresenta il click del destinatario su un link. Ogni link ha un suo numero ID, dove il suo valore è salvato come un’entità URL (descrizione di sotto). I campi personalizzati disponibili sono:

mailid – ID numero della newsletter
subid – ID numero del destinatario
urlid – ID numero del link
click – numero dei click del destinatario su un link
date – data, quando è avvenuto l’ultimo klick
ip – indirizzo IP da dove è avvenuto l’ultimo klick

Url

Questa entità rappresenta il collegamento nella newsletter. Ogni collegamento in ogni newsletter è un’entità separata, anche se il fine del collegamento è lo stesso. Disponibili sono i seguenti campi personalizzati:

urlid – ID numero del link
name – nome del link
url – il fine del link

FILTRI

I filtri vengono creati all’interno del parametro filter.

Record

Il filtro viene creato iscrivendo il nome, l’operation ed il valore. Per i string, i valori devono essere annotati con le virgolette, mentre i numeri no.

Esempio:

email=="test@gmail.com"
created>1451606400

Operations

Confronto

== – confronto, se il valore corrisponde esattamente
>=
<=
>
<
!=

Operations logici

I filtri sono costituiti dalle condizioni, che si possono collegare tra loro con uno degli operation:

&& – logico E
|| – logico O

Esempio:

created>1451606400&&created<1454284800

Funzioni

Per i campi personalizzati, che sono di tipo string, hai a disposizione più funzioni:

Startwith(“str”) – il valore inizia con str
Endswith(“str”) – il valore termina con str

Nota: La funzione not equals può essere fatta con la negazione di Equals.

Esempio:

email.Endswith("gmail.com")

Negazione

Puoi negare il filtro con l’uso dell’operation ! (prima del nome del campo personalizzato).

Esempio:

!email.Endswith('gmail.com')

Esempio dell’intero request

Il filtro deve essere sempre codificato in URL.

Esempio:

https://api.squalomail.com/v1/get-data?apiKey=[api_key]&entity=recipient&filter=created%3E1451606400%26%26created%3C1454284800

Note

La funzione get-data non permette il filtraggio dei campi personalizzati del destinatario fatti su misura.

15. get-recipients-with-custom-fields

Funzione di invio: POST

Con questa funzione puoi ottenere tutti i destinatari che sono disponibili nel sistema SqualoMail e i suoi dati, inclusi i campi su misura. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
filter – con questo parametro definisci sulla base di quale valore desideri filtrare i destinatari come: subid, email, name, surname
filterCustomFields – è un array di oggetti con cui scegliere in base a quali campi su misura desideri filtrare i contatti. Ogni oggetto all’interno dell’array filterCustomFields ha le seguenti proprietà:
- fieldName – Il nome del campo su misura per il quale vuoi filtrare,
- value – il valore che stai cercando. Questo valore deve essere sempre una stringa
- operator – l’operatore con cui comparare campo e valore. Le opzioni valide sono: “=”, “!=”, “>”, “>=”, “<“, “<=”, “like”, “not like”

Nota: L’operatore like cercherà parte della stringa – se si cerca il testo “te” restituirà il destinatario che ha valore, ad esempio, “testo” nel campo su misura scelto

Esempio:

{
    "apiKey":"String content",
    "filter":"subid:12534",
    "filterCustomFields": [
         {
              "fieldName": "Field-1"
              "value": "Ye"
              "operator": "like"
         },
         {
              "fieldName": "Field-2"
              "value": "15"
              "operator": ">="
         },
     ]
}

16. get-recipients-with-tags

Funzione di invio: GET o POST

Con questa funzione puoi ottenere tutti i destinatari che sono disponibili nel sistema SqualoMail filtrati per tag. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
tags– è un array di oggetti con cui scegliere in base a quali tags desideri filtrare i contatti.

Esempio:

{
    "apiKey":"String content",
    "tags": ["Tag 1"]
}

17. get-invalid-recipients

Funzione di invio: GET

Con questa funzione ottieni tutti i destinatari che non sono abilitati. Di solito, la ragione è un indirizzo email non valido o non attivo. Questa funzione non ha nessun parametro speciale, tranne l’autenticazione:

apiKey – parola chiave per accedere all’API

Esempio:

{
	"apiKey":"String content",
}

18. get-subscribed-recipients

Funzione di invio: GET

Questa funzione restituisce tutti i destinatari, che sono iscritti ad una lista. Questo non vale per i destinatari non iscritti, comprende però quelli non abilitati (enabled=0). Disponibili sono i seguenti campi personalizzati:

apiKey – parola chiave per accedere all’API
listId – ID numero della lista, per la quale desideri ottenere i destinatari iscritti.

Esempio:

{
	"apiKey":"String content",
	"listId":2147483647
}

19. get-unsubscribed-recipients

Funzione di invio: GET

Questa funzione restituisce tutti i destinatari, che hanno cancellato l’iscrizione da un lista. Questi destinatari sono quelli che hanno cancellato l’iscrizione, e non quelli che non erano mai iscritti ad una lista. Il risultato comprende anche i destinatari non abilitati (enabled=0). Il parametro disponibile è solo uno:

apiKey – parola chiave per accedere all’API
listId – ID numero della lista, per la quale desideri ottenere i destinatari iscritti

Esempio:

{
	"apiKey":"String content",
	"listId":2147483647
}

20. subscribe-recipient

Funzione di invio: GET – POST

Questa funzione permette di iscrivere un destinatario a una o piu liste. I campi da inserire sono:

apiKey – parola chiave per accedere all’API
recipientId– L’id del destinatario da iscrivere alla/e lista/e.
listIds – L’id della/e lista/e a cui iscrivere il destinatario.
accept – Parametro facoltativo. Imposta il valore “Accetta messaggi” per il destinatario.

Esempio:

{
	"apiKey":"String content",
	"recipientId":2147483647,
        "listIds":[5],
        "accept":1
}

21. subscribe-recipient-by-email

Funzione di invio: GET – POST

Questa funzione permette di iscrivere un destinatario a una o piu liste, in base alla sua email. I campi da inserire sono:

apiKey – parola chiave per accedere all’API
email– L’indirizzo email del destinatario
listIds – L’id della/e lista/e a cui iscrivere il destinatario.
accept – Parametro facoltativo. Imposta il valore “Accetta messaggi” per il destinatario.

Esempio:

{
	"apiKey":"String content",
	"email":"info@email.com",
        "listIds":[5],
        "accept":1
}

22. unsubscribe-recipient

Funzione di invio: GET – POST

Questa funzione permette di disiscrivere un destinatario a una o piu liste. I campi da inserire sono:

apiKey – parola chiave per accedere all’API
recipientId– L’id del destinatario da disiscrivere alla/e lista/e.
listIds – L’id della/e lista/e a cui iscrivere il destinatario.
Accept – Parametro facoltativo. Imposta il valore “Accetta messaggi” per il destinatario.

Esempio:

{
	"apiKey":"String content",
	"recipientId":2147483647,
        "listIds":[5],
        "accept":0
}

23. unsubscribe-recipient-by-email

Funzione di invio: GET – POST

Questa funzione permette di disiscrivere un destinatario a una o piu liste, in base alla sua email. I campi da inserire sono:

apiKey – parola chiave per accedere all’API
email– L’indirizzo email del destinatario
listIds – L’id della/e lista/e a cui iscrivere il destinatario.
Accept – Parametro facoltativo. Imposta il valore “Accetta messaggi” per il destinatario.

Esempio:

{
	"apiKey":"String content",
	"email":"info@email.com",
        "listIds":[5],
        "accept":0
}

24. send-newsletter

Funzione di invio: GET

Impostazione di invio di una newsletter ad un determinato tempo. A quali liste verrà inviata, lo puoi impostare durante la creazione della newsletter (create-newsletter) o con la funzione update-newsletter. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
newsletterId – ID numero della newsletter, che desideri inviare
sendDate – data dell’invio nel formato UNIX Timestamp

Esempio:

{
	"apiKey":"String content",
	"newsletterId":2147483647,
	"sendDate":2147483647
 }

25. update-newsletter

Funzione di invio: POST

Con questa funzione puoi sostituire i campi personalizzati di una newsletter. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
id – ID numero della newsletter, alla quale desideri sostituire i campi personalizzati
subject – oggetto (Subject) della newsletter
body – testo della newsletter
altBody – versione testuale del contenuto della newsletter
fromEmail – indirizzo email del mittente (facoltativo, altrimenti viene configurato quello predefinito)
fromName – nome del mittente, come lo vede il destinatario (facoltativo, altrimenti viene configurato quello predefinito)
replyToEmail – indirizzo email per la risposta (facoltativo, altrimenti viene configurato quello predefinito)
replyToName – nome del mittente per la risposta, come lo vede il destinatario (facoltativo, altrimenti viene configurato quello predefinito)
language – lingua della newsletter. Puoi scegliere tra DE, EN, ES, FR, HR, IT e SL (facoltativo, predefinito è lo SL (sloveno))
listIds – ID numeri delle liste, alle quali verrà inviata la newsletter (l’invio viene fatto dopo con un’altra funzione). L’esempio del formato è il seguente: [4,6]. L’ID della lista lo trovi tramite queste istruzioni.
visible – se la newsletter è visibile ai destinatari (si possono iscrivere/disiscrivere da soli). I possibili valori sono true o false.
addUtm – se aggiungere i parametri UTM alla newsletter. I possibili valori sono true o false.
utmMedium – il valore del parametro UTM medium
utmSource – il valore del parametro UTM source
utmCampaign – il valore del parametro UTM campaign
utmId – il valore del parametro UTM id
utmTerm – il valore del parametro UTM term
utmContent – il valore del parametro UTM content

Esempio:

{
	"apiKey":"String content",
	"id":2147483647,
	"altBody":"String content",
	"body":"String content",
	"fromEmail":"String content",
	"fromName":"String content",
	"language":"String content",
	"listIds":[2147483647],
	"replyToEmail":"String content",
	"replyToName":"String content",
	"subject":"String content",
	"visible":true,
        "utmMedium": "String content",
        "utmSource": "String content", 
        "utmCampaign": "String content",
        "utmId": "String content",
        "utmTerm": "String content",
        "utmContent": "String content",
        "addUtm": true
}

26. update-recipient

Funzione di invio: POST

Con questa funzione puoi i campi di un destinatario esistente. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
id – ID numero della newsletter, alla quale desideri sostituire i campi personalizzati
email – indirizzo email del destinatario
name – nome del destinatario
surname – cognome del destinatario
gender – sesso del destinatario
phone – numero di telefono del destinatario
listIds – ID numero delle liste, alle quali il destinatario verrà iscritto. L’esempio del formato è il seguente [4,6]. L’ID della lista lo trovi con queste istruzioni. Se il destinatario era già prima iscritto su altre liste, le vecchie iscrizioni si cancelleranno in si sostituiranno con quelle nuove.
html – se il destinatario accetta i messaggi in formato HTML oppure solo in quello testuale.
confirmed – se il destinatario consente di accettare i messaggi (i messaggi saranno comunque inviati).
enabled – se il destinatario è abilitato (i destinatari non abilitati non esistono)
accept – se il destinatario accetta i messaggi
customAttributes – lista delle coppie di chiavi, valori (key, value) per i campi personalizzati del destinatario su misura. Per il nome del campo usa lo spazio »nome del campo personalizzato«, che è disponibile tramite l’interfaccia utente grafica.

Esempio:

{
	"apiKey":"String content",
	"id":2147483647,
	"accept":true,
	"confirmed":true,
	"customAttributes":[
		{
		"name":"firstname",
		"value":"John"
		},
		{
		"name":"lastname",
		"value":"Smith"
		}
	],
	"email":"String content",
	"enabled":true,
	"html":true,
	"listIds":[2147483647],
	"name":"String content",
        "surname": "String content",
        "gender": "null | male | female | other",
        "phone": "+39l0481980021",
        "gdprCanSend": true,
        "gdprCanTrack": true,
        "ip": "123.123.123.123"
}

27. import-recipients-async

Funzione di invio: POST

Con questa funzione puoi importare un file di destinatari in modo asincro. La funzione accetta i seguenti parametri:

autogenerateNames– questo parametro rileva automaticamente, al momento dell’importazione, il nome e il cognome dei destinatari, qualora presente nell’indirizzo email dello stesso, andando a compilare i corrispettivi campi su misura NOME e COGNOME all’interno dell’applicazione SqualoMail
listIdsToAdd – ID delle liste a cui iscrivere i destinatari
overwriteData – questo parametro permette di sovrascrivere i dati dei destinatari che al momento dell’importazine sono già presenti nell’applicazione. I valori per overwriteData sono:
- 1 significa, che trascriverà tutti i campi.
- 2 significa che trascriverà solo i campi vuoti (null oppure “”)
- 3 significa che aggiungerà solamente i destinatari non esistenti (quindi solo INSERT). I destinatari esistenti non verranno modificati.
clearPreviousListIds – ID delle liste a cui i destinatari sono già iscritti e da cui desideri disiscriverli di modo che restino iscirtti solo alle liste indicate dal parametro listIdsToAdd
importAsDisabled – questo parametro permette di importare i destinatari come DISABILITATI
base64EncodedFile– file che desideri importare.

Esempio:

{
"autogenerateNames":true,
"listIdsToAdd":[13],
"overwriteData":2,
"clearPreviousListIds":true,
"importAsDisabled":false,
"base64EncodedFile":"Base64 encoded file",
}

28 grant-gdpr-consent

Funzione di invio: GET – POST

Con questa funzione puoi convalidare il consenso GDPR alla ricezione delle newsletter per un destinatario, in base al suo ID. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
recipientId – ID del destinatario
consentTitle – l’attributo di conferma/revoca del consenso GDPR
language – la lingua della normativa GDPR a cui da il consenso

Esempio:

{
"apikey":"String content",
"recipientId": 2147483647,
"consentTitle": "gdpr_can_send",
"language": "it",
}

29. grant-gdpr-consent-by-email

Funzione di invio: GET – POST

Con questa funzione puoi convalidare il consenso GDPR alla ricezione delle newsletter per un destinatario, in base al suo indirizzo email. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
email – email del destinatario
consentTitle – l’attributo di conferma/revoca del consenso GDPR
language – la lingua della normativa GDPR a cui da il consenso

Esempio:

{
"apikey":"String content",
"email": "email@company.com",
"consentTitle": "gdpr_can_send",
"language": "it",
}

30. revoke-gdpr-consent

Funzione di invio: GET – POST

Con questa funzione puoi revocare il consenso GDPR alla ricezione delle newsletter per un destinatario, in base al suo ID. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
recipientId – ID del destinatario
consentTitle – l’attributo di conferma/revoca del consenso GDPR
language – la lingua della normativa GDPR a cui revocare il consenso

Esempio:

{
"apikey":"String content",
"recipientId": 2147483647,
"consentTitle": "gdpr_can_send",
"language": "it",
}

31. revoke-gdpr-consent-by-email

Funzione di invio: GET – POST

Con questa funzione puoi revocare il consenso GDPR alla ricezione delle newsletter per un destinatario, in base al suo indirizzo email. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
email – email del destinatario
consentTitle – l’attributo di conferma/revoca del consenso GDPR
language – la lingua della normativa GDPR a cui revocare il consenso

Esempio:

{
"apikey":"String content",
"email": "email@company.com",
"consentTitle": "gdpr_can_send",
"language": "it",
}

32. cancel-sending-newsletter

Funzione di invio: GET – POST

Con questa funzione puoi annullare l’invio programmato di una newsletter, in base al suo ID. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
newsletterId – l’ID della newsletter

Esempio:

{
"apikey":"String content",
"newsletterId": 12345
}

33. custom-event

Funzione di invio: POST

Con questa funzione puoi creare un evento personalizzato. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
customText – il testo da inserire per attivare l’evento personalizzato

Esempio:

{
"apikey":"String content",
"customText": "String content"
}

34. custom-event/order

Funzione di invio: POST

Con questa funzione puoi creare un ordine personalizzato. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
customText – il testo da inserire per attivare l’evento personalizzato
orderId – L’ID dell’ordine
shopId – L’ID del negozio

Esempio:

{
"apikey":"String content",
"customText": "String content"
"orderId": "the_id_of_order",
"shopId": 123
}

35. custom-event/abandoned-checkout

Funzione di invio: POST

Con questa funzione puoi creare un carrello abbandonato personalizzato. La funzione accetta i seguenti parametri:

apiKey – parola chiave per accedere all’API
customText – il testo da inserire per attivare l’evento personalizzato
abandonedCheckoutId – L’ID del carrello abbandonato
shopId – L’ID del negozio

Esempio:

{
"apikey":"String content",
"customText": "String content"
"abandonedCheckoutId": "the_id_of_checkout",
"shopId": 123
}

Supporto / Per gli sviluppatori

Principi di base

Operazioni disponibili

1. create-list

2. update-list

3. get-lists

4. get-lists-details

5. create-newsletter

6. create-newsletter-from-template

7. create-recipient

8. delete-newsletter

9. delete-recipient

10. delete-recipient-by-email

11. delete-recipients-by-list

12. delete-list

13. get-app-id

14. get-data

ENTITÀ E CAMPI PERSONALIZZATI

Field

History

List

Mail

Recipient

ListMail

ListSub

Stats

UserStats

UrlClick

Url

FILTRI

Record

Operations

Funzioni

Esempio dell’intero request

Note

15. get-recipients-with-custom-fields

16. get-recipients-with-tags

17. get-invalid-recipients

18. get-subscribed-recipients

19. get-unsubscribed-recipients

20. subscribe-recipient

21. subscribe-recipient-by-email

22. unsubscribe-recipient

23. unsubscribe-recipient-by-email

24. send-newsletter

25. update-newsletter

26. update-recipient

27. import-recipients-async

28 grant-gdpr-consent

29. grant-gdpr-consent-by-email

30. revoke-gdpr-consent

31. revoke-gdpr-consent-by-email

32. cancel-sending-newsletter

33. custom-event

34. custom-event/order

35. custom-event/abandoned-checkout