Caselle di posta per agenti

Una casella di posta per agenti è una inbox indirizzabile che il tuo codice gestisce tramite la API. Leggi e filtra i suoi thread, rispondi ai messaggi o componi nuova posta senza eseguire un server IMAP né analizzare MIME grezzo.

Una casella di posta risiede sul dominio condiviso inbox.ai oppure su un tuo dominio di invio abilitato alla ricezione. Il suo indirizzo viene riservato nel momento in cui la crei e resta tuo: la parte locale è riservata al tuo spazio di lavoro e non viene mai assegnata a nessun altro, nemmeno dopo l'eliminazione della casella.

Indirizzi

Ogni casella di posta ha un indirizzo, {local_part}@inbox.ai. Puoi ottenere un indirizzo in due modi:

Generato: ometti la parte locale e ne generiamo una priva di collisioni per te (a7f3k2@inbox.ai). Sempre disponibile.
Personalizzato: richiedi una parte locale specifica (support@inbox.ai). Gli handle personalizzati sono globalmente univoci, assegnati in ordine di arrivo e inclusi nelle quote del piano a pagamento; uno spazio di lavoro gratuito usa indirizzi generati.

Un indirizzo è immutabile una volta creato. Per cambiarlo, crea una nuova casella ed elimina quella vecchia. La parte locale precedente viene mantenuta per 30 giorni (la sua finestra di ripristino) prima di poter essere reclamata di nuovo, e resta riservata al tuo spazio di lavoro.

Thread e messaggi

La posta ricevuta e inviata è raggruppata in thread, uno per conversazione. Un thread contiene gli indirizzi partecipanti, un contatore di non letti, la direzione dell'ultimo messaggio (inbound o outbound) e il timestamp dell'attività più recente. Le risposte confluiscono nel thread a cui rispondono; un nuovo messaggio composto apre un nuovo thread.

Ogni messaggio espone gli header, il testo in chiaro estratto con la cronologia delle citazioni rimossa e gli allegati. I body originali sono disponibili per 30 giorni; il MIME grezzo è disponibile solo per i messaggi ricevuti. Gli ID dei messaggi sono prefissati in base alla direzione: rem_ per un messaggio ricevuto, em_ per uno inviato.

Decidere cosa entra

Due controlli precedono la inbox, entrambi verificati rispetto al mittente dell'envelope anziché all'header From: falsificabile:

Criterio di ricezione: il default a livello di casella.
- open accetta tutto ciò che supera l'autenticazione.
- replies_only accetta solo la posta che prosegue un thread già presente nella casella.
- allowlist accetta solo i mittenti consentiti dalle tue regole, più le risposte a un thread esistente.
- drop scarta tutto, senza eccezioni.
Regole di ricezione: voci di consenso o blocco per mittente, abbinate a un indirizzo completo o a un dominio (una regola su dominio copre anche i suoi sottodomini). Un blocco prevale sempre su un consenso.

La posta bloccata da una regola, o che non supera DMARC, viene comunque archiviata nella casella e resta leggibile: è archiviata fuori dalla inbox anziché eliminata e non attiva alcun webhook. L'unica eccezione è una casella impostata su drop, che scarta tutto alla porta anziché archiviarlo.

Invio

Una casella di posta invia in due modi tramite la API: rispondi a un messaggio (il messaggio in uscita confluisce nel thread corrispondente) oppure componi un nuovo messaggio (che apre un nuovo thread). Nella dashboard, apri un messaggio e scegli Inoltra per inviare il body originale e gli allegati a nuovi destinatari, entro la finestra di 30 giorni del contenuto originale. La posta viene inviata dall'indirizzo della casella stessa, con il nome visualizzato e il Reply-To predefinito che hai configurato. Lo stato di consegna viene associato al messaggio inviato, così puoi verificare se una risposta è stata consegnata o è rimbalzata.

Eventi

Iscriviti alla famiglia di webhook email_mailbox.* per pilotare un agente senza polling: email_mailbox.message_received (la posta in arrivo ha raggiunto la inbox), email_mailbox.thread_created e gli eventi di stato di consegna per i messaggi che invii. Solo la posta in inbox viene distribuita; spam e posta bloccata da regole sono archiviati silenziosamente, così una casella inondata non si amplifica in un'ondata di webhook. La posta in inbox attiva anche l'evento standard email.received, quindi un'integrazione inbound esistente continua a funzionare.

Per una vista in tempo reale senza infrastruttura webhook, collegati a GET /v1/email/mailboxes/{mailbox_id}/events. Lo stream SSE invia il tipo di evento, l'ID del thread e l'ID del messaggio per l'attività della casella, inclusi spam e arrivi bloccati. Recupera i messaggi completi con quegli ID. Lo stream non riproduce eventi dopo una disconnessione. Usa i webhook per la consegna durevole e gli endpoint di lista per recuperare il ritardo dopo un'interruzione.

Conservazione e cancellazione

Il livello di conservazione di una casella controlla per quanto tempo puoi leggere gli header dei messaggi, il testo estratto e gli allegati della casella, a partire dall'invio o dalla ricezione. Il valore predefinito è 30 giorni. Se il tuo piano include la conservazione a 90 o 365 giorni, imposta retention_tier alla creazione o all'aggiornamento. Un livello non incluso nel tuo piano viene rifiutato con E17048.

Contenuto o azione	Finestra di conservazione
Header dei messaggi, testo estratto e allegati della casella	Livello selezionato: 30, 90 o 365 giorni
Body originali HTML e in testo semplice	30 giorni su ogni livello
MIME grezzo per i messaggi ricevuti	30 giorni su ogni livello; i messaggi inviati non hanno MIME grezzo archiviato
Inoltro di un messaggio nella dashboard	Richiede il contenuto originale entro la sua finestra di 30 giorni
Lettura del testo estratto o risposta con nuovo contenuto	Disponibile finché il messaggio è conservato

Ad esempio, al giorno 40 un messaggio in una casella a 90 giorni ha ancora testo estratto leggibile e ricercabile e allegati conservati. Puoi rispondere con nuovo contenuto, ma non puoi aprire il body originale, scaricare il suo MIME grezzo né inoltrarlo. Il testo estratto è limitato a 64 KiB per messaggio e può omettere parti dell'originale. Gli allegati archiviati prima dell'attivazione della conservazione estesa degli allegati mantengono la scadenza originale di circa 31 giorni; il cambio di livello non li migra. Innalzare il livello non può recuperare contenuti già eliminati.

I messaggi smettono di essere restituiti dalla API quando la loro conservazione scade. Un'operazione di pulizia oraria elabora l'eliminazione in background; la cancellazione fisica può restare indietro rispetto alla scadenza API.

L'abbassamento del livello ha effetto immediato sulle letture: tutto ciò che è più vecchio del nuovo limite smette di essere restituito immediatamente. Hai dieci minuti per annullare l'operazione, e dieci minuti è l'unica garanzia: rialza il livello entro quella finestra e nulla viene perso. Dopo, i messaggi rimasti fuori diventano idonei alla cancellazione e la pulizia oraria successiva li elimina, quindi un rialzo tardivo recupera solo ciò che la pulizia non ha ancora raggiunto.

L'innalzamento a un livello incluso nel tuo piano viene accettato in qualsiasi momento, anche mentre una modifica precedente è ancora in fase di applicazione. L'aggiornamento in background è indipendente dalla finestra di annullamento di dieci minuti. Un secondo abbassamento viene accettato dopo che la prima modifica ha aggiornato ogni messaggio archiviato. L'aggiornamento parte ogni dieci minuti e può richiedere ore per caselle di grandi dimensioni. Fino al completamento, la API restituisce E17050; riprova più tardi.

Se il tuo piano prevede una quota di archiviazione finita per le caselle, una singola quota è condivisa da ogni casella attiva o ripristinabile. Ogni casella riporta la sua parte come size_bytes. Un piano senza quota finita offre archiviazione illimitata per le caselle. Quando le caselle raggiungono insieme la quota finita, l'invio viene rifiutato con E17049 finché non liberi spazio in una qualsiasi di esse.

L'eliminazione di una casella interrompe immediatamente la ricezione della posta. La casella può essere ripristinata per 30 giorni, mentre la normale scadenza di conservazione dei messaggi continua. Dopo 30 giorni, la cancellazione permanente rimuove la casella e i messaggi rimasti. Una volta avviata la cancellazione permanente, il ripristino viene rifiutato anche se la pulizia è ancora in corso. L'indirizzo resta riservato al tuo spazio di lavoro.

Prossimi passi

Crea la tua prima casella: il percorso guidato API dalla creazione alla risposta.
Costruisci con l'IA: pilota le caselle di posta da un agente tramite il server MCP.

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaGetting started with email Esplora la funzionalitàEmail Segui il percorso di apprendimentoBuild your first integration Guida all'implementazioneSend your first email

Prova l'esercitazione e ottieni un brief di implementazione