Guida rapida

La Send API transazionale permette al tuo backend di attivare l'invio di un'email — nello stesso modo in cui chiameresti l'endpoint di invio di Brevo, SendGrid o Postmark. È una soluzione naturale per OTP, ricevute e avvisi, e può anche attivare un progetto che hai progettato nello Studio, con i tuoi dati al posto di una riga di contatto.

Genera una chiave

Sotto Sviluppatori nella dashboard, premi Crea chiave e dalle un nome (ad es. "Backend di produzione", "Staging"). La chiave completa — mia_live_... — viene mostrata esattamente una volta. Conservala in un posto sicuro; MailInApp conserva solo un hash, quindi non c'è modo di recuperarla di nuovo. Se la perdi, revocala e generane una nuova.

Le chiavi sono associate al tuo account, non a un singolo progetto — una chiave può attivare qualsiasi progetto tu possieda. Creane quante ne vuoi (una per ambiente o integrazione è uno schema comune) e revocane una qualsiasi in modo indipendente in qualsiasi momento.

Invio n. 1: libero

Per una semplice email transazionale — senza coinvolgere alcun progetto dello Studio — fornisci tu stesso l'HTML e il testo:

curl -X POST https://mailinapp.com/api/v1/send \
  -H "Authorization: Bearer mia_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Your one-time code",
    "html": "<p>Your code is 123456</p>",
    "text": "Your code is 123456"
  }'

Una chiamata riuscita restituisce:

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

Invio n. 2: modello

Questo è il vero elemento differenziante: progetta visivamente un'email nello Studio — motore di fallback, blocchi interattivi, tag di personalizzazione — poi attivala dal tuo stesso codice di registrazione, checkout o supporto, con mergeData al posto di una riga di fonte dati:

curl -X POST https://mailinapp.com/api/v1/send \
  -H "Authorization: Bearer mia_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_12345" \
  -d '{
    "to": "[email protected]",
    "projectId": "your-project-id",
    "mergeData": { "name": "Ada", "orderId": "12345" }
  }'

Trova projectId nell'URL dello Studio per il progetto (/studio/<projectId>). I campi di mergeData si risolvono nei tag di personalizzazione {{field}} del progetto esattamente come farebbe una riga di contatto. Il destinatario riceve un link della vista live personale e firmato come per qualsiasi altro invio — i blocchi interattivi (sondaggi, valutazioni, moduli) funzionano, e ogni risposta confluisce nella normale vista Risposte di quel progetto e nelle consegne webhook, attribuita a questa specifica chiamata API.

L'intestazione Idempotency-Key è facoltativa ma consigliata per qualsiasi cosa attivata da un'operazione che può essere ritentata (un webhook di checkout, un consumer di coda) — vedi idempotenza nel riferimento API.

Sovrascrivere il mittente

Entrambi i tipi di invio usano per impostazione predefinita 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. Aggiungi from per sovrascriverlo per una chiamata, ad es. un account multi-brand che invia come un team specifico:

curl -X POST https://mailinapp.com/api/v1/send \
  -H "Authorization: Bearer mia_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "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": "Your Sales Team" }
  }'

from.email è obbligatorio ogni volta che from è presente (nessuna sovrascrittura del solo nome); from.name è facoltativo. Sull'invio nativo (SES), from.email deve essere un indirizzo su uno dei tuoi domini verificati — vedi Indirizzo mittente nel riferimento API per il motivo, e per la regola più permissiva dell'SMTP.

Se hai già salvato un'identità del mittente nella dashboard, passa il suo id come senderId invece di ripetere l'indirizzo/nome in linea — vedi il riferimento API per entrambi i campi.

Prossimi passi

• Forme complete di richiesta/risposta, semantica di type, limiti di velocità e codici di errore: riferimento API.
• Le chiamate recenti effettuate con le tue chiavi — incluso lo stato ed eventuali errori — compaiono nella pagina Sviluppatori a scopo di audit.
• Non hai un relay SMTP esistente? L'invio nativo permette a MailInApp di consegnare per tuo conto, una volta che il tuo dominio è stato messo in whitelist e verificato.
• Vuoi che un agente IA costruisca o modifichi le tue email invece di chiamare direttamente l'API? La stessa chiave autentica anche il server MCP, così Claude Desktop, Claude Code, o qualsiasi altro client MCP può farlo per te via chat.