Caselle di posta per agenti

Una casella di posta per agenti è una casella indirizzabile che il tuo codice gestisce tramite l'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 uno dei tuoi domini di invio. 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.

Sul tuo dominio, passa domain alla creazione e scegli una parte locale qualsiasi, come support@acme.com. Il modo in cui la posta raggiunge la casella dipende dalla configurazione del dominio:

• Ricezione abilitata: la posta arriva direttamente non appena i record MX del dominio puntano a noi. Vedi Ricezione email.
• Ricezione non abilitata: la proprietà del dominio deve essere verificata e i tuoi record MX restano invariati. La casella riceve un forwarding_address, come k7q2mzxw4h6p5ra3@eu1.inbound.bird.com. Presso il tuo attuale provider email, aggiungi una regola di inoltro per support@acme.com che punti a quell'indirizzo. La posta inoltrata arriva nella casella, e le risposte e i nuovi messaggi partono comunque da support@acme.com.

Per una casella esistente sul tuo dominio senza indirizzo di inoltro, apri Mailbox settings e scegli Set up forwarding. L'indirizzo della casella, i messaggi, il criterio di ricezione e la conservazione restano invariati. Servono il permesso di scrittura sulla gestione delle caselle e la proprietà del dominio verificata nello spazio di lavoro. Se un altro spazio di lavoro ha già rivendicato il dominio per la ricezione, qui non puoi ottenere un nuovo indirizzo di inoltro.

L'equivalente API è POST /v1/email/mailboxes/{mailbox_id}/forwarding-address, senza corpo della richiesta. Restituisce la casella completa con il suo forwarding_address. Ripetendo la richiesta ottieni lo stesso indirizzo, anche dopo eliminazione e ripristino; la richiesta non cambia l'indirizzo né riattiva una casella sospesa. Il comando CLI è bird email mailboxes forwarding-address create <mailbox-id>.

Creare un indirizzo non configura l'inoltro presso il tuo provider, non modifica il DNS e non verifica la consegna. Se il tuo provider riceve già la posta, mantieni i suoi record MX e aggiungi lì la regola di inoltro. Se i record MX puntano a noi, prepara prima la casella e la regola di inoltro presso il provider, poi sposta i record MX su quel provider. Mantieni la ricezione abilitata mentre la modifica DNS si propaga. Prova l'inoltro prima di disattivare la ricezione diretta.

Gmail e Google Workspace inviano un messaggio di conferma al nuovo indirizzo di inoltro. Aprilo in questa casella e segui le istruzioni di conferma per completare la configurazione. Microsoft 365 può richiedere che un amministratore consenta l'inoltro esterno. Con il criterio replies_only o allowlist, controlla la posta bloccata; controlla anche lo spam e le regole di ricezione. Un criterio drop non conserva la conferma: cambia esplicitamente il criterio prima di richiedere una nuova conferma. Una casella sospesa deve essere riattivata per accettare normalmente i messaggi.

Durante i test, conserva una copia presso il tuo provider. Invia un nuovo messaggio da un altro account all'indirizzo originale della casella, poi apri il messaggio ricevuto in questa casella. Il suo indirizzo Delivered to deve corrispondere a forwarding_address per dimostrare la consegna tramite quel percorso. L'API lo espone come delivered_to. I conteggi dei messaggi della casella includono l'attività in uscita e non verificano l'inoltro.

Per tornare alla consegna diretta, abilita la ricezione, ripristina i nostri record MX e prova la consegna diretta prima di rimuovere la regola di inoltro del provider. Percorsi sovrapposti, come la doppia consegna di Google Workspace, possono far arrivare ogni messaggio due volte nella casella. L'indirizzo di inoltro continua a funzionare quando la ricezione diretta è disattivata e resta lo stesso dopo eliminazione e ripristino.

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 posta in arrivo:

• Criterio di ricezione: il default a livello di casella.
  • open accetta la posta dopo le regole di blocco. I risultati SPF e DKIM non modificano questa policy di ammissione.
  • 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.

Una regola di blocco corrisponde al mittente dell'envelope o all'indirizzo From:. Una regola di consenso corrisponde al mittente dell'envelope, oppure all'indirizzo From: quando il messaggio ha una firma DKIM valida del dominio di quell'indirizzo. L'header From: è facile da falsificare, quindi un From: non firmato non ottiene mai un consenso. Questo copre la posta inoltrata, in cui Gmail e Microsoft 365 sostituiscono il mittente dell'envelope con un proprio indirizzo, e la posta dei servizi di invio che usano un indirizzo di bounce separato. La posta inoltrata senza una firma DKIM ancora valida corrisponde comunque all'indirizzo del servizio di inoltro.

La posta bloccata da una regola viene comunque archiviata nella casella e resta leggibile. Viene spostata fuori dalla posta in arrivo e non genera webhook. L'unica eccezione è una casella impostata su drop, che scarta tutto all'ingresso invece di archiviarlo.

Invio

Una casella di posta invia in due modi tramite l'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 Forward 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 entrata ha raggiunto la posta in arrivo), email_mailbox.thread_created e gli eventi di stato di consegna per i messaggi che invii. Solo la posta in arrivo viene propagata; spam e posta bloccata dalle regole vengono archiviati silenziosamente, così una casella inondata non può amplificarsi in una cascata di webhook. La posta in arrivo genera anche l'evento standard email.received, quindi un'integrazione inbound esistente continua a funzionare. Entrambi gli eventi includono i risultati di autenticazione. Controlla quei campi prima di un instradamento automatico: la consegna nella posta in arrivo da sola non significa che il mittente sia stato verificato.

Conservazione e cancellazione

Il livello di conservazione di una casella determina per quanto tempo puoi leggere intestazioni dei messaggi, testo estratto e allegati della casella, misurato 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 piano viene rifiutato con E17048.

Ad esempio, al giorno 40 un messaggio in una casella a 90 giorni ha ancora testo estratto leggibile, ricercabile e allegati conservati. Puoi rispondere con nuovo contenuto, ma non puoi aprire il corpo originale, scaricare il MIME grezzo o 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. Alzare il livello non può recuperare contenuti già cancellati.

I messaggi smettono di essere restituiti dall'API quando la loro conservazione scade. Un processo orario esegue la cancellazione in background; la pulizia fisica può ritardare rispetto alla scadenza API.

Abbassare il livello ha effetto immediato sulle letture: tutto ciò che è più vecchio del nuovo limite smette di essere restituito subito. Hai dieci minuti per annullare, e dieci minuti è l'unica garanzia: alza di nuovo il livello entro quella finestra e non viene perso nulla. Dopo, i messaggi rimasti diventano idonei alla cancellazione e il successivo processo orario li rimuove, quindi un innalzamento successivo recupera solo ciò che il processo non ha ancora raggiunto.

Alzare a un livello incluso nel piano è accettato in qualsiasi momento, anche mentre una modifica precedente è ancora in applicazione. L'aggiornamento in background è indipendente dalla finestra di annullamento di dieci minuti. Abbassare una seconda volta è 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. Finché non è completato, l'API restituisce E17050; riprova più tardi.

Se il tuo piano prevede un limite di archiviazione per le caselle, un unico limite è condiviso da ogni casella attiva o ripristinabile. Ogni casella riporta la propria quota come size_bytes. Un piano senza limite ha archiviazione illimitata per le caselle. Quando le caselle raggiungono complessivamente il limite, l'invio viene rifiutato con E17049 finché non liberi spazio in una qualsiasi di esse.

L'eliminazione di una casella interrompe immediatamente la ricezione di posta. La casella può essere ripristinata per 30 giorni, mentre la normale scadenza di conservazione dei messaggi prosegue. 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'AI: gestisci le caselle da un agente tramite il server MCP.