Odniesienie do API

Użyj Agentic Inbox, aby podłączyć skrzynkę pocztową do asystenta lub API zarządzania, aby zarządzać domenami, skrzynkami pocztowymi i aliasami Twojej organizacji. Korzystają one z odrębnych mandatów i uprawnień. Wybierz integrację, której potrzebujesz poniżej.

Agentic Inbox

Połącz przez OAuth z PKCE https://franklymail.com/api/agent/mcp. W prowadnica połączeń obejmuje konfigurację ChatGPT i Claude. Zaloguj się na pocztę. Każda dotacja OAuth jest związana z tą zweryfikowaną skrzynką pocztową. Korzystanie z dotacji mailbox.read, message.read, message.search oraz draft.write. Nie ma automatycznego zezwolenia na wysyłanie.

Projekty zwracają link do recenzji. Tylko sesja zweryfikowana dla tej skrzynki pocztowej może zatwierdzić dokładną bieżącą wersję. Sesja kont panelowych nie może wyrażać zgody ani zatwierdzać. Argumenty narzędzia lub wiadomość czatu nie mogą autoryzować wysyłania.

Do wyszukiwania folder- specyficzne, przejść folder jako inbox, sent, drafts, archive, trash lub junk (spam jest pseudonimem). Stosowanie list_folders oraz folderId dla folderów niestandardowych. Wybierz jeden selector; brakujący folder zwraca błąd zamiast przeszukiwać wszystkie wiadomości. Pomijanie obu wyszukiwań każdego folderu.

prepare_forward wymaga mailboxId, messageId, requestKey oraz to; cc oraz wprowadzenie text są opcjonalne. To wymaga obu message.read oraz draft.write. Oryginalne nagłówki i czytelny tekst są włączane automatycznie. Załączniki wymagają poczty internetowej, lub wyraźnego wyboru tekstu przez użytkownika tylko za pomocą omitAttachments: true. Niekompletne lub przerośnięte oryginały są odrzucane. Projekty terminowe wykorzystują ten sam przepływ przeglądów i homologacji co odpowiedzi.

Ludzka strona przeglądowa obsługuje edytowanie odbiorców, przedmiotów i wiadomości. Mailbox Boost dodaje również fakultatywne Ścieżka otwiera oraz Napisz z AI. Śledzenie jest wyłączone, dopóki nie zostanie zaznaczone i zapisane. Wspólna wiadomość wysłana do kilku odbiorców nie może określić, który odbiorca ją otworzył. Proxy prywatności mogą wpływać na sygnały otwarte; wyświetlanie aktywności w poczcie internetowej.

Pisarz AI wymaga zgody na skrzynkę pocztową i dzieli się dodatku na pisanie poczty internetowej. Wykorzystuje zapisany projekt, przedmiot, odbiorców i instrukcje pisania, aby przygotować sugestię do OpenAI. Stosowanie sugestii to edycja, a następnie oszczędzanie i świeża aprobata dla ludzi. Żadna funkcja nie dodaje narzędzia MCP ani zezwolenia na wysyłanie; agenci nie mogą ustawić trackOpens lub zadzwonić do autora przeglądarki.

OAuth używa kodu autoryzacji S256 PKCE oraz resource=https://franklymail.com/api/agent/mcp. Odkryj konfigurację w metadane zasobów chronionych oraz metadane serwera autoryzacji. Dynamiczna rejestracja klienta jest obsługiwana. Tokeny dostępu trwają jedną godzinę, odświeżają się i obracają. Ponowne użycie tokena odświeżającego cofa połączenie. Dotacje trwają do 90 dni.

MCP używa bezpaństwowców Streamable HTTP z odpowiedziami JSON. Zawołaj tools/list dla schematów. Udane połączenia obejmują: result.structuredContent; awarie narzędzi mogą zwrócić HTTP 200 z result.isError=true oraz blok tekstowy JSON zawierający error. Sprawdź zarówno odpowiedź HTTP jak i wynik narzędzia. Uwierzytelnianie nie działa za pomocą HTTP 401.

Alternatywne trasy HTTP: GET /api/v1/mailboxes/:id/messages, GET /api/v1/mailboxes/:id/messages/:messageId, POST /api/v1/drafts, GET /api/v1/drafts/:id oraz PUT /api/v1/drafts/:id. Wyszukiwanie akceptuje folder lub folderId, text, from, subject, unread, limit (1 do 25) oraz position. Projekt tworzenia wymaga mailboxId, requestKey, to, subject, text; cc oraz replyToMessageId są opcjonalne. Przegląd wymaga aktualnego version oraz kompletnych odbiorców zastępczych, przedmiotów i tekstu.

Listowanie folderów i przesyłanie folderów za pomocą narzędzi MCP list_folders oraz prepare_forward; nie posiadają odrębnych tras HTTP. Projekty obsługują co najwyżej 10 Odbiorców do i Cc łącznie, obiekt 256-znak i 20,000-znak wiadomości, i wygasają po 24 godzin. Zostają w Agentic Inbox do czasu zatwierdzenia; wysyłane wiadomości pojawiają się na poczcie internetowej.

Agentic Inbox pozwala 25 wniosków / dzień i 5 / minutę na skrzynkę pocztową; Boost podnosi to do 2,500 / dzień i 60 / minutę. Połączenia z tą samą skrzynką pocztową dzielą się jej przydziałem. Zmiana hasła cofa sesje i połączenia pocztowe. Istniejące subwencje skrzynek odbiorczych autoryzowane przez konto muszą ponownie połączyć się za pośrednictwem poczty internetowej. Dzienne diety zresetowane o północy UTC. Dodatek ten nie jest przedmiotem ręcznego przeglądu i zatwierdzenia. W przypadku błędu ograniczającego należy przestrzegać Retry-After oraz error.resetsAt; pokaż dostarczony link Boost o wyczerpaniu standardowego planu.

Dla kogo możesz tworzyć skrzynki pocztowe

Jedno konto to jedna organizacja. Skrzynki pocztowe są dla ludzi w Twoim: pracowników, wykonawców, własne projekty, pseudonimy i wspólne adresy. Są. nie dla klientów pobieranych lub serwowanych. Oddanie FranklyMail skrzynek pocztowych, lub prowadzenie konta w imieniu kogoś innego jako usługi, za którą jesteś opłacany, jest naruszeniem terminy. Zobacz klauzulę odsprzedaży. Prowadzenie kilku domen jest w porządku i zawsze było; holding z piętnastu marek jest jedną organizacją. Agencja z 15 klientami nie jest.

Nie ma kwoty liczenia pocztowego, aby wyegzekwować to rozróżnienie. Jeśli konto rozwija się w postaci kilku organizacji, piszemy i pytamy. Nic nie jest zawieszone z powodu pytania.

API zasobów Legacy: tylko metadane

Istniejące referencje zasobów zachowują swoje oryginalne uprawnienia. Aby umożliwić dostęp do treści poczty, utworzyć nowe połączenie za pomocą asystent przewodnika połączenia. Klucze przyznane tylko domain.read oraz mailbox.read czytaj tylko metadane. Nie mogą czytać wiadomości, wysyłać wiadomości ani zmieniać zasobów. Nowo utworzone skrzynki pocztowe i domeny nigdy nie uzyskują dostępu automatycznie.

Wyślij klucz jako Authorization: Bearer fma_.... Poniższe przejścia są względne do https://franklymail.com/api.

Listy akceptują limit od 1 do 100 (domyślnie 50) i UUID cursor od poprzedniej odpowiedzi. Wracają. { data: [...], nextCursor, requestId }; szczegółowe informacje o powrocie { data: {...}, requestId }. Liczenie bajtów to skróty dziesiętne. DNS wyniki są przechowywane obserwacje.

Standardowy ograniczony dostęp pozwala na 25 wniosków / dzień i 5 / minutę, udostępnianych na kluczach konta. Mailbox Boost podnosi to do 2500 / dzień i 60 / minutę na subskrybowaną skrzynkę pocztową. Dni resetowane o północy UTC. Kluczowe pułapy domyślne do 60 / minutę, regulowane od 1 do 600, z oddzielnym pułapem bezpieczeństwa wspólnego konta 600 / minutę.

Każda zwrócona skrzynka Boost korzysta z jednej prośby z własnego kieszonkowego. Wszelkie standardowe zasoby na stronie udostępniają jeden standardowy wniosek. Wszystkie wymagane dodatki muszą być dostępne; odrzucona strona nie wydaje żadnego z nich. Pusta strona korzysta ze standardowego dodatku. Domena i DNS czytniki mogą korzystać z uprawnień pierwszej skrzynki boost przez UUID w tej dziedzinie, tylko wtedy, gdy klucz wyraźnie przyznaje mailbox.read Za to też. Nie zwiększa to dostępu do innych skrzynek pocztowych.

On 429, honor Retry-After oraz error.resetsAt. Dzienne wykorzystanie wyczerpania daily_quota_exceeded; minimalne limity stosowania rate_limited. Standardowe limity planu obejmują: error.metadata.upgrade z łączem Boost i wyższe uprawnienia. Pokaż link do osoby zarządzającej skrzynką pocztową. Agent nie może kupić upgrade. Zwiększone wyczerpanie i pułapy bezpieczeństwa key / account nie mają żadnej oferty aktualizacji. X-Agent-Plan określa standardowy, zwiększający lub mieszany dostęp; X-Agent-Daily-Limit, X-Agent-Daily-Remaining oraz X-Agent-Daily-Reset opisać wymaganą dzienną dietę wraz z najmniejszymi pozostającymi wnioskami. Kluczowe pułapy nadal liczą uwierzytelnione zaprzeczenia. Brak zwrotów z zakresu 403; zasób poza zwrotem dotacji 404; wygasły lub cofnięty zwrot klucza 401. Ograniczone kwalifikacje pracy /api/v1 oraz /api/agent/mcp w ich oryginalnych zakresach. Trasy te nie akceptują ani plików cookie przeglądarki, ani kluczy do zarządzania.

Zarządzanie uwierzytelnianiem API

Wybierz "Nowy klucz zarządzania" pod Ustawienia → Klucze API. Jest pokazywany raz, przy tworzeniu; przechowujemy tylko hasz i nie możemy go pokazać ponownie. Na każde życzenie wyślij go jako znak na okaziciela:

curl -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     https://franklymail.com/api/mailboxes

Prośby są JSON w i JSON na zewnątrz. Błąd jest { "error": { "code", "message", "field? } } z dopasowanym statusem HTTP: 401 dla klucza, który jest brakujący, cofnięty lub nieznany, 403 w przypadku trasy, do której klucz nie może dotrzeć, 422 na złe pole.

curl -X POST https://franklymail.com/api/mailboxes \
     -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"domainId":"<uuid>","localPart":"sales"}'

Co klucz zarządzania może nazwać

Ścieżki są względne do https://franklymail.com/api. Ta lista jest wyczerpująca: trasa, na której nie ma odpowiedzi 401 do klucza, cokolwiek to robi dla signed- w przeglądarce.

Obszary

Skrzynki pocztowe

Pseudonimy i przekazywanie

Dodawanie domeny, krok po kroku

POST /domains tworzy go i przekazuje z powrotem zapisy do publikacji. Nic innego nie musi być wywoływane, aby rozpocząć weryfikację, ponieważ kontrole przeprowadzane są na ich własnym harmonogramie.

curl -X POST https://franklymail.com/api/domains \
     -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name":"example.com"}'

# {"id":"<uuid>","domain":"example.com","status":"pending",
#  "ownership":"unproven","sending":"pending","recheckIn":300,
#  "records":[{"key":"mx","type":"MX","host":"example.com","value":"…","status":"missing"},
#             {"key":"spf"…},{"key":"dkim"…},{"key":"dmarc"…}]}

Opublikuj każdy z nich records[] wejście do swojego DNS dostawcy, a następnie oglądać GET /domains, ten sam ładunek dla każdej domeny, więc jeden sondaż obejmuje całą partię. Trzy pola odpowiadają na trzy różne pytania, a ich łączenie jest zwykłą pomyłką:

• records[].status: live Gdy DNS odpowie na nasze oczekiwania, missing Do tego czasu.
• ownership: proven Kiedy skończy się rekord DKIM. To jest ten, który blokuje skrzynki pocztowe i import, więc poczta może być skopiowana na długo przed podłączeniem MX.
• status: cała dziedzina, active gdy wszystko, w tym MX jest na żywo i poczta rzeczywiście przybędzie.

recheckIn to sekundy do następnej automatycznej kontroli; spać mniej więcej tak długo między sondażami, a nie młotkiem. POST /domains/:id/recheck wymusza natychmiast i jest ograniczona stawka na domenę, więc używać go po publikacji rekordów, a nie jako pętli wyborczej. Trasa jest idemstrong na konto i nazwę: przeksięgowanie domeny masz już zwraca istniejący, a nie duplikat lub błąd.

Przesuwanie skrzynki pocztowej, krok po kroku

Jest to przepływ większość skryptów są napisane dla, i ten z ruchomych części warte określenia, a nie pozostawiając do odkrycia.

1. Zacznij. POST /mailboxes/:id/import ze szczegółami połączeń starego serwera. Hasło jest zaszyfrowane, zanim dotknie kolumny, nigdy nie zostanie zwrócone przez żadną trasę i wyczyszczone w momencie zakończenia zadania.

curl -X POST https://franklymail.com/api/mailboxes/<mailboxId>/import \
     -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"host":"imap.oldhost.com","port":993,"username":"you@old.com","password":"…"}'

# 202 {"importId":"<uuid>","status":"pending"}

Odpowiada. 202, nie 200: kopia trwa od minut do godzin, więc zadanie jest w kolejce i wniosek wraca natychmiast. Jeden import na raz na skrzynkę pocztową. Rozpoczynając od sekundy, podczas gdy jeden uruchamia odpowiedzi 409 import_in_progress z identyfikatorem pracy uruchomionej, ponieważ dwie równoległe kopie tego samego źródła duplikują każdą wiadomość i powtórka tego nie cofnie. 30 skrzynek pocztowych może importować jednocześnie; limit jest na skrzynkę pocztową, nie na konto.

2. Podążaj za nim. GET /mailboxes/:id/import zwraca ostatnią pracę dla tej skrzynki pocztowej, lub {"import": null} jeśli nigdy takiego nie było.

curl -H "Authorization: Bearer $FRANKLYMAIL_API_KEY" \
     https://franklymail.com/api/mailboxes/<mailboxId>/import

# {"import":{"id":"<uuid>","status":"running","folders_done":2,"folders_total":9,
#            "messages_done":1841,"messages_skipped":3,"current_folder":"INBOX",
#            "last_error":null,"started_at":"…","finished_at":null}}

status jest jednym z pending, running, done, failed lub cancelledA ostatnie trzy są śmiertelne. Przeanalizuj to w kolejności sekund, a nie milisekund; odczyty nie są ograniczone kursem, ale liczniki poruszają się tylko tak szybko, jak inne serwery odpowiadają. folders_done / folders_total jest uczciwą wartością postępu: messages_done nie ma mianownika dopóki folder nie zostanie otwarty, więc procent zbudowany z niego będzie skakać do tyłu. W przypadku porażki, last_error posiada napisane zdanie, które ma być pokazane osobie.

3. Przestań, jeśli musisz.POST /mailboxes/:id/import/cancel Kończy pracę w biegu. Nic nie zmienia się u starego dostawcy. Import tylko z niego czyta. Wiadomości już skopiowane pobyt chyba, że wniosek wyraźnie poprosi inaczej.

Dwie rzeczy, które warto wiedzieć, zanim to spiszesz. Skrzynka pocztowa potrzebuje sprawdzonego rekordu DKIM, a nie pełnego MX, więc kopia może być uruchomiona na kilka dni przed przełączeniem poczty. I nasze rozmieszczenie ponownie uruchamia panel: praca, która była uruchomiona zatrzymuje się i nie wraca sama, więc skrypt, który rozpoczyna trzydzieści importu powinien sprawdzić ich status później niż zakładając milczenie oznacza sukces.

Usuwanie rzeczy

Dwie zasady, i są jedynymi miejscami, w których API odmawia wykonania tego, o co prosiłeś:

• Poczta pocztowa zatrzymuje pocztę, kiedy ją usuniesz.DELETE /mailboxes/:id usuwa adres z serwisu i zostawia każdą wiadomość tam, gdzie jest. Aby zniszczyć również pocztę, prośba musi to powiedzieć i potwierdzić dokładną liczbę bajtów panel pokazał. Jeśli skrzynka pocztowa wzrosła od tego czasu, zniszczenie jest raczej odmawiane, niż milczenie biorąc dodatkowe. Żaden agent nie może przez przypadek zniszczyć wiadomości.
• Domena nie może być usunięta, gdy na niej są skrzynki pocztowe. Dostajesz 409 domain_has_mailboxes wykaz adresów i które z nich zostały wykorzystane. Najpierw usuń każdą skrzynkę pocztową: to jest krok, w którym pytanie o pocztę jest zadawane, raz na skrzynkę pocztową, przez tego, kto ma prawo na nie odpowiedzieć.

Jeśli pacjent jest agentem: Nie odpowiadaj na żadne pytanie w imieniu człowieka. Usuwanie skrzynki pocztowej jest odwracalne do czasu zniszczenia poczty i nigdy po niej. Kiedy zadanie wymaga zniszczenia, powiedz, co zostanie zniszczone i niech osoba zdecyduje.

Wyciąganie poczty

Skrzynka pocztowa może być pobrana jako zip plików mbox, każdego folderu, każdej wiadomości, ale nie za pomocą klucza API. GET /mailboxes/:id/export odpowiedzi 403 browser_only do klucza, ponieważ ta jedna trasa przekazuje pocztę, a nie konfigurację wokół niego, a klucz mieszka w dokładnie takich miejscach, z których wycieka tajemnica.

Do eksportu: otworzyć skrzynkę pocztową w panelu i użyć Pobierz. Płynie, gdy się buduje, więc skrzynka pocztowa jest większa od pamięci i nie ma na co czekać. Jeśli chcesz go z terminala, zaloguj się do panelu w przeglądarce i wywołaj ten sam adres URL z tą sesją. Trasa jest niezmieniona, tylko klucze są odrzucane.

Zrób to. przed Usuwam wszystko, co może ci się przydać. Eksport to jedyna kopia, która przetrwa zniszczenie.

Co klucz nie może zrobić

Klucz jest wyskalowany na jedno konto i, w nim, na trzy rzeczy powyżej. Nie może pobrać skrzynki pocztowej, nie może uzyskać rachunku, nie może zarejestrować domeny (która wydaje pieniądze), nie może utworzyć hasła aplikacji, nie może zmienić hasła konta lub 2FA, ani nie może utworzyć lub cofnąć innego klucza API, w tym siebie. Te wszystkie potrzebują signed- w przeglądarce.

Powodem jest kształt wiarygodności, a nie nieufność: klucz żyje w .env plik, tajny sklep informacyjny i środowisko agenta, i sekret, który mieszka w trzech miejscach nie powinien być w stanie wziąć na konto lub zablokować jego właściciela. Jeśli klucz wycieka, należy go cofnąć w Ustawieniach: posiadacz nie może najpierw zmentować zamiennika.

Czego ta granica nie twierdzi. Klucz może ustawić hasło skrzynki pocztowej, ponieważ tworzenie i rozdawanie skrzynek pocztowych jest zadaniem, dla którego istnieje, a każdy, kto może ustawić hasło skrzynki pocztowej może się zalogować do tej skrzynki pocztowej ponad IMAP i przeczytać ją. Zamknięcie export nie zmienia tego i udawanie, że inaczej byłoby gorszym rodzajem bezpieczeństwa niż żadne. Zmienia się to, że ścieżka nie jest już cicha: resetowanie hasła blokuje prawdziwego użytkownika z ich własnej skrzynki pocztowej, która jest zauważana w ciągu godziny, podczas gdy pobieranie nie pozostawia nic za sobą, tylko linię dziennika. Jeśli ten handel nie jest tym, którego chcesz dla danego klucza, nie twórz klucza: klawisze zarządzania nie mają żadnych zakresów zasobów. Użyj połączenia Agentic Inbox OAuth do skrzynki pocztowej zweryfikowanej za pośrednictwem poczty internetowej.

Klucze do zarządzania nie wygasają. Dziesięć żywych kluczy na konto, które jest pułapem, a nie kontyngentem, więc nazwa ich na skrypt lub na maszynę, więc cofnięcie jednego jest oczywistą decyzją.

Zmiana hasła konta cofa każdy klucz, na rutynowej rotacji tak samo jak na rekonwalescencji. Nikt nie może odróżnić tych dwóch od siebie w chwili, gdy wpisują nowe hasło, więc bezpieczna odpowiedź nie zależy od tego, która z nich była. Plan dla niego: długoletni skrypt powinien zawieść głośno na 401 Zamiast próbować ponownie, a ktokolwiek obróci hasło, wytrąca nowy klucz. Wysyłamy email posiadaczowi konta za każdym razem, gdy jest tworzony klucz i ponownie, gdy zmiana hasła je cofa, więc klucz wykonany przez kogoś innego nie pozostaje niezauważony.

API zarządzania i limity stawek eksportowych

Dwa liczniki, zarówno na konto, jak i na klucz, więc obracanie klucza nie resetuje ich:

• 120 pisze co 5 minut przez domeny, skrzynki pocztowe i pseudonimy. Odczyty nie są liczone, więc sondowanie domeny do czasu sprawdzenia jest wolne. Przenoszenie dziesięciu domen i trzydziestu skrzynek pocztowych kosztuje znacznie poniżej stu pisów w sumie, więc normalna praca luzem nie osiąga tego.
• 30 eksportuje skrzynki pocztowe na godzinę. Eksport strumieniuje każdą wiadomość w skrzynce pocztowej, co jest najdroższą rzeczą, o jaką można poprosić API.

* Over anone you get * 429 z { "error": { "code": "rate_limited" } } oraz Retry-After Nagłówek w sekundach. Czekać tak długo, a nie ponownie natychmiast: wielokrotnie uderzając limit wydłuża pauzę. Jeśli legalna praca potrzebuje więcej miejsca pracy, piszcie do nas, a nie do nas; wolelibyśmy zwiększyć liczbę, niż dowiedzieć się z rachunku.

Przenoszenie kilku domen jednocześnie

Zamówienie, które działa: POST /domains dla każdej nazwy, publikuje rekordy, które zwraca, ankieta GET /domains do czasu zweryfikowania każdego z nich, POST /mailboxes na adres. Poczta może być kopiowana ze starego hosta przed MX cutover, ponieważ domena potrzebuje tylko swojego rekordu DKIM sprawdzone dla POST /mailboxes/:id/import aby uruchomić, tak aby migracja i przełączanie nie musiały mieć miejsca w tym samym dniu.

MCP

Agentic Inbox zapewnia zdalny punkt końcowy MCP w https://franklymail.com/api/agent/mcp do czytania, wyszukiwania i przygotowywania projektów skrzynek pocztowych. Połącz przez OAuth za pomocą prowadnica konfiguracji. Zaopatrzenie domeny i administracja skrzynki pocztowej używają oddzielnego zarządzania HTTP API udokumentowane powyżej.