Endpoint ed esempi

Le API REST di MailerEnergy ti permettono di collegare il tuo sito, il tuo gestionale o altri strumenti alla piattaforma: per esempio puoi aggiungere automaticamente nuovi iscritti a una lista quando qualcuno compila un form sul tuo sito. Tutte le chiamate condividono lo stesso percorso di base: /api/v1, da anteporre all'host della piattaforma (ad esempio https://app.mailerenergy.com/api/v1).

Prima di tutto: il token

Ogni chiamata va autenticata con un token personale. Lo generi dal menu Aiuto > API & Token. Ogni utente ha i propri token, indipendenti da quelli degli altri membri del team. Attenzione: il token viene mostrato una sola volta, al momento della creazione, quindi copialo subito e conservalo in un posto sicuro. Se lo perdi non puoi recuperarlo: dovrai generarne uno nuovo. Puoi revocare un token quando vuoi, e da quel momento smetterà di funzionare. Il token va passato in ogni richiesta tramite l'header Authorization: Bearer IL_TUO_TOKEN.

Gli endpoint principali

Ecco le chiamate che userai più spesso:

• GET /lists — elenco di tutte le tue liste
• POST /lists — crea una nuova lista
• GET /lists/{id} — dettagli di una singola lista
• GET /lists/{id}/subscribers — elenco degli iscritti di una lista
• POST /lists/{id}/subscribers — aggiungi un iscritto a una lista (campi: email, first_name, last_name)
• GET /campaigns — elenco delle campagne
• GET /campaigns/{id} — dettagli di una campagna

In tutti gli endpoint, {id} va sostituito con un numero reale (vedi sotto come trovare l'ID della lista). Ricorda che ogni richiesta deve includere l'header Authorization con il tuo token.

Dove trovo l'ID della lista?

L'{id} che vedi negli endpoint è l'identificativo numerico della lista. Lo trovi nel menu Liste, nella colonna ID: ti basta cliccarci sopra per copiarlo negli appunti.

Esempio: aggiungere un iscritto via curl

Supponiamo che la tua lista abbia ID 123. Questo comando aggiunge un nuovo iscritto:

curl -X POST https://app.mailerenergy.com/api/v1/lists/123/subscribers \
  -H "Authorization: Bearer IL_TUO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"mario.rossi@example.com","first_name":"Mario","last_name":"Rossi"}'

Sostituisci 123 con l'ID reale della tua lista e IL_TUO_TOKEN con il token che hai generato. Il solo campo obbligatorio è email; first_name e last_name sono facoltativi.

Se invii un indirizzo email già presente nella lista, il record esistente viene aggiornato anziché duplicato: puoi quindi usare la stessa chiamata anche per correggere nome e cognome di un iscritto già registrato.

Verifica email anche via API

Importante: ogni indirizzo aggiunto tramite API viene verificato esattamente come quelli inseriti a mano o importati da CSV. Controlliamo la sintassi, il dominio e i record MX e blocchiamo gli indirizzi usa-e-getta, quelli di tipo generico/aziendale (role-based, come info@ o noreply@) e quelli palesemente inesistenti. Gli indirizzi fasulli o non validi non entrano nella lista: finiscono in soppressione e non riceveranno invii. Questo protegge la reputazione del tuo dominio e mantiene la tua lista pulita, senza che tu debba fare nulla. Tienilo presente quando integri un form: un indirizzo accettato dalla tua applicazione potrebbe comunque finire in soppressione se non supera la verifica.