Agent-mailboxen

Een agent-mailbox is een adresseerbare inbox die je code beheert via de API. Lees en filter de threads, beantwoord berichten of stel nieuwe mail op zonder een IMAP-server te draaien of ruwe MIME te parsen.

Een mailbox staat op het gedeelde inbox.ai-domein of op een van je eigen verzenddomeinen. Het adres wordt geclaimd zodra je de mailbox aanmaakt en blijft van jou: het lokale deel is gereserveerd voor je werkruimte en wordt nooit aan iemand anders gegeven, ook niet nadat je de mailbox verwijdert.

Adressen

Elke mailbox heeft één adres, {local_part}@inbox.ai. Je krijgt een adres op twee manieren:

• Gegenereerd: laat het lokale deel weg en we genereren een botsingsvrij adres voor je (a7f3k2@inbox.ai). Altijd beschikbaar.
• Aangepast: vraag een specifiek lokaal deel aan (support@inbox.ai). Aangepaste handles zijn wereldwijd uniek, op volgorde van aanvraag, en vallen onder het tegoed van een betaald abonnement; een gratis werkruimte gebruikt gegenereerde adressen.

Een adres is onveranderlijk zodra het is aangemaakt. Om het te wijzigen maak je een nieuwe mailbox aan en verwijder je de oude. Het oude lokale deel wordt 30 dagen vastgehouden (het herstelvenster) voordat het opnieuw geclaimd kan worden, en blijft gereserveerd voor je werkruimte.

Op je eigen domein geef je domain mee bij het aanmaken en kies je een willekeurig lokaal deel, zoals support@acme.com. Hoe mail de mailbox bereikt, hangt af van de configuratie van het domein:

• Ontvangst ingeschakeld: mail komt direct binnen zodra de MX-records van het domein naar ons verwijzen. Zie E-mail ontvangen.
• Ontvangst niet ingeschakeld: het eigendom van het domein moet geverifieerd zijn, en je MX-records blijven ongewijzigd. De mailbox krijgt een forwarding_address, zoals k7q2mzxw4h6p5ra3@eu1.inbound.bird.com. Voeg bij je huidige e-mailprovider een doorstuurregel voor support@acme.com toe die naar dat adres verwijst. Doorgestuurde mail komt in de mailbox terecht, en antwoorden en nieuwe mail worden nog steeds verzonden vanaf support@acme.com.

Heb je een bestaande mailbox op je eigen domein zonder doorstuuradres, open dan Mailbox settings en kies Set up forwarding. Het adres, de berichten, het ontvangstbeleid en de bewaring van de mailbox blijven daarbij ongewijzigd. Je hebt schrijfrechten voor mailboxbeheer nodig, en het eigendom van het domein moet in de werkruimte geverifieerd zijn. Heeft een andere werkruimte het domein voor ontvangst geclaimd, dan kun je hier geen nieuw doorstuuradres krijgen.

Het equivalent in de API is POST /v1/email/mailboxes/{mailbox_id}/forwarding-address, zonder request body. Dit retourneert de volledige mailbox met de forwarding_address. Herhaal je het verzoek, dan krijg je hetzelfde adres terug, ook na verwijderen en herstellen; het verzoek roteert het adres niet en hervat geen opgeschorte mailbox. Het CLI-commando is bird email mailboxes forwarding-address create <mailbox-id>.

Een adres aanmaken configureert geen doorsturen bij je provider, wijzigt geen DNS en verifieert geen bezorging. Ontvangt je provider al mail, houd dan de MX-records daar en voeg daar de doorstuurregel toe. Verwijzen de MX-records naar ons, richt dan eerst de mailbox en de doorstuurregel bij je provider in en zet daarna de MX-records over naar die provider. Laat Ontvangst ingeschakeld terwijl de DNS-wijziging wordt doorgevoerd. Test het doorsturen voordat je directe ontvangst uitschakelt.

Gmail en Google Workspace sturen een bevestigingsbericht naar een nieuw doorstuuradres. Open dat bericht in deze mailbox en volg de bevestigingsinstructies om de configuratie af te ronden. Bij Microsoft 365 moet een beheerder mogelijk extern doorsturen toestaan. Controleer bij het beleid replies_only of allowlist de geblokkeerde mail, en controleer ook spam en ontvangstregels. Een drop-beleid bewaart de bevestiging niet: wijzig het beleid expliciet voordat je een nieuwe bevestiging aanvraagt. Een opgeschorte mailbox moet je hervatten voordat die berichten normaal accepteert.

Bewaar tijdens het testen een kopie bij je provider. Stuur vanaf een ander account een nieuw bericht naar het oorspronkelijke mailboxadres en open het ontvangen bericht in deze mailbox. Het Delivered to-adres moet overeenkomen met het forwarding_address; dat toont aan dat de bezorging via die route verliep. De API geeft dit weer als delivered_to. Het aantal berichten in de mailbox omvat ook uitgaande activiteit en verifieert het doorsturen dus niet.

Wil je terug naar directe bezorging, schakel dan Ontvangst in, zet onze MX-records terug en test directe bezorging voordat je de doorstuurregel bij je provider verwijdert. Overlappende routes, zoals dubbele bezorging in Google Workspace, kunnen elk bericht twee keer in de mailbox zetten. Het doorstuuradres blijft werken als directe ontvangst is uitgeschakeld en blijft hetzelfde na verwijderen en herstellen.

Threads en berichten

Ontvangen en verzonden mail wordt gegroepeerd in threads, één per gesprek. Een thread bevat de deelnemende adressen, een teller voor ongelezen berichten, de richting van het laatste bericht (inbound of outbound) en het tijdstempel van de meest recente activiteit. Antwoorden worden in de bijbehorende thread opgenomen; een nieuw bericht opstellen start een nieuwe thread.

Elk bericht toont headers, geëxtraheerde platte tekst zonder geciteerde geschiedenis, en bijlagen. Originele bodies zijn 30 dagen beschikbaar; ruwe MIME is alleen beschikbaar voor ontvangen berichten. Bericht-ID's worden voorafgegaan door de richting: rem_ voor een ontvangen bericht, em_ voor een bericht dat je hebt verzonden.

Bepalen wat binnenkomt

Twee controles staan vóór de inbox:

• Ontvangstbeleid: de standaardinstelling voor de hele mailbox.
  • open accepteert mail na blokregels. SPF- en DKIM-resultaten veranderen dit toelatingsbeleid niet.
  • replies_only accepteert alleen mail die een bestaande thread in de mailbox voortzet.
  • allowlist accepteert alleen afzenders die je regels toestaan, plus antwoorden op een bestaande thread.
  • drop verwerpt alles, zonder uitzonderingen.
• Ontvangstregels: per afzender een toestaan- of blokkeervermelding, getoetst op een volledig adres of een domein (een domeinregel geldt ook voor subdomeinen). Een blokkering wint altijd van een toestemming.

Een blokregel wordt getoetst aan de envelope-afzender of het From:-adres. Een toestaanregel wordt getoetst aan de envelope-afzender, of aan het From:-adres als het bericht een geldige DKIM-handtekening heeft van het domein van dat adres. De From:-header is eenvoudig te vervalsen, dus een niet-ondertekende From: levert nooit een toestemming op. Dit geldt voor doorgestuurde mail, waarbij Gmail en Microsoft 365 de envelope-afzender vervangen door hun eigen adres, en voor mail van verzenddiensten die een apart bounce-adres gebruiken. Doorgestuurde mail zonder behouden DKIM-handtekening wordt nog steeds getoetst aan het adres van de doorstuurdienst.

Mail die een regel blokkeert, wordt opgeslagen in de mailbox en blijft leesbaar. Het wordt buiten de inbox gearchiveerd en verstuurt geen webhook. De enige uitzondering is een mailbox ingesteld op drop, die alles aan de deur weggooit in plaats van te archiveren.

Verzenden

Een mailbox verzendt op twee manieren via de API: beantwoorden van een bericht (het uitgaande bericht wordt in die thread opgenomen) of een nieuw bericht opstellen (wat een nieuwe thread opent). Open in het dashboard een bericht en kies Forward om de originele body en bijlagen naar nieuwe ontvangers te sturen, binnen het 30-dagenvenster van de originele inhoud. Mail wordt verzonden vanaf het eigen adres van de mailbox, met de weergavenaam en standaard Reply-To die je hebt ingesteld. De bezorgstatus wordt teruggekoppeld aan het verzonden bericht, zodat je kunt zien of een antwoord is bezorgd of gebounced.

Events

Abonneer je op de email_mailbox.*-webhookfamilie om een agent aan te sturen zonder polling: email_mailbox.message_received (inkomende mail heeft de inbox bereikt), email_mailbox.thread_created, en de delivery-status-events voor berichten die je verstuurt. Alleen inboxmail wordt doorgegeven; spam en door regels geblokkeerde mail wordt stil opgeslagen, zodat een overspoelde mailbox niet kan uitgroeien tot een stortvloed aan webhooks. Inboxmail activeert ook het standaard email.received-event, zodat een bestaande inbound-integratie blijft werken. Beide events bevatten authenticatieresultaten. Controleer die velden vóór geautomatiseerde routering: aflevering in de inbox alleen betekent niet dat de afzender geverifieerd was.

Bewaring en verwijdering

De bewaartier van een mailbox bepaalt hoe lang je berichtkoppen, geëxtraheerde tekst en mailboxbijlagen kunt lezen, gemeten vanaf verzending of ontvangst. De standaard is 30 dagen. Als je abonnement 90 of 365 dagen bewaring omvat, stel je retention_tier in bij het aanmaken of bijwerken. Een tier die je abonnement niet omvat, wordt geweigerd met E17048.

Op dag 40 heeft een bericht in een 90-dagenmailbox bijvoorbeeld nog leesbare, doorzoekbare geëxtraheerde tekst en bewaarde bijlagen. Je kunt antwoorden met nieuwe inhoud, maar je kunt de originele body niet openen, de ruwe MIME niet downloaden en het bericht niet doorsturen. Geëxtraheerde tekst is beperkt tot 64 KiB per bericht en kan delen van het origineel weglaten. Bijlagen die zijn opgeslagen vóór uitgebreide bijlagebewaring was ingeschakeld, behouden hun oorspronkelijke vervaldatum van ongeveer 31 dagen; van tier wisselen migreert ze niet. De tier verhogen kan inhoud die al verwijderd is niet herstellen.

Berichten worden niet meer geretourneerd door de API wanneer hun bewaartermijn verloopt. Een uurlijkse opruimtaak verwerkt verwijdering op de achtergrond; fysieke opruiming kan achterlopen op het verlopen van API.

Verlaging van de tier gaat onmiddellijk in op leesbewerkingen: alles ouder dan de nieuwe grens wordt meteen niet meer geretourneerd. Je hebt tien minuten om het ongedaan te maken, en tien minuten is de enige garantie: verhoog de tier opnieuw binnen dat venster en er gaat niets verloren. Daarna komen de gestrande berichten in aanmerking voor verwijdering en de volgende uurlijkse opruimtaak verwijdert ze, dus een latere verhoging herstelt alleen wat de opruimtaak nog niet heeft bereikt.

Verhoging naar een tier die je abonnement omvat, wordt op elk moment geaccepteerd, ook terwijl een eerdere wijziging nog wordt toegepast. De achtergrondupdate staat los van het tien-minutenvenster om ongedaan te maken. Een tweede verlaging wordt pas geaccepteerd nadat de eerste wijziging elk opgeslagen bericht heeft bijgewerkt. De update start elke tien minuten en kan uren duren voor grote mailboxen. Tot die voltooid is, retourneert de API E17050; probeer het later opnieuw.

Als je abonnement een eindige opslaglimiet voor mailboxen instelt, wordt één limiet gedeeld door elke actieve of herstelbare mailbox. Elke mailbox rapporteert zijn aandeel als size_bytes. Een abonnement zonder eindige limiet heeft onbeperkte mailboxopslag. Zodra de mailboxen samen een eindige limiet bereiken, wordt verzending geweigerd met E17049 totdat je ruimte vrijmaakt in een van de mailboxen.

Het verwijderen van een mailbox stopt onmiddellijk de ontvangst van mail. De mailbox kan 30 dagen worden hersteld, terwijl de normale bewaartermijn van berichten doorloopt. Na 30 dagen verwijdert permanente wissing de mailbox en de resterende berichten. Zodra permanente wissing begint, wordt herstel geweigerd, zelfs als opruiming nog bezig is. Het adres blijft gereserveerd voor je werkruimte.

Vervolgstappen

• Claim je eerste mailbox: het API-standaardpad van aanmaken tot antwoorden.
• Bouwen met AI: stuur mailboxen aan vanuit een agent via de MCP-server.