API Rest

  La documentazione delle API è in aggiornamento

Autenticazione

Il web service REST fornito da Tazebao utilizza una procedura di autenticazione nota come HMAC (Keyed-Hash Message Authentication Code).

Ciascun client ottiene al momento dell'iscrizione un ID_KEY ed una SECRET_KEY da utilizzare per autenticare ogni singola richiesta alle API di Tazebao.

La firma deve essere passata nell'header HTTP di ogni richiesta. Il seguente è un esempio di pseudo-codice utile ad ottenere la firma:

SIGNATURE = Base64(Hmac('SECRET_KEY', "date: DATETIME", 'sha256'))

Data la firma SIGNATURE una richiesta a Tazebao deve conetenere un HEADER HTTP come definito di seguito:

~$ curl -v -H 'Date: "DATETIME"' -H 'Authorization: Signature keyId="ID_KEY",algorithm="hmac-sha256",headers="date",signature="SIGNATURE"'

Quello mostrato è codice puramente descrittivo, la reale implementazione dipende dal linguaggio utilizzato. Nella propria area personale sono presenti degli esempi di implementazione in PHP e Python, analoghi esempi sono contenuti in un repository apposito di esempio di client che consuma le API di Tazebao.

Profilo utente

Questa chiamata permette di conoscere l'utente associato al token inviato.

GET https://www.tazebao.email/api/v1/whoami/

RESPONSE 200

{
  "userId": 1,
  "userName": "otto",
  "userEmail": "mail@otto.to.it",
  "isSuperUser": false,
  "client": {
    "idKey": "xxxxxxxx",
    "secretKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Liste di iscritti

Gli iscritti alla newsletter possono essere organizzati in liste. I campi sono definiti nella seguente tabella.

Campo Tipo Descrizione
id Integer ID univoco (sola lettura)
name Varchar Nome lista
tot_subscribers Integer Numero di iscritti (sola lettura)

Lista di tutte le liste di iscritti

GET https://www.tazebao.email/api/v1/newsletter/subscriberlist/

Restituisce un array di liste di iscritti associate al client autenticato, es:

RESPONSE 200

[{
  "id":1,
  "name":"Journalists",
  "tot_subscribers": 145
},{
  "id":8,
  "name":"Companies",
  "tot_subscribers": 49
}]

E' possibile filtrare i risultati e cambiarne l'ordinamento aggiungendo parametri alla query string:

Parametro Descrizione
q Ricerca case insensitive sul nome della lista
sort Nome campo per ordinamento
sort_direction Direzione ordinamento: asc / desc

Dettaglio singola lista di iscritti

GET https://www.tazebao.email/api/v1/newsletter/subscriberlist/[LIST_ID]/

restituisce un oggetto che rappresenta la singola lista di iscritti referenziata da LIST_ID, es:

RESPONSE 200

{"id":1,"name":"Journalists", "tot_subscribers": 145}

Aggiunta lista di iscritti

POST https://www.tazebao.email/api/v1/newsletter/subscriberlist/

Il payload deve essere un json contenente il campo name, es:

{"name":"Skaters"}

RESPONSE 201

{"id":15,"name":"Skaters", "tot_subscribers": 0}

Modifica lista di iscritti

PUT https://www.tazebao.email/api/v1/newsletter/subscriberlist/[LIST_ID]/

Il payload deve essere un json contenente il campo name, es:

{"name":"Good Skaters"}

RESPONSE 200

{"id":15,"name":"Good Skaters", "tot_subscribers": 0}

Eliminazione lista di iscritti

DELETE https://www.tazebao.email/api/v1/newsletter/subscriberlist/[LIST_ID]/

RESPONSE 204 No Content

Iscritti

Gli iscritti alla tua newsletter, i campi sono specificati nella tabella seguente.

Campo Tipo Descrizione
id Integer ID univoco (sola lettura)
client Integer ID del client di appartenenza
email Varchar Indirizzo e-mail
info Varchar Informazioni aggiuntivein formato json
opt_in Boolean Indica se l'iscritto ha esplicitamente accettato le condizioni sulla privacy
opt_in_datetime Datetime Indica in quale data ed ora l'utente ha accettato le condizioni sulla privacy
lists Array Array di ID di liste di iscritti associate all'iscritto

Lista di tutti gli iscritti

GET https://www.tazebao.email/api/v1/newsletter/subscriber/

Restituisce una lista paginata (10 per pagina) di iscritti associati al client autenticato se in totale sono meno più 8.000. Se gli iscritti totali sono inferiori a 8000 invece viene restituita una lista completa non paginata (solo i campi all'interno della chiave results nell'esempio seguente) , es:

RESPONSE 200

{
    "count": 10,
    "next": "https://www.tazebao.email/api/v1/newsletter/subscriber/?page=2",
    "previous": null,
    "results": [
        {
            "id":1,
            "client":1,
            "email":"email@example.com",
            "subscription_datetime":"2016-09-08T14:49:58.860948Z",
            "info":"custom stuff",
            "lists":[1],
            "opt_in":true,
            "opt_in_datetime":"2016-09-08T14:49:58.860948Z"

        },
        {
            "id":2,
            "client":1,
            "email":"email2@example.com",
            "subscription_datetime":"2016-09-08T14:59:58.860948Z",
            "info":"",
            "lists":[1, 2],
            "opt_in":true,
            "opt_in_datetime":"2016-09-08T14:49:58.860948Z"
        },
        // ... 8 more
    ]
}

E' possibile filtrare i risultati e cambiarne l'ordinamento aggiungendo parametri alla query string:

Parametro Descrizione
q Ricerca case insensitive sull'e-mail e le info dell'iscritto
lists Ricerca di iscritti appartenenti alla lista avente ID uguale al valore passato
email Ricerca case insensitive sull'e-mail dell'iscritto
info Ricerca case insensitive sulle info dell'iscritto
sort Nome campo per ordinamento
sort_direction Direzione ordinamento: asc / desc

Dettaglio iscritti

GET https://www.tazebao.email/api/v1/newsletter/subscriber/[SUBSCRIBER_ID]/

Restituisce il dettaglio di un iscritto, es:

{
    "id":2,
    "client":1,
    "email":"email2@example.com",
    "subscription_datetime":"2016-09-08T14:59:58.860948Z",
    "info":"",
    "lists":[1, 2],
    "opt_in": true,
    "opt_in_datetime":"2016-09-08T14:59:58.860948Z"
}

Aggiunta iscritto

POST https://www.tazebao.email/api/v1/newsletter/subscriber/

Il payload deve essere un json contenente i campi dell'utente, es:

{"email":"xxx@otto.to.it","info":"{\"firstname\": \"meow\"}","lists":["1"], "opt_in": true, "opt_in_datetime": "2020-06-08T14:59:58.860948Z"}

RESPONSE 201

{
    "id":2,
    "client":1,
    "email":"xxx@otto.to.it",
    "subscription_datetime":"2016-09-08T14:59:58.860948Z",
    "info":"{\"firstname\": \"meow\"}",
    "lists":[1],
    "opt_in": true,
    "opt_in_datetime":"2020-06-08T14:59:58.860948Z"
}

Modifica iscritto

PUT https://www.tazebao.email/api/v1/newsletter/subscriber/[SUBSCRIBER_ID]/

Il payload deve essere un json contenente i campi dell'utente, es:

{"email":"aaa@otto.to.it","info":"{\"firstname\": \"meow\"}","lists":["1"]}

RESPONSE 200

{
    "id":2,
    "client":1,
    "email":"aaa@otto.to.it",
    "subscription_datetime":"2016-09-08T14:59:58.860948Z",
    "info":"{\"firstname\": \"meow\"}",
    "lists":[1],
    "opt_in": true,
    "opt_in_datetime":"2020-06-08T14:59:58.860948Z"
}

Eliminazione iscritti

DELETE https://www.tazebao.email/api/v1/newsletter/subscriber/[SUBSCRIBER_ID]/

RESPONSE 204 No Content

Aggiunta liste a iscritti

POST https://www.tazebao.email/api/v1/newsletter/subscriber/add_list/

Il payload deve essere un json contenente i campi lists e subscribers, es:

{"subscribers":[1],"lists":["67"]}

RESPONSE 200

Rimuovi liste da iscritti

POST https://www.tazebao.email/api/v1/newsletter/subscriber/remove_list/

Il payload deve essere un json contenente i campi lists e subscribers, es:

{"subscribers":[1],"lists":["67"]}

RESPONSE 200

Topic

Le campagne sono organizzate in topic. Ciascun topic ha le proprie informazioni, i campi sono roportati nella tabella seguente.

Campo Tipo Descrizione
id Integer ID univoco (sola lettura)
name Varchar Nome topic
sending_address Varchar Indirizzo e-mail che compare nel campo from della newsletter
sending_name Varchar Nome che compare nel campo from della newsletter
unsubscribe_url Varchar URL utilizzato per la disiscrizione. E' supportato l'utilizzo di variabili e funzioni per criptare con la chiave segreta, è disponibile anche un link gestito da Tazebao per la disiscrizione. Ulteriore documentazione disponibile a login effettuato.

Lista di tutti i topic

GET https://www.tazebao.email/api/v1/newsletter/topic/

Restituisce un array di liste di topic associati al client autenticato, es:

RESPONSE 200

[
  {
    "id": 1,
    "name": "Lavori",
    "sending_address": "tazebao@otto.to.it",
    "sending_name": "tazebao",
    "unsubscribe_url": "https://www.tazebao.email/unsubscribe/?id={{ id }}&email={{ email }}&sig={% encrypt id email %}"
  },
  //...
]

E' possibile filtrare i risultati e cambiarne l'ordinamento aggiungendo parametri alla query string:

Parametro Descrizione
q Ricerca case insensitive sul nome dell topic
sort Nome campo per ordinamento
sort_direction Direzione ordinamento: asc / desc

Dettaglio topic

GET https://www.tazebao.email/api/v1/newsletter/topic/[TOPIC_ID]/

restituisce un oggetto che rappresenta un singolo topic referenziato da TOPIC_ID, es:

RESPONSE 200

{
    "id": 1,
    "name": "Lavori",
    "sending_address": "tazebao@otto.to.it",
    "sending_name": "tazebao",
    "unsubscribe_url": "https://www.tazebao.email/unsubscribe/?id={{ id }}&email={{ email }}&sig={% encrypt id email %}"
}

Aggiunta topic

POST https://www.tazebao.email/api/v1/newsletter/topic/

Il payload deve essere un json contenente i campi del topic name, es:

{
    "name": "Lavori",
    "sending_address": "tazebao@otto.to.it",
    "sending_name": "tazebao",
    "unsubscribe_url": "https://www.tazebao.email/unsubscribe/?id={{ id }}&email={{ email }}&sig={% encrypt id email %}"
}

RESPONSE 201

{
    "id": 1,
    "name": "Lavori",
    "sending_address": "tazebao@otto.to.it",
    "sending_name": "tazebao",
    "unsubscribe_url": "https://www.tazebao.email/unsubscribe/?id={{ id }}&email={{ email }}&sig={% encrypt id email %}"
}

Modifica topic

PUT https://www.tazebao.email/api/v1/newsletter/topic/[TOPIC_ID]/

Il payload deve essere un json contenente i campi del topic name, es:

{
    "name": "Lavori 2020",
    "sending_address": "tazebao@otto.to.it",
    "sending_name": "tazebao",
    "unsubscribe_url": "https://www.tazebao.email/unsubscribe/?id={{ id }}&email={{ email }}&sig={% encrypt id email %}"
}

RESPONSE 200

{
    "id": 1,
    "name": "Lavori 2020",
    "sending_address": "tazebao@otto.to.it",
    "sending_name": "tazebao",
    "unsubscribe_url": "https://www.tazebao.email/unsubscribe/?id={{ id }}&email={{ email }}&sig={% encrypt id email %}"
}

Eliminazione topic

DELETE https://www.tazebao.email/api/v1/newsletter/topic/[TOPIC_ID]/

RESPONSE 204 No Content

Attenzione! Eliminando un topic si eliminano tutte le campagne correlate!

Campagne

Le campagne sono i contenuti che effettivamente vengono inviati, i campi di una campagna sono specificati nella seguente tabella.

Campo Tipo Descrizione
id Integer ID univoco (sola lettura)
insertion_datetime Datetime Data ed ora di inserimento (sola lettura)
last_edit_datetime Datetime Data ed ora di ultima modifica (sola lettura)
last_dispatch Datetime Data ed ora ultimo invio (sola lettura)
last_not_test_dispatch Datetime Data ed ora ultimo invio esclusi invvi di test (sola lettura)
name Varchar Nome campagna
subject Varchar Oggetto dell'e-mail
html_text Varchar Corpo dell'email (HTML)
plain_text Varchar Corpo dell'email (testo puro)
template Integer Riferimento al template utilizzato per la creazione dell'e-mail
topic_id Integer Riferimento al topic
topic Varchar Nome testuale del topic (sola lettura)
url Varchar Url cui è possibile visualizzare la campagna online (accessibile solo se abilitato)
view_online Boolean Abilita/disabilita la visualizzazione della campagna online

Lista di tutte le campagne

GET https://www.tazebao.email/api/v1/newsletter/campaign/

Restituisce una lista paginata (10 per pagina) di campagne associate al client autenticato se in totale sono più di 100, altrimenti ritorna una lista con tutte le campagne presenti (valore della chiave results nell'esempio che segue) es:

RESPONSE 200

{
    "count": 2,
    "next": "https://www.tazebao.email/api/v1/newsletter/campaign/?page=2",
    "previous": null,
    "results": [
        {
            "id": 1,
            "topic_id": 1,
            "topic": "New Articles",
            "name": "Let's talk about birds!",
            "insertion_datetime": "2016-09-08T14:51:06.980733Z",
            "last_edit_datetime": "2016-09-22T11:42:30.398038Z",
            "last_dispatch": "2016-09-22T11:42:30.398038Z",
            "last_not_test_dispatch": "2016-09-22T11:42:30.398038Z",
            "subject": "A new article on birds.com!",
            "plain_text": "plain bla bla",
            "html_text": "html bla bla",
            "subject": "Let's talk about birds!",
            "template": 100,
            "view_online": true,
            "url": "https://www.tazebao.email/newsletter/client-slug/2016/09/08/campaign-slug/"
        }
        // ... 1 more
    ]
}

E' possibile filtrare i risultati e cambiarne l'ordinamento aggiungendo parametri alla query string:

Parametro Descrizione
q Ricerca case insensitive sul nome della campagna
view_online Filtra le campagne per la loro visibilità online, possibili valori: 0 e 1
topic Ricerca campagne il cui topic ID sia uguale a quello specificato
subject Ricerca case insensitive sull'oggetto della campagna
text Ricerca case insensitive sul testo della campagna
date_from Ricerca campagne con data di ultima modifica posteriore alla data specificata, formato: YYYY-MM-DD
date_to Ricerca campagne con data di ultima modifica anteriore alla data specificata, formato: YYYY-MM-DD
sort Nome campo per ordinamento
sort_direction Direzione ordinamento: asc / desc

Dettaglio campagna

GET https://www.tazebao.email/api/v1/newsletter/campaign/[CAMPAIGN_ID]/

Restituisce il dettaglio di una campagna, es:

{
    "id": 1,
    "topic_id": 1,
    "topic": "New Articles",
    "name": "Let's talk about birds!",
    "insertion_datetime": "2016-09-08T14:51:06.980733Z",
    "last_edit_datetime": "2016-09-22T11:42:30.398038Z",
    "last_dispatch": "2016-09-22T11:42:30.398038Z",
    "last_not_test_dispatch": "2016-09-22T11:42:30.398038Z",
    "subject": "A new article on birds.com!",
    "plain_text": "plain bla bla",
    "html_text": "html bla bla",
    "subject": "Let's talk about birds!",
    "template": 100,
    "view_online": true,
    "url": "https://www.tazebao.email/newsletter/client-slug/2016/09/08/campaign-slug/"
}