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
}]

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 (200 per pagina) di iscritti associati al client autenticato, es:

RESPONSE 200

{
    "count": 300,
    "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"
        },
        // ... 198 more
    ]
}

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 %}"
  },
  //...
]

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 (20 per pagina) di campagne associate al client autenticato, 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/"
        }
        // ... 19 more
    ]
}

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/"
}