Cos'è l'API di Benchmark Email? Cosa può fare, prezzi e come usarla (con un esempio di integrazione con Google Sheets)

Il tool di email marketing “Benchmark Email” offre un API ufficiale che consente di scambiare informazioni su contatti e campagne con strumenti esterni. Puoi sincronizzare automaticamente i dati gestiti in e-commerce, sistemi di prenotazione, CRM, Google Sheets e altro ancora con Benchmark Email, liberandoti dalla fastidiosa routine di “esportare un CSV e importarlo ogni settimana”.

In questo articolo, basato sulla documentazione ufficiale di ottobre 2026, spiego nel dettaglio una panoramica dell’API di Benchmark Email, cosa può e non può fare, le condizioni d’uso, come ottenere una chiave API e un esempio concreto di integrazione con Google Sheets.

Cos’è l’API di Benchmark Email?

L’API di Benchmark Email è un meccanismo per connettere il tuo account Benchmark Email a software esterni. La pagina ufficiale la presenta con il concetto che “il tuo ecosistema dovrebbe funzionare in modo integrato”, e presenta queste caratteristiche:

• JSON su HTTP (un formato REST comune), con la pubblicazione anche di una specifica OpenAPI
• Autenticazione tramite chiave API (l’header X-API-Key)
• Permessi con ambito limitato (scoped), che consentono di circoscrivere l’accesso a contatti, campagne, report e domini
• Possibilità di impostare una data di scadenza per ciascuna chiave, oltre a disattivarle e riattivarle senza doverle eliminare
• Presenza di limiti di velocità (rate limits) orari e mensili, con la possibilità di verificare i crediti residui negli header delle risposte
• Guide agli scenari per i flussi di lavoro principali e una guida alla migrazione da Benchmark Classic

Il punto fondamentale è che l’API può essere utilizzata su tutti i piani senza costi aggiuntivi. Tutto ciò di cui hai bisogno è un account attivo e una chiave API.

A chi è rivolta l’API

La pagina ufficiale la presenta come una funzionalità pensata per risolvere problemi come:

• Clienti del tuo e-commerce, lead in un foglio di calcolo e contatti da POS o CRM che risiedono in luoghi separati
• La necessità di ripetere costantemente esportazione CSV → pulizia → importazione per costruire una lista email
• Il copia-incolla manuale dei risultati delle campagne in fogli di calcolo o presentazioni ogni singola volta

In altre parole, è pensata per i team i cui dati sono sparsi su più strumenti e che si ritrovano a fare abbinamenti di record a mano. Al contrario, se gestisci tutto unicamente all’interno dell’interfaccia di Benchmark Email, non avrai alcun bisogno dell’API.

Cosa puoi fare con l’API di Benchmark Email

Le risorse con cui puoi interagire tramite l’API si dividono in quattro gruppi principali.

Gestione dei contatti

I contatti sono la risorsa che utilizzerai più spesso.

• Creare, aggiornare ed eliminare contatti: Usando l’indirizzo email come chiave, puoi registrare contatti specificando un nome e qualsiasi campo personalizzato.
• Ricerca e segmenti: Puoi effettuare ricerche per indirizzo email, dominio email, campi personalizzati, tag, liste, stato, date di creazione e aggiornamento e altro ancora. Puoi scegliere tra diversi operatori come “uguale a”, “contiene”, “inizia con”, “entro un periodo” e “è vuoto”, combinandoli con AND/OR.
• Controllo dei duplicati: Effettuando una ricerca per indirizzo email prima di creare un contatto, puoi evitare di inserire una seconda volta un contatto già registrato.
• Aggiornamenti differenziali: Esiste anche un endpoint che consente di aggiungere o rimuovere contatti da liste, aggiungere o rimuovere tag e aggiornare campi simultaneamente per un singolo contatto.
• Esportazione e recupero eventi: Puoi anche esportare i contatti e recuperare la cronologia degli eventi per ciascun contatto.

Gestione delle liste

Puoi creare, rinominare, duplicare, unire ed eliminare liste tramite l’API. Questa funzione è utile quando il tuo CRM o tool di e-commerce rappresenta la fonte di verità su “come raggruppare i clienti”. Ad esempio, puoi fare in modo che il sistema esterno stabilisca gruppi come “ha acquistato 3 o più volte” o “livello di abbonamento Gold” e rifletta questi dati nelle liste di Benchmark.

Nota che l’unione crea una nuova lista mantenendo quelle originali, mentre i contatti duplicati vengono gestiti automaticamente.

Creazione e configurazione delle campagne

Tramite l’API puoi impostare nome della campagna, oggetto, testo di anteprima, nome del mittente e indirizzo mittente, indirizzo di risposta, lista dei destinatari, corpo HTML e altro ancora, salvando la campagna come bozza. È anche possibile duplicare una campagna esistente, e la copia creata sarà sempre una bozza, indipendentemente dallo stato dell’originale.

Recupero dei report

Puoi recuperare cinque tipologie di informazioni:

• Panoramica della dashboard (ultimi 1-90 giorni, con variazione percentuale rispetto al periodo precedente)
• Prestazioni di recapito complessive (inviate, recapitate, aperture, clic, rimbalzi, disiscrizioni, reclami)
• Dati storici (time series) delle prestazioni di recapito (utili per creare grafici)
• Report per singole campagne (inclusi i clic per singolo link)
• Trend di coinvolgimento per singole campagne

Alimentando uno strumento di BI o una tua dashboard con questi dati, elimini la noia di dover “copiare i tassi di apertura nelle diapositive”.

Controllo dei domini di invio

Puoi leggere lo stato di autenticazione dei domini di invio privati. Questa funzione è utile quando desideri monitorare la consegnabilità su una dashboard separata o comunicare a un altro sistema che “questo dominio è pronto per l’invio”.

Recupero delle informazioni sull’account

Tramite GET /api/account puoi recuperare informazioni di base come città, paese, codice paese, codice valuta e fuso orario dell’account. Puoi usarlo per verificare che la tua chiave API funzioni prima di chiamare altri endpoint e per allineare il fuso orario quando recuperi i report. Nota che il valore unlayerKey incluso nella risposta è una chiave segreta (hash SHA256) per l’integrazione con Unlayer, quindi fai attenzione a non esporla nei log o a schermo.

Cosa non può fare l’API (operazioni riservate all’interfaccia di Benchmark Email)

L’API non è universale e alcune operazioni vengono intenzionalmente escluse per garantire una spedizione sicura.

In sintesi, il sistema è progettato in modo tale che le operazioni che potrebbero causare un invio accidentale non possano essere eseguite tramite chiave API. Il flusso di lavoro previsto consiste nel preparare le bozze delle campagne tramite API e fare in modo che sia una persona a effettuare il controllo finale e a premere il pulsante di invio.

Condizioni d’uso, limiti di velocità (rate limits) e prezzi

Prezzi e numero di chiavi API

• L’API è gratuita su tutti i piani
• Il piano gratuito consente 2 chiavi API attive, mentre il piano Pro ne permette fino a 10 (contatta il reparto vendite se te ne servono di più)
• La raccomandazione ufficiale è di “creare una chiave per ogni integrazione”. Puoi limitare l’ambito (permessi) di ciascuna chiave e disattivarne singolarmente l’utilizzo quando non sono più necessarie

Limiti di velocità e quota mensile

In base alla documentazione per sviluppatori, i limiti sono i seguenti.

Ad esempio, per un piano con un limite ipotetico di 1.000 contatti, il valore di riferimento è di 10.000 richieste al mese sul piano gratuito e 100.000 richieste al mese sui piani a pagamento (questo è solo un calcolo di esempio; verifica i numeri effettivi del piano a cui sei abbonato).

Quando superi un limite, ricevi un errore 429 Too Many Requests e l’header Retry-After indica il numero di secondi da attendere. La risposta restituisce inoltre header come X-RateLimit-Remaining (rimanenti per l’ora) e X-Monthly-Remaining (rimanenti per il mese), permettendoti di regolare l’elaborazione monitorando le risorse disponibili.

Inoltre, se provi ripetutamente a utilizzare una chiave API non valida, quell’indirizzo IP viene temporaneamente bloccato. Se continui a ricevere errori 401, verifica la chiave anziché insistere con tentativi continui.

Altre condizioni

• Solo gli utenti con permessi di proprietario (owner) possono creare e gestire le chiavi API
• Una chiave può essere utilizzata solo finché l’account si trova nello stato “Open” o “Pending Cancel” (in caso di ritardi nei pagamenti o sospensione, riceverai l’errore 403)
• È richiesto un header User-Agent in ogni richiesta (come descritto di seguito)

Dall’ottenimento di una chiave API alla prima richiesta

1. Creare una chiave API

1. Accedi a Benchmark Email con l’account proprietario
2. Apri Impostazioni > Chiavi API (Settings > API Keys)
3. Clicca su Crea chiave API (Create API Key)
4. Assegnale un nome chiaro (ad esempio, Sheets Sync) e seleziona solo gli ambiti necessari
5. Imposta una data di scadenza se lo desideri (se non la imposti, la chiave non scadrà mai)
6. Copia subito la chiave mostrata dopo la creazione e conservala in un luogo sicuro

La chiave viene mostrata una sola volta, al momento della creazione. Se la perdi, puoi rigenerarla dalla schermata delle chiavi API, ma la vecchia chiave diventerà non valida.

Una chiave API è composta da bme_ + un codice regione di 2 caratteri (come us, jp o eu) + una stringa casuale di 43 caratteri, per un totale di 50 caratteri.

2. Verificare l’URL di base (Base URL)

L’URL di base varia in base alla regione e al cluster del tuo account e assume la forma https://api-{region}-{cluster}.benchmarkemail.io (ad esempio, https://api-us-west-2-a.benchmarkemail.io). Il tuo URL di base personale viene mostrato nella schermata Impostazioni > Chiavi API, quindi utilizza quello di riferimento.

3. Inviare la prima richiesta

curl -H "X-API-Key: bme_your-api-key-here" \
  -H "User-Agent: MyIntegration/1.0" \
  "<your-api-base-url>/api/contact-structure"

Se la struttura dei contatti (le definizioni dei campi personalizzati) viene restituita in formato JSON, l’operazione è riuscita. Se ricevi 401 o 403, verifica la chiave, l’ambito e lo stato dell’account.

Se ricevi un errore 403 che restituisce HTML anziché JSON, è altamente probabile che l’header User-Agent non venga inviato. Questo accade perché la protezione perimetrale di Benchmark Email rifiuta le richieste prive di User-Agent. cURL e le librerie standard dei principali linguaggi lo aggiungono automaticamente, ma ambienti come l’estensione cURL di PHP richiedono che venga impostato esplicitamente.

Nota: L’esempio cURL presente nella pagina di presentazione commerciale (il formato che passa list_id a /v1/contacts) e gli endpoint della documentazione per sviluppatori (il formato che passa contactStructureId e il campo _id a /api/contact) sono scritti in modo diverso. Quando effettui l’implementazione, fai sempre riferimento alla documentazione per sviluppatori (developers.benchmarkemail.io).

Come funzionano gli ambiti (Scopes)

Gli ambiti vengono associati a una chiave API nel formato {resource}:{access type}.

Ci sono tre punti chiave da ricordare:

• write include read: Con contacts:write puoi anche leggere i contatti
• Principio del privilegio minimo: Suddividi le tue chiavi; ad esempio, usa solo reports:read per una dashboard di reportistica e solo contacts:write per la sincronizzazione dei contatti da un foglio di calcolo
• read è sufficiente per la ricerca: La ricerca dei contatti viene eseguita tramite POST, ma tutto ciò di cui hai bisogno è contacts:read

Casi d’uso concreti

Da qui in poi, basandomi sulle specifiche della documentazione ufficiale, analizzerò esempi di integrazione realmente utili.

Nota: Il codice sottostante è un esempio scritto secondo le specifiche della documentazione ufficiale. Prima di eseguirlo sulla tua lista di produzione, verifica sempre che funzioni con una lista di prova o con una quantità ridotta di dati.

Esempio 1: Sincronizzare i contatti da Google Sheets a Benchmark Email

Immagina di raccogliere iscrizioni a seminari o risposte a sondaggi in Google Sheets. Registri solo le righe appena aggiunte in una lista di Benchmark Email, evitando di duplicare indirizzi email già presenti.

Preparazione

1. Crea una chiave API con l’ambito contacts:write
2. Tramite GET /api/contact-structure, prendi nota dell’identificativo _id della struttura dei contatti e dei codici _id dei campi “nome” e “cognome”
3. Prendi nota dell’identificativo _id della lista di destinazione (puoi recuperare la lista tramite GET /api/contact-structure/{structure ID}/lists/all)
4. Usa la prima riga del foglio di calcolo come intestazione, con colonna A = email, colonna B = nome, colonna C = cognome e colonna D = risultato sincronizzazione
5. Salva la chiave API e gli identificativi nelle “Proprietà dello script” (Script Properties) di Apps Script (evita di inserirli direttamente nel codice)

Codice Google Apps Script

// ===== Settings (saved in script properties) =====
const P = PropertiesService.getScriptProperties();
const BASE_URL = P.getProperty('BME_BASE_URL');           // e.g. https://api-us-west-2-a.benchmarkemail.io
const API_KEY = P.getProperty('BME_API_KEY');             // bme_us_...
const STRUCTURE_ID = P.getProperty('BME_STRUCTURE_ID');   // _id of the contact structure
const LAST_NAME_ID = P.getProperty('BME_LAST_NAME_FIELD_ID');
const FIRST_NAME_ID = P.getProperty('BME_FIRST_NAME_FIELD_ID');
const LIST_ID = P.getProperty('BME_LIST_ID');

// ===== Common API call =====
function api_(method, path, body, retry) {
  retry = retry || 0;
  const res = UrlFetchApp.fetch(BASE_URL + path, {
    method: method,
    contentType: 'application/json',
    headers: { 'X-API-Key': API_KEY, 'User-Agent': 'SheetsToBenchmark/1.0' },
    payload: body ? JSON.stringify(body) : undefined,
    muteHttpExceptions: true,
  });
  const code = res.getResponseCode();
  if (code === 429 && retry < 3) {          // Rate limit: wait, then retry
    Utilities.sleep(60 * 1000);
    return api_(method, path, body, retry + 1);
  }
  if (code >= 400) throw new Error(code + ' ' + res.getContentText());
  const text = res.getContentText();
  return text ? JSON.parse(text) : null;
}

// ===== Duplicate check by email address =====
function emailExists_(email) {
  const r = api_('post', '/api/contact/search', {
    contactStructureId: STRUCTURE_ID,
    page: 1,
    pageSize: 1,
    source: ['_id'],
    contactSpecification: {
      filters: [{ criterias: [{ columnToFilter: 'KEY', operator: 'EQ', values: [email] }] }],
    },
  });
  return r.totalRecords > 0;
}

// ===== Register only unsynced rows =====
function syncNewRows() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Applicants');
  const rows = sheet.getDataRange().getValues();

  for (let i = 1; i < rows.length; i++) {
    const email = String(rows[i][0]).trim();
    const firstName = rows[i][1];
    const lastName = rows[i][2];
    const synced = rows[i][3];
    if (!email || synced) continue;       // Skip empty and already-synced rows

    let result;
    if (emailExists_(email)) {
      result = 'Skipped (already registered)';
    } else {
      api_('post', '/api/contact', {
        key: email,
        contactStructureId: STRUCTURE_ID,
        fields: [
          { _id: LAST_NAME_ID, value: lastName },
          { _id: FIRST_NAME_ID, value: firstName },
        ],
        lists: [{ _id: LIST_ID }],
      });
      result = 'Synced ' + new Date().toLocaleString();
    }
    sheet.getRange(i + 1, 4).setValue(result);
    Utilities.sleep(300);                  // Avoid back-to-back requests
  }
}

Fatto ciò, se configuri syncNewRows su un trigger basato sul tempo di Apps Script (come “ogni ora” o “ogni mattina”), i dati verranno riflessi automaticamente nella tua lista di Benchmark Email man mano che vengono aggiunte righe al foglio di calcolo. Se utilizzi il foglio di risposta di un Google Form, puoi anche sfruttare il trigger “all’invio del modulo”.

Ogni riga richiede al massimo 2 richieste (ricerca + creazione), lasciando ampio margine rispetto al limite di 3.600 richieste all’ora.

Esempio 2: Scrivere automaticamente i risultati di recapito su Google Sheets

Il secondo esempio va nella direzione opposta e compila automaticamente i report delle campagne inviate all’interno di un foglio di calcolo. L’API per l’elenco delle campagne (GET /api/email/campaign) restituisce anche le statistiche delle campagne inviate (aperture, clic, tasso di apertura e così via). Puoi riutilizzare la funzione api_ vista in precedenza.

Questo processo funziona con una chiave dotata dell’ambito campaigns:read.

function exportCampaignStats() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName('Delivery Report') || ss.insertSheet('Delivery Report');

  const res = api_('get', '/api/email/campaign?page=1&size=25&statuses=sent&sort=scheduledAt:desc');

  const header = ['Campaign name', 'Subject', 'Sent at', 'Sent', 'Delivered',
                  'Opens (unique)', 'Open rate (%)', 'Clicks (unique)', 'Click rate (%)'];
  const rows = res.records.map(function (c) {
    const s = c.stats || {};
    return [
      c.name, c.subject, c.scheduledAt,
      s.sent, s.delivered,
      s.opens && s.opens.unique, s.opens && s.opens.rate,
      s.clicks && s.clicks.unique, s.clicks && s.clicks.rate,
    ];
  });

  sheet.clearContents();
  sheet.getRange(1, 1, 1, header.length).setValues([header]);
  if (rows.length) sheet.getRange(2, 1, rows.length, header.length).setValues(rows);
}

Se lo esegui con un trigger giornaliero mattutino, avrai i dati più recenti pronti non appena aprirai il foglio. Da lì potrai automatizzare un report settimanale creando grafici con le funzioni standard di Google Sheets o collegandoti a Looker Studio.

Se hai bisogno di analisi più dettagliate, sfrutta anche l’API dei report.

• GET /api/reports/dashboard?pastDays=30&timezone=America/New_York: Panoramica degli ultimi 30 giorni (con variazione percentuale rispetto al periodo precedente)
• GET /api/reports/email/{campaign ID}: Clic per singolo link di una specifica campagna
• GET /api/reports/email/{campaign ID}/engagement?period=week: Trend di aperture e clic per una settimana dopo l’invio

Impostando timezone sul tuo fuso orario (ad esempio, America/New_York), le date verranno delimitate e aggregate in base al tuo fuso orario locale, risultando ideali per i report della tua area geografica.

Esempio 3: Aggiungere automaticamente clienti da un sito e-commerce o modulo di prenotazione a una lista (n8n, Zapier e altri)

Al momento Benchmark Email non dispone di uno strumento nativo di workflow no-code. Tuttavia, la documentazione ufficiale specifica che “è possibile automatizzare i flussi di lavoro tramite l’API utilizzando strumenti come Zapier e n8n”. Sfruttando un nodo in grado di inviare richieste HTTP (il nodo HTTP Request di n8n, i Webhooks di Zapier, ecc.), potrai effettuare l’integrazione quasi senza scrivere codice.

Ad esempio, il flusso si sviluppa così:

1. Trigger: Arriva un ordine sul sito e-commerce / viene inviato un modulo di prenotazione / un utente compila un Google Form
2. Ricerca: Usa POST /api/contact/search per verificare se l’indirizzo email è già registrato
3. Diramazione (Branch)
   • Non registrato → Crealo con POST /api/contact e aggiungilo a una lista
   • Registrato → Usa l’endpoint di aggiornamento differenziale per aggiungerlo alle liste, assegnare tag e aggiornare i campi
4. Notifica: Se necessario, invia un avviso a Slack o Microsoft Teams del tipo “è stato registrato un nuovo contatto”

Filtrando tramite FIELD_ID durante la ricerca, puoi anche verificare condizioni come “solo gli utenti il cui livello di abbonamento è Gold”. In questo modo manterrai aggiornate automaticamente le liste di Benchmark Email, preservando al contempo i dati anagrafici dei clienti nel tuo e-commerce o CRM.

Esempio 4: Duplicare la newsletter del mese scorso per creare la bozza di questo mese

Per attività ricorrenti come una newsletter mensile, in cui invii quasi lo stesso design a cadenza regolare, la duplicazione di una campagna passata per preparare una bozza rappresenta la soluzione ideale.

# 1. Duplicate last month's campaign to create this month's draft
curl -X POST "<your-api-base-url>/api/email/campaign/{last month's campaign ID}/duplicate" \
  -H "X-API-Key: $BENCHMARK_KEY" \
  -H "User-Agent: MonthlyNewsletter/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "name": "November 2026 Newsletter" }'

# 2. Update the subject, preview text, and destination list (__v is the value you just retrieved)
curl -X PATCH "<your-api-base-url>/api/email/campaign/{new campaign ID}" \
  -H "X-API-Key: $BENCHMARK_KEY" \
  -H "User-Agent: MonthlyNewsletter/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "[November Issue] This Month'"'"'s Announcements",
    "previewText": "A roundup of new features and use cases",
    "lists": ["{destination list ID}"],
    "__v": 0
  }'

Fatto questo, apri la bozza nell’interfaccia di Benchmark Email, riscrivi il testo, controlla il contenuto e procedi con l’invio. Suddividendo i compiti (l’API si occupa di “preparare la bozza” e una persona gestisce “il controllo finale e l’invio”), potrai operare in totale sicurezza.

Esempio 5: Affidare l’implementazione a un assistente di codifica IA

La documentazione ufficiale per sviluppatori fornisce anche risorse dedicate agli assistenti di programmazione basati su intelligenza artificiale.

• llms.txt: Un indice di tutte le pagine della documentazione
• llms-full.txt: Il testo completo di tutta la documentazione in un unico file
• SKILL.md: Una guida per agenti che riassume endpoint, linee guida decisionali ed errori comuni

Quando ti rivolgi a un’IA, un ottimo approccio consiste nell’istruirla così: “Leggi prima SKILL.md, poi la guida agli scenari che corrisponde a ciò che desidero realizzare e infine scrivi il codice”. Ad esempio, persino uno script Google Apps Script simile all’Esempio 1 può essere adattato alle tue esigenze in pochissimo tempo chiedendo all’IA di leggere le specifiche e di “scriverlo in base alla disposizione delle colonne del mio foglio di calcolo”.

Punti da verificare durante l’implementazione

Ecco gli errori più comuni in cui è facile incorrere, tratti direttamente dalle guide agli scenari.

• PUT esegue una “sostituzione completa”: Se aggiorni un contatto con il metodo PUT, tutti i campi che non hai incluso nella richiesta verranno cancellati. Recupera prima i dati aggiornati con GET e usali come base, modificando solo le parti che desideri cambiare prima di effettuare l’invio
• Il parametro __v (versione) è obbligatorio: Per le chiamate PUT e per le richieste PATCH su campagne e liste, devi includere il valore __v appena recuperato tramite GET. Se usi un valore obsoleto, riceverai un errore ConcurrencyError (400), quindi dovrai ripetere il recupero dei dati e riprovare
• Gli stati fanno distinzione tra maiuscole e minuscole (case-sensitive): Valori come Active, Inactive e Unsubscribe devono essere inviati esattamente in questa forma; l’uso di caratteri minuscoli provocherà un errore. Quando imposti Inactive, sono richiesti sia primary che secondary
• I contatti disiscritti o rimbalzati non possono essere ripristinati: Una volta che un contatto assume lo stato Inactive, non può tornare a essere Active tramite API. Si tratta di una regola progettata per tutelare la conformità normativa, quindi la premessa di base è non tentare di riattivarli autonomamente
• I duplicati generano errori: Se lo stesso indirizzo email esiste già all’interno della stessa struttura, riceverai l’errore DuplicateFieldError. Esegui un controllo tramite ricerca prima di procedere alla creazione, oppure gestisci l’errore passando a un aggiornamento
• L’attributo source nella ricerca è obbligatorio: Specifica i campi che desideri ricevere sotto forma di array, ad esempio _id, key e fields. I valori sono case-sensitive e, se viene incluso anche un solo valore sconosciuto, l’intera richiesta verrà respinta
• Il recupero delle liste contatti non prevede la paginazione: L’endpoint GET /api/contact restituisce tutti i record in un’unica soluzione, quindi per account con un elevato volume di dati l’utilizzo dell’API di ricerca (dotata di paginazione) risulta più sicuro
• L’indirizzo mittente deve appartenere a un dominio autenticato: Il parametro from di una campagna deve corrispondere a un indirizzo configurato su un dominio di invio autenticato
• Gestisci sempre le chiavi tramite variabili d’ambiente o proprietà di script: Evita di inserirle direttamente nel codice sorgente o nelle celle dei fogli di calcolo. Se sospetti una fuga di dati, disattiva e rigenera immediatamente la chiave

Vantaggi e precauzioni dell’API di Benchmark Email

A chi è rivolta (e a chi no)

A chi è adatta

• I dati dei tuoi clienti si trovano in più punti (come sito e-commerce, sistema di prenotazione, CRM e fogli di calcolo) e perdi tempo a incrociare i record manualmente
• Hai a disposizione uno sviluppatore o puoi delegare l’implementazione a un assistente di codifica IA
• Desideri visualizzare i risultati delle consegne all’interno della tua dashboard personale o di uno strumento di BI
• Invii email con la stessa struttura a cadenza mensile e vuoi automatizzare esclusivamente la preparazione della bozza

A chi NON è adatta

• Le tue attività si esauriscono interamente all’interno dell’interfaccia di Benchmark Email e non hai alcuna necessità di integrazione con tool esterni
• Cerchi configurazioni interamente no-code e basate solo su clic (al momento ciò richiede l’implementazione di richieste HTTP in strumenti esterni come Zapier)
• Vuoi gestire l’invio effettivo delle email direttamente dall’API (lo strumento non è pensato per utilizzi di tipo transactional email)

Domande frequenti (FAQ)

D. Posso usare l’API sul piano gratuito di Benchmark Email?

Sì. L’API è inclusa gratuitamente in tutti i piani. Nel piano gratuito puoi creare fino a 2 chiavi API attive.

D. Posso usarla senza conoscenze di programmazione?

È necessario scrivere o generare del codice per l’integrazione. Anche se non sai scrivere codice in autonomia, puoi raggiungere l’obiettivo affidandoti a uno sviluppatore o utilizzando un assistente di codifica basato su IA.

D. Posso inviare email tramite l’API?

Non direttamente. La creazione, la configurazione e la duplicazione delle campagne sono possibili tramite API, ma la pianificazione e l’invio devono essere effettuati dall’interfaccia di Benchmark Email.

D. Dove posso creare una chiave API?

Accedendo con un account dotato di permessi di proprietario, puoi crearla dalla sezione Impostazioni > Chiavi API. La chiave viene mostrata una sola volta al momento della creazione, quindi assicurati di copiarla subito.

D. Quali sono i limiti di velocità (rate limits)?

In base alla documentazione per sviluppatori, il limite è di 3.600 richieste all’ora per account (considerando il totale tra più chiavi), mentre la quota mensile corrisponde a 10 volte il limite dei contatti (piano gratuito) o a 100 volte (piani a pagamento). Questi valori potrebbero subire variazioni, pertanto ti invitiamo a verificare le informazioni più recenti nella sezione “Rate Limits” della documentazione.

D. Possono effettuare un’integrazione con Google Sheets?

Non esiste un connettore ufficiale, ma puoi integrarlo richiamando l’API tramite UrlFetchApp da Google Apps Script. Come mostrato negli Esempi 1 e 2 di questo articolo, puoi registrare contatti da un foglio di calcolo ed estrarre i risultati di recapito.

Riepilogo

L’API di Benchmark Email è uno strumento gratuito su tutti i piani che permette di connettere contatti, liste, campagne, report e domini di invio a software esterni.

• Ti consente di automatizzare il lavoro manuale di trasferimento dei dati, come la sincronizzazione dei contatti, la ricerca, il controllo dei duplicati, la gestione delle liste e il recupero dei report
• D’altra parte, l’invio, la pianificazione e la formattazione finale non possono essere gestiti tramite API e, per motivi di sicurezza, richiedono sempre una verifica manuale nell’interfaccia
• Per utilizzarla è richiesto il supporto di uno sviluppatore o di un tool di IA, ma grazie alla presenza di file come llms.txt e SKILL.md forniti dal team ufficiale, la barriera d’ingresso si riduce notevolmente se si sceglie di delegare la scrittura del codice all’intelligenza artificiale
• Sfruttando Google Sheets tramite Google Apps Script, puoi realizzare la registrazione automatica delle liste di iscrizione e l’aggregazione automatica dei risultati di recapito

Per iniziare, crea una chiave API sul piano gratuito, effettua una chiamata a GET /api/contact-structure e verifica la struttura del tuo account. Dopodiché, ti consiglio di iniziare automatizzando l’attività che richiede il maggior dispendio di tempo, come la sincronizzazione dei fogli di calcolo.

Link di riferimento

• API di Benchmark Email (pagina ufficiale della funzionalità)