mailinapp
Documentation menu

Riferimento API

POST /api/v1/send è l'intera Send API transazionale — un unico endpoint versionato e stabile. A differenza del resto delle rotte di MailInApp (che hanno sempre e solo il nostro stesso frontend come chiamante e possono cambiare liberamente), questo è un contratto da cui dipende codice di terze parti, quindi è versionato fin dal primo giorno.

Autenticazione

Authorization: Bearer mia_live_...

Una chiave mancante o non valida restituisce 401. Le chiavi si gestiscono sotto Sviluppatori nella dashboard — vedi la guida rapida. Una chiave revocata smette di funzionare immediatamente.

Richiesta

Content-Type: application/json. Due forme di richiesta condividono l'endpoint — quale delle due si applica viene deciso dalla presenza o meno di projectId.

Libero

| Campo | Tipo | Obbligatorio | Note | | --- | --- | --- | --- | | to | string | sì | Un singolo indirizzo destinatario. | | subject | string | sì | Troncato a 200 caratteri. | | html | string | sì | Inviato così com'è — nessun rendering, nessun tag di personalizzazione, nessuna pipeline dello Studio. | | text | string | sì | Parte in testo semplice. |

Modello

| Campo | Tipo | Obbligatorio | Note | | --- | --- | --- | --- | | to | string | sì | Un singolo indirizzo destinatario. | | projectId | string | sì | Deve essere un progetto che possiedi — l'URL dello Studio è /studio/<projectId>. | | mergeData | object | no | Oggetto piatto { chiave: valore }, fino a 100 campi. Sostituisce una riga di fonte dati — si risolve nei tag di personalizzazione {{field}} del progetto. Oggetti/array annidati vengono scartati; null/undefined diventano stringhe vuote; tutto il resto viene convertito in stringa. | | subject | string | no | Per impostazione predefinita è il nome del progetto se omesso. I tag di personalizzazione nell'oggetto si risolvono da mergeData. Troncato a 200 caratteri. |

Un corpo che non corrisponde a nessuna delle due forme (ad es. to mancante, oppure sia html/text sia projectId mancanti) restituisce 400.

Campi comuni

| Campo | Tipo | Obbligatorio | Note | | --- | --- | --- | --- | | type | "transactional" | "marketing" | no | Per impostazione predefinita "transactional". Vedi sotto. | | from | object | no | Sovrascrittura per chiamata dell'indirizzo/nome del mittente — { "email": string, "name"?: string }. Vedi sotto. | | senderId | string | no | Sovrascrittura per chiamata scegliendo una delle identità del mittente salvate del tuo account, invece di scrivere from in linea. Deve appartenere al tuo account, altrimenti 400. from prevale se sono forniti entrambi. | | replyTo | string | no | Indirizzo Reply-To per chiamata. Vedi sotto. |

Intestazioni

| Intestazione | Obbligatorio | Note | | --- | --- | --- | | Authorization | sì | Bearer <apiKey>. | | Idempotency-Key | no | Vedi idempotenza. |

Risposta

{ "id": "abc123", "status": "sent" }

status è uno dei seguenti:

| Stato | Significato | | --- | --- | | sent | Consegnato con successo al tuo metodo di invio (relay SMTP o invio nativo). | | suppressed | Il destinatario è nella tua lista di soppressione — vedi transazionale vs. marketing. Nessuna email è stata inviata; non è un errore. | | failed | Il tentativo di invio è fallito (ad es. il tuo relay SMTP non è configurato, oppure ha rifiutato il messaggio). Un campo error riporta un motivo leggibile da un essere umano. |

Codici di errore

| Stato | Significato | | --- | --- | | 400 | JSON malformato, una richiesta che non corrisponde né alla forma libera né a quella modello, un type non valido, un from non valido o non consentito (vedi Indirizzo mittente), un replyTo non valido, oppure (modalità modello) un projectId che non esiste o non è tuo. Restituito anche quando l'account non ha alcun metodo di invio funzionante configurato. | | 401 | Intestazione Authorization mancante o non valida, oppure la chiave è stata revocata. | | 404 | (Modalità modello) il progetto non esiste o non appartiene al tuo account — deliberatamente la stessa risposta di "non esiste" per evitare di rivelare quali ID di progetto siano validi per altri account. | | 429 | Limite di velocità superato — vedi limiti di velocità. |

Un 200 con status: "failed" (anziché uno stato non-2xx) viene restituito quando la richiesta stessa era valida ma il tentativo di invio effettivo è fallito a valle. Se devi distinguere "abbiamo rifiutato la tua richiesta" da "abbiamo provato e non è partita", controlla status nel corpo della risposta, non solo il codice di stato HTTP.

Transazionale vs. marketing

Il campo type controlla quale lista di soppressione viene verificata, rispecchiando il modo in cui gli ESP separano i flussi transazionali e marketing:

  • type: "transactional" (predefinito) — bypassa la soppressione da disiscrizione. Un reset della password o una ricevuta d'ordine non dovrebbero essere bloccati solo perché il destinatario si è disiscritto dalla tua newsletter. Non bypassa mai la soppressione da bounce — un indirizzo morto resta morto a prescindere dall'intento.
  • type: "marketing" — si comporta esattamente come un invio di campagna dalla dashboard: bloccato sia dalla soppressione da disiscrizione sia da quella da bounce.

In entrambi i casi viene restituito status: "suppressed" invece di un errore quando il messaggio viene bloccato.

Indirizzo mittente

Per impostazione predefinita, ogni invio usa l'identità del mittente configurata del tuo account — la scheda "Indirizzo mittente" di Impostazioni → Domini se usi l'invio nativo (SES), oppure l'indirizzo mittente configurato del tuo relay SMTP altrimenti. Passa from per sovrascriverlo per una chiamata:

{
  "to": "[email protected]",
  "subject": "Your one-time code",
  "html": "<p>Your code is 123456</p>",
  "text": "Your code is 123456",
  "from": { "email": "[email protected]", "name": "FitConsent Sales Team" }
}

from.email è obbligatorio ogni volta che from è presente — non esiste una sovrascrittura del solo nome, quindi un valore qui sostituisce sempre completamente sia l'indirizzo sia il nome visualizzato per quella chiamata. from.name è facoltativo; omettilo per inviare con il solo indirizzo nudo.

Se il tuo account invia tramite un dominio verificato (invio nativo/SES), from.email deve essere un indirizzo su uno dei tuoi domini di invio verificati (ad es. [email protected], non [email protected]) — un account può verificare più di un dominio, quindi uno qualsiasi di essi è consentito, ma mai quello di qualcun altro. L'invio nativo funziona su un unico account AWS della piattaforma condiviso tra tutti i clienti MailInApp, quindi questa restrizione è ciò che impedisce a un account di inviare posta che sembri provenire dal dominio verificato di un account diverso. Sull'invio SMTP non c'è una restrizione del genere: l'invio parte tramite il tuo stesso relay/le tue stesse credenziali, quindi è già affidabile allo stesso modo in cui lo sono già le regole di verifica del mittente del tuo stesso relay.

senderId (vedi la tabella dei campi comuni sopra) è di solito la scelta più semplice quando hai già configurato un'identità del mittente nella dashboard. Si risolve nel proprio {email, name, reply-to} di quell'identità senza doverli ripetere a ogni chiamata.

Un from non valido o non consentito restituisce 400 prima che venga tentato qualsiasi invio.

Indirizzo di risposta (Reply-To)

Per impostazione predefinita, le risposte vanno all'indirizzo Reply-To predefinito configurato del tuo account, impostato nella pagina Invio o Domini sotto Impostazioni a seconda del tuo metodo di invio, oppure da nessuna parte se non ne hai impostato uno. Passa replyTo per sovrascriverlo per una chiamata — utile quando il from visibile è un indirizzo no-reply ma vuoi comunque che una persona veda le risposte:

{
  "to": "[email protected]",
  "subject": "Your order shipped",
  "html": "<p>Your order is on its way.</p>",
  "text": "Your order is on its way.",
  "from": { "email": "[email protected]", "name": "FitConsent" },
  "replyTo": "[email protected]"
}

A differenza di from.email, replyTo non ha alcuna restrizione di dominio sull'invio nativo (SES) — non influisce mai sull'identità di invio né sulla reputazione di consegna, è solo un'intestazione che il client di posta del destinatario rispetta quando risponde. Un replyTo non valido restituisce 400 prima che venga tentato qualsiasi invio.

Idempotenza

Passa un'intestazione Idempotency-Key su qualsiasi chiamata che potrebbe essere ritentata — una riconsegna di un webhook di checkout, un consumer di coda che rielabora un messaggio. Una chiamata ritentata con la stessa chiave per lo stesso account restituisce il {id, status} della chiamata originale senza inviare una seconda email, anche se la prima chiamata è ancora in corso.

Le chiavi sono associate a ogni account e non hanno scadenza; riutilizzare una chiave già usata per un payload diverso è una responsabilità tua da evitare (restituirà comunque il risultato della prima chiamata, senza inviare il nuovo payload). Se non passi una chiave, ogni chiamata invia.

Limiti di velocità

Si applicano tre limiti indipendenti:

  • Per Chiave API: un limite di richieste al minuto. Superarlo restituisce 429 specificamente per quella chiave — le altre chiavi sullo stesso account non sono interessate.
  • Per account, quota della Send API: il tuo piano include un numero di chiamate alla Send API per mese di calendario (500/mese su Free). Superarla restituisce 429 finché la quota non si azzera il giorno 1.
  • Per account, volume di invio: il limite cumulativo mensile del volume di invio del tuo piano, condiviso tra tutti i percorsi di invio (invii dalla dashboard, invii pianificati, email di ciclo di vita, e questa API). È lo stesso limite che protegge il resto dell'invio del tuo account — la Send API non ha un budget separato.

Specificità della modalità modello

Un invio in modalità modello renderizza il progetto collegato esattamente come un normale invio a un destinatario: i tre livelli del motore di fallback, i blocchi interattivi, e un link della vista live personale e firmato costruito a partire da mergeData piuttosto che da una riga di contatto memorizzata. Tutto ciò che segue si comporta come un invio guidato dallo Studio:

  • Voti dei sondaggi, valutazioni, invii di moduli e aperture vengono registrati e compaiono nella vista Risposte del progetto, attribuiti a questa specifica chiamata API piuttosto che a una riga di contatto.
  • Il webhook del tuo progetto si attiva per ogni evento di interazione, come per qualsiasi altro destinatario.
  • Le chiamate recenti (stato, destinatario, timestamp) sono elencate nella pagina dashboard Sviluppatori come traccia di audit.

L'unica cosa che differisce da un invio dalla dashboard: non c'è alcuna riga di fonte dati memorizzata dietro l'interazione, quindi i join dal tuo lato dovrebbero basarsi sull'identificatore del destinatario della risposta piuttosto che su un indice di riga.