Skrzynki agentowe

Skrzynka agentowa to adresowalna skrzynka odbiorcza, którą Twój kod zarządza przez API. Czytaj i filtruj jej wątki, odpowiadaj na wiadomości lub twórz nowe bez uruchamiania serwera IMAP i bez parsowania surowego MIME.

Skrzynka działa na współdzielonej domenie inbox.ai albo na jednej z Twoich własnych domen nadawczych. Adres jest rezerwowany w momencie utworzenia skrzynki i pozostaje Twój: część lokalna jest przypisana do Twojego obszaru roboczego i nigdy nie zostanie przekazana nikomu innemu, nawet po usunięciu skrzynki.

Adresy

Każda skrzynka ma jeden adres, {local_part}@inbox.ai. Adres możesz uzyskać na dwa sposoby:

• Wygenerowany: pomiń część lokalną, a wygenerujemy dla Ciebie unikalną (a7f3k2@inbox.ai). Zawsze dostępny.
• Własny: podaj konkretną część lokalną (support@inbox.ai). Własne identyfikatory są globalnie unikalne, przydzielane w kolejności zgłoszeń i wliczane w limit płatnego planu; darmowy obszar roboczy korzysta z adresów generowanych.

Adres po utworzeniu jest niezmienny. Aby go zmienić, utwórz nową skrzynkę i usuń starą. Stara część lokalna jest przechowywana przez 30 dni (okno przywracania), zanim będzie mogła zostać ponownie zajęta, i pozostaje zarezerwowana dla Twojego obszaru roboczego.

We własnej domenie przekaż domain przy tworzeniu i wybierz dowolną część lokalną, na przykład support@acme.com. Sposób, w jaki poczta trafia do skrzynki, zależy od konfiguracji domeny:

• Odbiór włączony: poczta trafia bezpośrednio, gdy rekordy MX domeny wskazują na nas. Zobacz Odbieranie poczty e-mail.
• Odbiór niewłączony: domena wymaga zweryfikowanej własności, a Twoje rekordy MX pozostają bez zmian. Skrzynka otrzymuje forwarding_address, na przykład k7q2mzxw4h6p5ra3@eu1.inbound.bird.com. U obecnego dostawcy poczty dodaj regułę przekazywania dla support@acme.com, wskazującą na ten adres. Przekazana poczta trafia do skrzynki, a odpowiedzi i nowe wiadomości nadal wychodzą z support@acme.com.

W przypadku istniejącej skrzynki we własnej domenie bez adresu przekazywania otwórz Mailbox settings i wybierz Set up forwarding. Adres skrzynki, wiadomości, polityka odbioru i retencja pozostają bez zmian. Wymaga to uprawnienia do zapisu w zarządzaniu skrzynkami oraz zweryfikowanej własności domeny w obszarze roboczym. Domena zajęta do odbioru przez inny obszar roboczy nie może tu otrzymać nowego adresu przekazywania.

Odpowiednikiem w API jest POST /v1/email/mailboxes/{mailbox_id}/forwarding-address, bez treści żądania. Zwraca pełną skrzynkę wraz z jej forwarding_address. Powtórzenie żądania zwraca ten sam adres, także po usunięciu i przywróceniu; nie zmienia adresu ani nie wznawia zawieszonej skrzynki. Polecenie CLI to bird email mailboxes forwarding-address create <mailbox-id>.

Utworzenie adresu nie konfiguruje przekazywania u Twojego dostawcy, nie zmienia DNS ani nie weryfikuje dostarczania. Jeśli Twój dostawca już odbiera pocztę, zachowaj jego rekordy MX i dodaj u niego regułę przekazywania. Jeśli rekordy MX wskazują na nas, najpierw przygotuj skrzynkę i regułę przekazywania u dostawcy, a potem przenieś rekordy MX do tego dostawcy. Nie wyłączaj odbioru, dopóki zmiana DNS się propaguje. Przetestuj przekazywanie, zanim wyłączysz bezpośredni odbiór.

Gmail i Google Workspace wysyłają wiadomość potwierdzającą na nowy adres przekazywania. Otwórz ją w tej skrzynce i postępuj zgodnie z jej instrukcjami, aby dokończyć konfigurację. Microsoft 365 może wymagać, aby administrator zezwolił na przekazywanie zewnętrzne. Przy polityce replies_only lub allowlist sprawdź zablokowaną pocztę, a także spam i reguły odbioru. Polityka drop nie zachowuje potwierdzenia: zmień politykę, zanim poprosisz o nowe potwierdzenie. Zawieszoną skrzynkę trzeba wznowić, aby normalnie przyjmowała wiadomości.

Podczas testów zachowuj kopię u dostawcy. Wyślij nową wiadomość z innego konta na pierwotny adres skrzynki, a następnie otwórz odebraną wiadomość w tej skrzynce. Jej adres Delivered to musi być zgodny z forwarding_address, co potwierdza dostarczenie tą drogą. API udostępnia tę informację jako delivered_to. Liczniki wiadomości skrzynki obejmują aktywność wychodzącą i nie potwierdzają przekazywania.

Aby wrócić do bezpośredniego dostarczania, włącz odbiór, przywróć nasze rekordy MX i przetestuj bezpośrednie dostarczanie, zanim usuniesz regułę przekazywania u dostawcy. Nakładające się drogi, takie jak podwójne dostarczanie w Google Workspace, mogą umieścić każdą wiadomość w skrzynce dwukrotnie. Adres przekazywania działa nadal po wyłączeniu bezpośredniego odbioru i pozostaje taki sam po usunięciu i przywróceniu.

Wątki i wiadomości

Odebrana i wysłana poczta jest grupowana w wątki, jeden na konwersację. Wątek zawiera adresy uczestników, licznik nieprzeczytanych, kierunek najnowszej wiadomości (inbound lub outbound) oraz znacznik czasu ostatniej aktywności. Odpowiedzi trafiają do wątku, na który odpowiadają; nowa wiadomość rozpoczyna nowy wątek.

Każda wiadomość udostępnia nagłówki, wyekstrahowany tekst z usuniętą historią cytowań oraz załączniki. Oryginalne treści są dostępne przez 30 dni; surowy MIME jest dostępny tylko dla wiadomości odebranych. Identyfikatory wiadomości mają prefiks kierunku: rem_ dla wiadomości odebranej, em_ dla wysłanej.

Kontrola przyjmowania poczty

Przed skrzynką odbiorczą działają dwie kontrole:

• Polityka odbioru: domyślna reguła całej skrzynki.
  • open przyjmuje pocztę po zastosowaniu reguł blokowania. Wyniki SPF i DKIM nie zmieniają tej polityki przyjmowania.
  • replies_only akceptuje tylko pocztę kontynuującą wątek już istniejący w skrzynce.
  • allowlist akceptuje tylko nadawców dopuszczonych przez Twoje reguły oraz odpowiedzi na istniejący wątek.
  • drop odrzuca wszystko, bez wyjątków.
• Reguły odbioru: wpisy zezwalające lub blokujące poszczególnych nadawców, dopasowywane po pełnym adresie lub domenie (reguła domenowa obejmuje też subdomeny). Blokada zawsze wygrywa z zezwoleniem.

Reguła blokująca dopasowuje nadawcę kopertowego lub adres From:. Reguła zezwalająca dopasowuje nadawcę kopertowego albo adres From:, gdy wiadomość ma prawidłowy podpis DKIM z domeny tego adresu. Nagłówek From: łatwo sfałszować, więc niepodpisany From: nigdy nie uzyskuje zezwolenia. Dotyczy to poczty przekazanej, w której Gmail i Microsoft 365 zastępują nadawcę kopertowego własnym adresem, oraz poczty z usług wysyłkowych używających osobnego adresu zwrotnego. Poczta przekazana bez zachowanego podpisu DKIM nadal jest dopasowywana po adresie usługi przekazującej.

Poczta zablokowana przez regułę jest przechowywana w skrzynce i pozostaje dostępna do odczytu. Trafia poza skrzynkę odbiorczą i nie wywołuje webhooka. Jedynym wyjątkiem jest skrzynka ustawiona na drop, która odrzuca wszystko od razu, zamiast to katalogować.

Wysyłanie

Skrzynka wysyła na dwa sposoby przez API: odpowiedź na wiadomość (wiadomość wychodząca trafia do tego samego wątku) lub nowa wiadomość (która otwiera nowy wątek). W panelu otwórz wiadomość i wybierz Forward, aby wysłać jej oryginalną treść i załączniki do nowych odbiorców w ramach 30-dniowego okna dostępności treści. Poczta jest wysyłana z adresu skrzynki, z nazwą wyświetlaną i domyślnym Reply-To, które na niej skonfigurowałeś. Status doręczenia jest dołączany do wysłanej wiadomości, więc widzisz, czy odpowiedź została doręczona, czy odrzucona.

Zdarzenia

Zasubskrybuj rodzinę webhooków email_mailbox.*, aby sterować agentem bez odpytywania: email_mailbox.message_received (poczta przychodząca trafiła do skrzynki odbiorczej), email_mailbox.thread_created oraz zdarzenia statusu dostarczenia dla wysyłanych wiadomości. Tylko poczta ze skrzynki odbiorczej generuje zdarzenia; spam i poczta zablokowana regułami są przechowywane po cichu, więc zalana skrzynka nie przekłada się na lawinę webhooków. Poczta ze skrzynki odbiorczej wyzwala też standardowe zdarzenie email.received, więc istniejąca integracja poczty przychodzącej nadal działa. Oba zdarzenia zawierają wyniki uwierzytelnienia. Sprawdź te pola przed automatycznym routingiem: samo dostarczenie do skrzynki nie oznacza, że nadawca został zweryfikowany.

Retencja i usuwanie

Poziom retencji skrzynki określa, jak długo możesz odczytywać nagłówki wiadomości, wyodrębniony tekst i załączniki skrzynki, licząc od wysłania lub odebrania. Domyślnie jest to 30 dni. Jeśli Twój plan obejmuje retencję 90- lub 365-dniową, ustaw retention_tier przy tworzeniu lub aktualizacji. Poziom nieuwzględniony w Twoim planie zostanie odrzucony z błędem E17048.

Na przykład 40. dnia wiadomość w skrzynce z 90-dniową retencją nadal ma czytelny, przeszukiwalny wyodrębniony tekst i zachowane załączniki. Możesz odpowiedzieć z nową treścią, ale nie możesz otworzyć oryginalnej treści, pobrać surowego MIME ani przekazać wiadomości. Wyodrębniony tekst jest ograniczony do 64 KiB na wiadomość i może pomijać fragmenty oryginału. Załączniki zapisane przed włączeniem rozszerzonej retencji załączników zachowują swój pierwotny termin wygaśnięcia wynoszący około 31 dni; zmiana poziomu nie powoduje ich migracji. Podniesienie poziomu nie odzyska treści, które zostały już usunięte.

Wiadomości przestają być zwracane przez API, gdy ich retencja wygaśnie. Co godzinę uruchamiany jest proces usuwania w tle; fizyczne czyszczenie może następować z opóźnieniem względem wygaśnięcia API.

Obniżenie poziomu działa na odczyty natychmiast: wszystko starsze niż nowy próg przestaje być zwracane od razu. Masz dziesięć minut na cofnięcie tej zmiany i dziesięć minut to jedyna gwarancja: podnieś poziom ponownie w tym oknie, a nic nie zostanie utracone. Po jego upływie osierocone wiadomości kwalifikują się do usunięcia i najbliższy proces godzinny je zabiera, więc późniejsze podniesienie odzyska tylko to, czego proces jeszcze nie usunął.

Podniesienie do poziomu uwzględnionego w Twoim planie jest akceptowane w dowolnym momencie, także gdy wcześniejsza zmiana jest jeszcze stosowana. Aktualizacja w tle jest niezależna od dziesięciominutowego okna cofnięcia. Ponowne obniżenie jest akceptowane po tym, jak pierwsza zmiana zaktualizuje każdą zapisaną wiadomość. Aktualizacja uruchamia się co dziesięć minut i w przypadku dużych skrzynek może trwać godzinami. Do jej zakończenia API zwraca E17050; spróbuj ponownie później.

Jeśli Twój plan ustala skończony limit pojemności skrzynki, jeden limit jest współdzielony przez wszystkie aktywne lub możliwe do przywrócenia skrzynki. Każda skrzynka raportuje swój udział jako size_bytes. Plan bez skończonego limitu zapewnia nieograniczoną pojemność skrzynki. Gdy skrzynki łącznie osiągną skończony limit, wysyłanie jest odrzucane z błędem E17049, dopóki nie zwolnisz miejsca w którejkolwiek z nich.

Usunięcie skrzynki natychmiast wstrzymuje odbieranie poczty. Skrzynkę można przywrócić przez 30 dni, a normalne wygasanie retencji wiadomości trwa nadal. Po 30 dniach trwałe usunięcie kasuje skrzynkę i pozostałe w niej wiadomości. Gdy trwałe usunięcie się rozpocznie, przywracanie jest odrzucane, nawet jeśli czyszczenie jeszcze trwa. Adres pozostaje zarezerwowany dla Twojego obszaru roboczego.

Następne kroki

• Utwórz swoją pierwszą skrzynkę: ścieżka API od utworzenia do odpowiedzi.
• Buduj z AI: steruj skrzynkami z poziomu agenta przez serwer MCP.