API

Riferimento API REST

Tutti gli endpoint, i parametri, le richieste e le risposte di esempio. Autenticazione: chiave API (Bearer).

Esempio rapido

curl https://api.sendnomi.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Welcome",
    "html": "<h1>Hello!</h1>"
  }'

La chiave API si ottiene dal pannello → scheda Sviluppatore. Per gli ambienti di produzione e di test consigliamo chiavi separate con scope dedicati.

Autenticazione

Ogni richiesta include un header Authorization: Bearer YOUR_API_KEY. Le chiavi si creano nel pannello, vengono mostrate una sola volta alla creazione e poi salvate come hash. Se perdi una chiave, ne generi una nuova e revochi la vecchia — la chiave revocata viene disattivata all'istante.

  • Permessi basati su scope: 30 scope (send · campaign · template · webhook · domain · ...). Una chiave accede solo alle aree che autorizzi.
  • Allowlist IP: puoi limitare le chiavi di produzione a specifici intervalli IP/CIDR.
  • Limite temporale: puoi assegnare un TTL alle chiavi; alla scadenza si disattivano automaticamente.
  • Log di audit: ogni utilizzo della chiave viene registrato con timestamp + endpoint + esito.

Idempotency-Key

Usa l'header Idempotency-Key nelle richieste POST — una seconda richiesta con la stessa chiave restituisce di nuovo la prima risposta, senza invii duplicati. Consigliato UUIDv4; la chiave viene conservata per 24 ore. 

curl https://api.sendnomi.com/v1/messages \
  -H "Authorization: Bearer sn_live_•••" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-..." \
  ...

Formato degli errori

Tutte le risposte di errore condividono lo stesso envelope — codice + messaggio + dettaglio specifico della richiesta:

{
  "error": {
    "code":    "invalid_recipient",
    "message": "Recipient address does not match the format rule",
    "field":   "to",
    "request_id": "req_01HX8K..."
  }
}

Gli status code HTTP seguono la RFC 7231. Gli errori temporanei sono 5xx + retry-after; gli errori permanenti 4xx non sono soggetti a retry.

Rate limit

Il limite dipende dal tuo piano ed è mostrato in tempo reale nel pannello. Ogni risposta include gli header:

  • X-RateLimit-Limit · richieste consentite nella finestra
  • X-RateLimit-Remaining · richieste ancora disponibili
  • X-RateLimit-Reset · quando la finestra si azzera (Unix epoch)

Se ricevi un 429, attendi per la durata indicata nell'header Retry-After. Gli SDK lo fanno automaticamente.

Versioning

La versione è obbligatoria nell'URL (/v1/). Il passaggio a una nuova versione prevede una finestra di deprecazione di 12 mesi + avviso nel changelog. Le breaking change non vengono mai rilasciate in silenzio — non appena usi un endpoint deprecato, ricevi un header di avviso.

Elenco degli endpoint

  • POST /v1/messages Invia una email singola o in blocco.
  • GET /v1/messages/{id} Interroga lo stato di un messaggio specifico.
  • GET /v1/messages Elenco dei messaggi, con filtri e paginazione.
  • POST /v1/templates Crea un nuovo template (mix Handlebars + Liquid).
  • GET /v1/templates/{id} Dettaglio del template.
  • POST /v1/suppressions Aggiungi un indirizzo alla lista di soppressione.
  • GET /v1/suppressions Lista di soppressione.
  • POST /v1/webhooks Registra un endpoint webhook.
  • GET /v1/events Flusso eventi (sent, delivered, opened, clicked, bounced, complained).
  • GET /v1/domains I tuoi domini verificati.

Spec OpenAPI 3.1: /v1/openapi.json — per l'import in IDE / Postman. Ogni endpoint è documentato con tutti i parametri, la richiesta di esempio e lo schema di risposta.