Documentazione per sviluppatori

Per cominciare

1. Crea un account e un brand, poi verifica il dominio da cui vuoi inviare.
2. In console crea una API key per quel brand e scegli le capacità che le servono. Le capacità non si modificano dopo: per cambiarle crei una chiave nuova.
3. Chiama l'API con la chiave nell'intestazione Authorization.

Indirizzo base

https://api.mailronix.com

Autenticazione

Authorization: Bearer mrx_live_…

Il primo invio

Il mittente deve stare sul dominio verificato del brand a cui è legata la chiave. La risposta 202 significa che il messaggio è in coda, non che è stato recapitato.

curl -X POST https://api.mailronix.com/email/send \
  -H "Authorization: Bearer mrx_live_<la-tua-chiave>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ordine-4821" \
  -d '{
    "from": "notifiche@cliente-esempio.com",
    "to": "utente@destinatario.com",
    "subject": "Conferma ordine #4821",
    "html_body": "<p>Il tuo ordine #4821 è confermato.</p>"
  }'

Lo stesso invio in Node.js, senza dipendenze:

const risposta = await fetch('https://api.mailronix.com/email/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MAILRONIX_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'ordine-4821',
  },
  body: JSON.stringify({
    from: 'notifiche@cliente-esempio.com',
    to: 'utente@destinatario.com',
    subject: 'Conferma ordine #4821',
    html_body: '<p>Il tuo ordine #4821 è confermato.</p>',
  }),
})

if (!risposta.ok) {
  const { error } = await risposta.json()
  throw new Error(`${error.code}: ${error.message}`)
}
console.log(await risposta.json()) // { status: 'queued', email_log_id: '…' }

Risposta

202 Accepted
{ "status": "queued", "email_log_id": "9c4e2f1a-7d3b-4a5e-8f6c-1b2a3d4e5f6a" }

Per ritentare senza rischio di duplicati manda l'intestazione Idempotency-Key: un nuovo invio con la stessa chiave e lo stesso corpo, entro 24 ore, restituisce la risposta della prima chiamata.

Nome del mittente, risposte e allegati

Tre campi facoltativi di POST /email/send. Chi non li manda ottiene lo stesso comportamento di prima.

Esempio con i tre campi

{
  "from": "notifiche@cliente-esempio.com",
  "from_name": "Acme Assistenza",
  "reply_to": "supporto@altro-dominio.com",
  "to": "utente@destinatario.com",
  "subject": "La tua fattura",
  "html_body": "<p>In allegato la fattura.</p>",
  "attachments": [
    {
      "filename": "fattura-2026-0412.pdf",
      "content_type": "application/pdf",
      "content": "JVBERi0xLjcK…"
    }
  ]
}

• from_name: il nome che il destinatario legge al posto dell'indirizzo, da 1 a 78 caratteri (gli accenti vanno bene; niente @, < >, virgolette, a capo o indirizzi web). Se manca si usa il nome impostato sul brand.
• reply_to: l'indirizzo a cui vanno le risposte, su qualunque dominio tranne quello di Mailronix. Va abilitato dalla console, nelle impostazioni del brand, con «Consenti reply_to nella richiesta»: è spento di default e non si attiva con una API key, perché una chiave rubata non deve poter reindirizzare le risposte (senza consenso la risposta è 403 reply_to_not_allowed).
• attachments: fino a 5 allegati per messaggio, 7 MB di file in totale e l'email completa sotto i 10 MB (in email gli allegati pesano circa un terzo in più). Tipi ammessi: PDF, PNG, JPEG, GIF, testo, CSV e calendario. Solo su messaggi transazionali, su tutti i piani: con "marketing": true la risposta è 400 attachments_not_allowed_for_marketing.
• Gli allegati restano da noi solo il tempo dell'invio e comunque non oltre 24 ore; nel log del messaggio restano nome, tipo, dimensione e impronta, mai il contenuto. Non c'è scansione antivirus: il contenuto è responsabilità tua. Per ritentare con la stessa Idempotency-Key rimanda gli stessi byte.

Cosa può fare una chiave

Ogni chiave porta solo le capacità scelte alla creazione. Senza la capacità giusta l'API risponde 403 capability_not_granted.

POST /email/send

Invia un'email transazionale, con contenuto diretto o da template con variabili.

Capacità: email:send

GET /email/{id}

Legge lo stato di un invio.

Capacità: email:read

POST /contacts

Crea un contatto. Nasce non confermato: la richiesta di conferma parte da Mailronix.

Capacità: contacts:write

POST /contacts/revoke

Registra la disiscrizione di un indirizzo.

Capacità: contacts:unsubscribe

POST /contacts/delete

Cancella un contatto. Richiede anche la capacità di disiscrizione.

Capacità: contacts:delete

GET /contacts/revocations

Elenca le revoche del brand della chiave, a cursore.

Capacità: revocations:read

Regole da conoscere

• Una chiave scrive sempre e solo sotto il brand a cui è stata legata alla creazione. Se hai più brand, crei una chiave per brand.
• Un messaggio è transazionale per impostazione predefinita. Con "marketing": true parte solo verso contatti che hanno confermato l'iscrizione, e porta il link di disiscrizione.
• Non puoi dichiarare un consenso raccolto altrove: il consenso vale solo se il destinatario lo conferma con il suo click.
• language (facoltativo, su POST /email/send e POST /contacts): it, en, es, de o fr. Sceglie la lingua dei testi di servizio e delle pagine collegate; non traduce HTML né template. Senza il campo vale la lingua del brand; un altro valore produce 400 invalid_language.
• Gli errori hanno sempre la stessa forma, con un codice stabile da leggere con il programma e un messaggio per le persone.
• Il limite di richieste è per chiave (429 rate_limited). Esaurita la quota mensile del piano, gli invii sono rifiutati (403 plan_limit_exceeded) fino al mese di calendario UTC successivo; il piano Free ha anche un limite di 500 destinatari unici al giorno.

{ "error": { "code": "rate_limited", "message": "…" } }

Cosa non si fa via API

Campagne, creazione e revoca delle API key, template, configurazione dei webhook e fatturazione si gestiscono solo dalla console, con una sessione. È una scelta di sicurezza: una chiave rubata non deve poter creare credenziali né reindirizzare i dati dei tuoi invii.

Riferimento API

Ogni endpoint, campo e risposta, generati dalla specifica e leggibili senza scaricarla.

Specifica OpenAPI

La specifica OpenAPI 3.1 descrive ogni endpoint, campo ed errore: importala nel tuo client o nel tuo strumento di prova. È scritta in italiano.

Webhook in uscita

Per non fare polling puoi registrare dalla console indirizzi HTTPS a cui Mailronix invia gli eventi del tuo account, con firma HMAC e tentativi automatici.