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 draait op het gedeelde inbox.ai-domein, of op je eigen verzenddomein met ontvangst ingeschakeld. 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, zelfs 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.
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, beide getoetst aan de envelope-afzender in plaats van de vervalsbare From:-header:
- Ontvangstbeleid: de standaardinstelling voor de hele mailbox.
- open accepteert alles wat authenticatie doorstaat.
- 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.
Mail die een regel blokkeert, of die niet door DMARC komt, wordt nog steeds opgeslagen in de mailbox en blijft leesbaar: het wordt buiten de inbox gearchiveerd in plaats van verwijderd, en er wordt geen webhook geactiveerd. De enige uitzondering is een mailbox ingesteld op drop, die alles bij de deur verwerpt 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 Doorsturen 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 bezorgstatusevents voor berichten die je verstuurt. Alleen inbox-mail wordt doorgestuurd; spam en door regels geblokkeerde mail wordt stil opgeslagen, zodat een overspoelde mailbox niet kan uitmonden in een stortvloed aan webhooks. Inbox-mail activeert ook het standaard email.received-event, zodat een bestaande inbound-integratie blijft werken.
Voor een live weergave zonder webhook-infrastructuur verbind je met GET /v1/email/mailboxes/{mailbox_id}/events. De SSE-stream stuurt het eventtype, thread-ID en bericht-ID voor mailboxactiviteit, inclusief spam en geblokkeerde berichten. Haal volledige berichten op met die ID's. De stream herhaalt geen events na een verbroken verbinding. Gebruik webhooks voor duurzame bezorging en de lijst-endpoints om bij te werken na een onderbreking.
Bewaring en verwijdering
De bewaringslaag van een mailbox bepaalt hoe lang je berichtheaders, geëxtraheerde tekst en mailboxbijlagen kunt lezen, gemeten vanaf verzending of ontvangst. De standaard is 30 dagen. Als je abonnement bewaring van 90 of 365 dagen omvat, stel dan retention_tier in bij aanmaken of bijwerken. Een laag die je abonnement niet omvat wordt geweigerd met E17048.
| Inhoud of actie | Bewaringsvenster |
|---|---|
| Berichtheaders, geëxtraheerde tekst en mailboxbijlagen | Geselecteerde laag: 30, 90 of 365 dagen |
| Originele HTML- en platte-tekst-bodies | 30 dagen op elke laag |
| Ruwe MIME voor ontvangen berichten | 30 dagen op elke laag; verzonden berichten hebben geen opgeslagen ruwe MIME |
| Een bericht doorsturen in het dashboard | Vereist originele inhoud binnen het 30-dagenvenster |
| Geëxtraheerde tekst lezen of beantwoorden met nieuwe inhoud | Beschikbaar zolang het bericht bewaard wordt |
Op dag 40 heeft een bericht in een 90-dagenmailbox bijvoorbeeld nog steeds leesbare, doorzoekbare geëxtraheerde tekst en bewaarde bijlagen. Je kunt beantwoorden 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; het wisselen van laag migreert ze niet. Het verhogen van de laag kan inhoud die al is verwijderd niet herstellen.
Berichten worden niet meer geretourneerd door de API wanneer hun bewaring verloopt. Een uurlijkse opruimronde verwerkt verwijdering op de achtergrond; fysieke opruiming kan achterlopen op het verlopen van API.
Het verlagen van de laag wordt onmiddellijk van kracht bij lezen: alles dat ouder is dan de nieuwe grens wordt direct niet meer geretourneerd. Je hebt tien minuten om het ongedaan te maken, en tien minuten is de enige garantie: verhoog de laag opnieuw binnen dat venster en er gaat niets verloren. Daarna komen de gestrande berichten in aanmerking voor verwijdering en de volgende uurlijkse opruimronde neemt ze mee, dus een latere verhoging herstelt alleen wat de opruimronde nog niet heeft bereikt.
Verhogen naar een laag die je abonnement omvat wordt op elk moment geaccepteerd, ook terwijl een eerdere wijziging nog wordt toegepast. De achtergrondupdate staat los van het tienmenutenvenster om ongedaan te maken. Een tweede verlaging wordt 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 is voltooid retourneert de API E17050; probeer het later opnieuw.
Als je abonnement een eindig opslagtegoed voor mailboxen instelt, wordt één tegoed gedeeld door alle actieve of herstelbare mailboxen. Elke mailbox rapporteert zijn aandeel als size_bytes. Een abonnement zonder eindig tegoed heeft onbeperkte mailboxopslag. Zodra de mailboxen samen een eindig tegoed bereiken, wordt verzenden geweigerd met E17049 totdat je ruimte vrijmaakt in een van de mailboxen.
Het verwijderen van een mailbox stopt de ontvangst van mail onmiddellijk. De mailbox kan 30 dagen worden hersteld, terwijl de normale berichtvervaldatum 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 happy path van aanmaken tot beantwoorden.
- Bouw met AI: stuur mailboxen aan vanuit een agent via de MCP-server.
Gerelateerde bronnen
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.
Bekijk de gidsGetting started with emailOntdek de mogelijkheidEmailVolg het leerpadBuild your first integrationImplementatiegidsSend your first email
Probeer de oefening en ontvang een implementatieoverzicht