Un API per email in entrata riceve la posta inviata a un indirizzo o dominio di tua proprietà, la analizza e la consegna alla tua applicazione come POST HTTP strutturato. Invece di gestire un mail server e interrogare una casella di posta via IMAP, punti i record MX del tuo dominio al provider, e ogni messaggio in arrivo raggiunge il tuo endpoint con header, corpo e allegati già analizzati in JSON.
Come funziona l'email in entrata?
L'instradamento parte dal DNS. Imposti i record MX per un dominio o sottodominio (ad esempio reply.yourapp.com) in modo che puntino ai mail server del provider inbound. Quando qualcuno invia un messaggio a qualsiasi indirizzo di quel dominio, il messaggio arriva sull'infrastruttura del provider anziché sulla tua. Il provider accetta il messaggio, lo analizza e invia una richiesta POST a un URL che hai registrato, con il contenuto già analizzato.
Un payload analizzato include tipicamente mittente e destinatario, l'oggetto, il corpo in testo semplice e HTML, l'insieme completo degli header e gli eventuali allegati (spesso codificati in base64 o referenziati tramite URL). La tua app legge quel JSON e agisce di conseguenza, senza codice SMTP o IMAP da mantenere. Il meccanismo di consegna è un webhook, quindi valgono le stesse regole: rispondi con un rapido 2xx, poi elabora il messaggio in modo asincrono.
A cosa serve?
L'email in entrata trasforma i messaggi ricevuti in eventi applicativi. I pattern più comuni includono:
- Gestione delle risposte. Invii una notifica da
notifications@yourapp.come, quando un utente risponde, la risposta arriva come POST così puoi collegarla alla conversazione originale. - Ticketing di supporto. La posta inviata a
support@yourapp.comdiventa un nuovo ticket, con mittente e corpo mappati direttamente nel tuo help desk. - Parse to database. Ricevute inoltrate o email strutturate vengono analizzate e scritte in una tabella, senza inserimento manuale.
- Email to action. Un messaggio inviato a un indirizzo specifico attiva un workflow: crea un record, avvia un job, pubblica su un canale.
In cosa si differenzia dall'invio di email?
Outbound e inbound sono compiti separati. L'outbound è la tua app che consegna posta ai destinatari tramite SMTP o un HTTP send API. L'inbound è il contrario: mittenti esterni che consegnano posta alla tua app. Un'integrazione email completa di solito fa entrambe le cose, invia notifiche e riceve le risposte, ma le due parti si configurano in modo indipendente e il lato inbound è quello che dipende dai tuoi record MX.
Perché non interrogare una casella di posta via IMAP?
Puoi eseguire un poller IMAP su una casella reale, ma comporta costi continui. Gestisci le credenziali, decidi la frequenza di polling (che aggiunge latenza e connessioni inattive), analizzi il MIME grezzo da solo e tieni traccia dei messaggi già elaborati. Un API inbound elimina gran parte di tutto questo: il provider analizza il MIME, invia ogni messaggio una sola volta come JSON pulito e tu reagisci quasi in tempo reale. Per un confronto tra i protocolli sottostanti, vedi SMTP vs. IMAP.
Domande frequenti
Quali modifiche DNS servono?
Imposti i record MX per il dominio o sottodominio su cui vuoi ricevere posta in modo che puntino al tuo provider inbound. Dopo la propagazione, la posta indirizzata a qualsiasi indirizzo di quel dominio viene instradata al provider, che la analizza e la invia al tuo endpoint. Usare un sottodominio dedicato mantiene l'instradamento inbound separato dalla posta del dominio principale.
Come vengono gestiti gli allegati?
Il payload analizzato include gli allegati, di solito codificati in base64 inline oppure come URL da scaricare separatamente. Il tuo handler li decodifica o li scarica e li salva dove conservi i file. Gli allegati più grandi sono tipicamente referenziati tramite URL per mantenere il payload leggero.
L'email in entrata è la stessa cosa di un webhook?
La consegna usa un webhook: il provider invia alla tua app un POST HTTP per ogni messaggio. La differenza è che il payload è un'email completamente analizzata anziché un evento generico. Trattalo come qualsiasi webhook: verificalo, rispondi rapidamente ed elabora in modo asincrono.
Per vedere come Bird gestisce entrambe le direzioni dell'email, parti dalla panoramica del prodotto email e dalla guida agli eventi email, che copre il modello di consegna degli eventi su cui si baserà il tuo handler inbound.