Introduzione all’API e ai token

L'API REST di MailerEnergy ti permette di collegare la piattaforma ad altri programmi o al tuo sito, così da automatizzare operazioni che faresti a mano dal pannello: creare liste, aggiungere iscritti, leggere campagne e statistiche. In pratica è un modo per "parlare" con MailerEnergy tramite codice, senza aprire il browser. Se non sei uno sviluppatore puoi tranquillamente ignorare questa sezione: tutto quello che fa l'API si può fare anche dal pannello.

Cos'è l'API REST

REST è semplicemente lo standard più diffuso per le API web: le richieste viaggiano su normali chiamate HTTP (le stesse che usa il browser) e le risposte arrivano in formato strutturato, facile da leggere per un programma. Ogni operazione corrisponde a un indirizzo da chiamare, detto endpoint, abbinato a un verbo HTTP: in genere GET per leggere dati e POST per crearli.

Il base URL

Tutti gli endpoint partono dallo stesso indirizzo di base (il base URL):

• /api/v1

Per comporre l'indirizzo completo di un endpoint, aggiungi il suo percorso al base URL. Per esempio, per ottenere le tue liste chiamerai /api/v1/lists.

Gli endpoint disponibili

Ecco le operazioni che puoi effettuare tramite l'API:

• GET /api/v1/lists — elenca tutte le tue liste.
• POST /api/v1/lists — crea una nuova lista.
• GET /api/v1/lists/{id} — leggi i dettagli di una singola lista.
• GET /api/v1/lists/{id}/subscribers — elenca gli iscritti di una lista.
• POST /api/v1/lists/{id}/subscribers — aggiungi un iscritto a una lista (campi: email, e in opzione first_name e last_name).
• GET /api/v1/campaigns — elenca le tue campagne.
• GET /api/v1/campaigns/{id} — leggi i dettagli e le statistiche di una campagna.

Dove vedi {id}, devi sostituire l'identificativo della lista o della campagna a cui ti riferisci.

Come generare un token

Per usare l'API serve un token, cioè una chiave personale che identifica il tuo accesso. Ecco come crearlo:

1. Vai nel menu Aiuto > API & Token.
2. Crea un nuovo token.
3. Copialo e conservalo subito in un posto sicuro.

Punti importanti da ricordare:

• Ogni utente ha i propri token: non sono condivisi con il resto del team.
• Il token viene mostrato una sola volta, al momento della creazione. Se lo perdi, non potrai rivederlo: dovrai crearne uno nuovo.
• I token sono revocabili in qualsiasi momento: se pensi che uno sia compromesso, eliminalo e generane un altro.

Autenticazione Bearer

Ogni richiesta all'API deve includere il token in un'intestazione (header) chiamata Authorization, nel formato Bearer:

• Authorization: Bearer IL_TUO_TOKEN

Sostituisci IL_TUO_TOKEN con il token che hai generato. Senza questo header, o con un token sbagliato o revocato, la richiesta verrà rifiutata. Tratta il token come una password: chi lo possiede può operare sul tuo account.

Buono a sapersi

Le email aggiunte tramite API passano dalla stessa verifica usata nel pannello (sintassi, dominio, indirizzi usa-e-getta e role-based): gli indirizzi inesistenti o fasulli vengono bloccati e finiscono in soppressione, esattamente come quando li inserisci a mano o via import CSV. Quando un endpoint richiede l'ID di una lista, lo trovi nella colonna ID della pagina Liste (cliccalo per copiarlo).