Referentie API

Gebruik Agentic Inbox om een mailbox aan te sluiten op een assistent, of de beheer API om uw organisatie domeinen, mailboxen en aliassen te beheren. Deze maken gebruik van aparte referenties en machtigingen. Kies hieronder de integratie die u nodig heeft.

Agentic Inbox

Verbind via OAuth met PKCE op https://franklymail.com/api/agent/mcp. De verbindingshandleiding heeft betrekking op ChatGPT en Claude opstelling. Meld je aan bij webmail. Elke OAuth subsidie is gebonden aan die ene geverifieerde mailbox. Gebruik van subsidies mailbox.read, message.read, message.search en draft.write. Er is geen automatische verzendtoestemming.

Concepten geven een herzieningslink terug. Alleen een sessie die voor die mailbox is geverifieerd, kan de exacte huidige versie goedkeuren. Een panel-accountsessie kan geen toestemming geven of goedkeuren. Hulpmiddelargumenten of een chatbericht kunnen het verzenden niet autoriseren.

Voor mapspecifieke zoekopdrachten, pas folder als inbox, sent, drafts, archive, trash of junk (spam is een alias). Gebruik list_folders en folderId voor aangepaste mappen. Kies één selectie; een ontbrekende map geeft een foutmelding terug in plaats van alle e-mail te zoeken. Beide zoekopdrachten niet doorzoeken.

prepare_forward vereist mailboxId, messageId, requestKey en to; cc en inleiding text zijn facultatief. Het vereist beide message.read en draft.write. Originele headers en leesbare tekst worden automatisch meegeleverd. Bijlagen vereisen webmail, of de expliciete tekstkeuze van de gebruiker alleen met behulp van omitAttachments: true. Onvolledige of te grote originelen worden afgewezen. Voorontwerpen maken gebruik van dezelfde toetsings- en goedkeuringsstroom als antwoorden.

De menselijke review pagina ondersteunt het bewerken van ontvangers, onderwerp en bericht. Mailbox Boost voegt ook optioneel Track opent en Schrijf met AI. Tracking is uitgeschakeld totdat geselecteerd en opgeslagen. Een gedeeld bericht naar meerdere geadresseerden kan niet identificeren welke ontvanger het heeft geopend. Privacyproxies kunnen open signalen beïnvloeden; kijk activiteit in webmail.

De AI schrijver vereist toestemming voor de mailbox en deelt de webmail writing toelage. Het gebruikt de opgeslagen ontwerp-, onderwerp-, ontvangers- en schrijfinstructies om een suggestie tot en met OpenAI. Het toepassen van een suggestie is een bewerking, gevolgd door opslaan en een verse menselijke goedkeuring. Geen van beide functies voegt een MCP-hulpprogramma of een verzendmachtiging toe; agenten kunnen dit niet instellen trackOpens of bel de browserschrijver.

OAuth maakt gebruik van autorisatiecode met S256 PKCE en resource=https://franklymail.com/api/agent/mcp. Ontdek configuratie op de metadata van de beschermde hulpbron en authorization servermetadata. Dynamische client registratie wordt ondersteund. Toegang tokens duren een uur; verfrissen tokens roteren. Het hergebruiken van een verfrissende token trekt de verbinding in. Subsidies duren tot 90 dagen.

MCP gebruikt staatloze streamable HTTP met JSON-responsen. Oproep tools/list Voor schema's. Succesvolle oproepen omvatten result.structuredContent; gereedschapsfouten kunnen HTTP 200 teruggeven met result.isError=true en een JSON tekstblok met error. Controleer zowel de HTTP-respons als het gereedschapsresultaat. Authenticatiefouten gebruiken HTTP 401.

Equivalente HTTP-routes: GET /api/v1/mailboxes/:id/messages, GET /api/v1/mailboxes/:id/messages/:messageId, POST /api/v1/drafts, GET /api/v1/drafts/:id en PUT /api/v1/drafts/:id. Zoeken accepteert folder of folderId, text, from, subject, unread, limit (1 t/m 25) en position. Ontwerp-aanmaak vereist mailboxId, requestKey, to, subject, text; cc en replyToMessageId zijn facultatief. Herziening vereist de huidige version en volledige vervangende ontvangers, onderwerp en tekst.

Maplijst en doorsturen gebruiken de MCP-tools list_folders en prepare_forward; ze hebben geen aparte HTTP routes. Concepten ondersteuning maximaal 10 Aan en Cc ontvangers gecombineerd, een 256-karakter onderwerp en 20,000-karakter bericht, en vervallen na 24 uur. Ze blijven in Agentic Inbox totdat goedgekeurd; verzonden berichten verschijnen in webmail.

Agentic Inbox maakt 25 verzoeken per dag en 5/minuut per postbus mogelijk; Boost verhoogt dit tot 2,500/dag en 60/minuut. Verbindingen met dezelfde mailbox delen de vergoeding. Wachtwoordwijzigingen trekken mailboxsessies en verbindingen in. Bestaande account-geautoriseerde inbox subsidies moeten opnieuw worden verbonden via webmail. De dagvergoedingen worden om middernacht gereset. Handmatige toetsing en goedkeuring maken geen gebruik van deze vrijstelling. Bij een limietfout, respect Retry-After en error.resetsAt; toon de bijgeleverde Boost-link bij uitputting van het standaardplan.

Voor wie kunt u mailboxen aanmaken

Eén account is één organisatie. Mailboxen zijn voor de mensen in de jouwe: medewerkers, aannemers, uw eigen projecten, aliassen en gedeelde adressen. Dat zijn ze. niet voor klanten die u in rekening brengt of dient. Het doorverkopen van FranklyMail brievenbussen, of het uitvoeren van een account namens iemand anders als een dienst waarvoor u wordt betaald, is een inbreuk op de termen. Zie de verkoopclausule daar. Het runnen van verschillende domeinen die je bezit is prima en is altijd geweest; een holding met vijftien merken is één organisatie. Een agentschap met vijftien klanten is dat niet.

Er is geen quota voor brievenbussen om dat onderscheid af te dwingen. Als een account groeit een vorm die leest als meerdere organisaties, schrijven en vragen we. Niets wordt opgeschort vanwege een vraag.

Legacy resource API: alleen metadata

Bestaande brongegevens behouden hun oorspronkelijke machtigingen. Om toegang tot e-mailinhoud mogelijk te maken, maakt u een nieuwe verbinding met behulp van de hulpverbindingshandleiding. Alleen toegewezen sleutels domain.read en mailbox.read alleen metadata lezen. Ze kunnen geen berichten lezen, e-mail versturen of bronnen wijzigen. Nieuw aangemaakte mailboxen en domeinen krijgen nooit automatisch toegang.

Stuur de sleutel als Authorization: Bearer fma_.... Paden hieronder zijn relatief met https://franklymail.com/api.

Lijsten accepteren limit van 1 tot 100 (standaard 50) en een UUID cursor van het vorige antwoord. Ze keren terug. { data: [...], nextCursor, requestId }; details retourneren { data: {...}, requestId }. Byte-tellingen zijn decimale tekenreeksen. DNS resultaten worden opgeslagen observaties.

Standaard beperkte toegang maakt 25 verzoeken per dag en 5/minuut, gedeeld over de sleutels van de rekening. Mailbox Boost verhoogt dit tot 2.500/dag en 60/minuut per geabonneerde brievenbus. Dagen reset om middernacht UTC. Belangrijkste plafonds standaard tot 60/minuut, instelbaar van 1 tot 600, met een apart veiligheidsplafond voor gedeelde rekening van 600/minuut.

Elke geretourneerde Boost mailbox gebruikt één verzoek uit eigen zakgeld. Elke standaard resources op de pagina delen een standaard verzoek. Alle benodigde emissierechten moeten beschikbaar zijn; een afgewezen pagina geeft geen van hen uit. Een lege pagina gebruikt de standaard vergoeding. Domein en DNS leest kan de toelage van de eerste Boost mailbox door UUID in dat domein gebruiken, alleen als de sleutel expliciet verleent mailbox.read Voor het ook. Dit vergroot de toegang tot andere mailboxen niet.

Aan 429, eer Retry-After en error.resetsAt. Dagelijks gebruik van uitputting daily_quota_exceeded; gebruik van minieme limieten rate_limited. De standaardplanlimieten omvatten: error.metadata.upgrade met de Boost link en hogere vergoedingen. Toon die link naar de persoon die de mailbox beheert. Een agent kan geen upgrade kopen. Boost uitputting en sleutel/account veiligheidsplafonds hebben geen upgrade aanbod. X-Agent-Plan identificatie van standaard, boost of gemengde toegang; X-Agent-Daily-Limit, X-Agent-Daily-Remaining en X-Agent-Daily-Reset de vereiste dagvergoeding te beschrijven met de weinige verzoeken die nog over zijn. Sleutelplafonds tellen nog steeds authentieke ontkenningen. Ontbrekende scope geeft terug 403; een hulpbron buiten het subsidierendement 404; een verlopen of ingetrokken sleutel geeft terug 401. Beperkte werkzaamheden op het gebied van geloofsbrieven /api/v1 en /api/agent/mcp binnen hun oorspronkelijke scopes. Deze routes accepteren noch browser cookies noch beheersleutels.

Beheer API-authenticatie

Kies een nieuwe beheersleutel onder Instellingen → API-sleutels. Het wordt eenmaal getoond, bij de schepping; we slaan slechts een hasj op en kunnen het niet meer laten zien. Stuur het als een token aan token op elk verzoek:

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

De verzoeken zijn JSON in en JSON uit. Een fout is { "error": { "code", "message", "field? } } met de bijbehorende HTTP-status: 401 voor een sleutel die ontbreekt, ingetrokken of onbekend is, 403 voor een route die een sleutel niet kan bereiken, 422 Voor een slecht veld.

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

Wat een management sleutel kan noemen

Paden zijn relatief met https://franklymail.com/api. Deze lijst is volledig: een route waarop geen antwoord wordt gegeven 401 aan een sleutel, wat het ook doet voor een ingelogde browser.

Domeinen

Postbussen

Bijnamen en doorsturen

Een domein toevoegen, stap voor stap

POST /domains maakt het en geeft de documenten terug om te publiceren. Er hoeft niets anders te worden gevraagd om te beginnen met de verificatie, aangezien de controles op hun eigen schema lopen.

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"…}]}

Publiceer elk records[] entry bij uw DNS provider, kijk dan GET /domains, dezelfde lading voor elk domein, dus een peiling dekt een hele partij. Drie velden beantwoorden drie verschillende vragen, en ze samenbrengen is de gebruikelijke fout:

• records[].status: live Eenmaal DNS beantwoordt wat we verwachten, missing Tot dan.
• ownership: proven Zodra het DKIM record op is. Dit is degene die mailboxen en importeert., zodat post kan worden gekopieerd lang voordat de MX is verwisseld.
• status: het hele domein, active wanneer alles inclusief MX live is en de post daadwerkelijk zal arriveren.

recheckIn is seconden tot de volgende automatische controle; slaap ongeveer zo lang tussen polls in plaats van hameren. POST /domains/:id/recheck dwingt men onmiddellijk en is per domein beperkt tarief, dus gebruik het na het publiceren van records, niet als een polling lus. De route is idempotent per account en naam: het opnieuw posten van een domein dat je al hebt, geeft de bestaande terug in plaats van een duplicaat of een fout.

Een mailbox stap voor stap verplaatsen

Dit is de flow waar de meeste scripts voor geschreven zijn, en degene met bewegende delen die de moeite waard zijn om te vermelden in plaats van te vertrekken om ontdekt te worden.

1. Begin maar. POST /mailboxes/:id/import met de gegevens van de oude server. Het wachtwoord wordt versleuteld voordat het een kolom aanraakt, nooit via welke route dan ook wordt teruggestuurd, en het moment dat de taak stopt.

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"}

Het antwoordt. 202, niet 200: een kopie duurt minuten tot uren, zodat de opdracht in de wachtrij staat en het verzoek onmiddellijk terugkeert. Eén import per keer per mailbox. Een seconde beginnen terwijl een draait antwoorden 409 import_in_progress met het id van de lopende taak, omdat twee gelijktijdige kopieën van dezelfde bron elk bericht dupliceren en een herhaling dat niet ongedaan maakt. Dertig mailboxen kunnen tegelijk importeren; de limiet is per mailbox, niet per account.

2. Volg het. GET /mailboxes/:id/import de nieuwste taak voor die mailbox teruggeeft, of {"import": null} Als er nooit een is geweest.

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 is een van pending, running, done, failed of cancelled, en de laatste drie zijn terminal. Poll het op de volgorde van seconden, geen milliseconden; lees is niet beperkt maar de tellers bewegen alleen zo snel als de andere server antwoordt. folders_done / folders_total is de eerlijke vooruitgang figuur: messages_done heeft geen noemer totdat een map is geopend, dus een percentage dat er uit is opgebouwd zal achteruit springen. Bij een mislukking, last_error draagt een zin geschreven om te worden getoond aan een persoon.

3. Hou op, als het moet.POST /mailboxes/:id/import/cancel Stop de lopende baan. Niets wordt veranderd bij de oude provider door een van deze. Een import leest er alleen maar uit. Berichten die al zijn gekopieerd blijven, tenzij het verzoek uitdrukkelijk anders vraagt.

Twee dingen die het waard zijn om te weten voordat je dit script. Een mailbox moet de DKIM record van zijn domein bewezen, niet de volledige MX cutover, zodat de kopie kan draaien dagen voordat u de mail overschakelt. En een inzet van ons start het paneel opnieuw op: een taak die werd uitgevoerd stopt en niet op zichzelf hervat, dus een script dat dertig importen begint moet hun status achteraf controleren in plaats van ervan uit te gaan dat stilte succes betekent.

Dingen verwijderen

Twee regels, en zij zijn de enige plaatsen waar deze API weigert te doen wat je vroeg:

• Een mailbox bewaart zijn e-mail wanneer u deze verwijdert.DELETE /mailboxes/:id neemt het adres uit dienst en laat elk bericht achter waar het is. Om de e-mail ook te vernietigen, moet het verzoek dat zeggen en de exacte bytetelling bevestigen die het paneel u liet zien. Als de mailbox sindsdien is gegroeid, wordt de vernietiging geweigerd in plaats van stilletjes de extra te nemen. Niets wat een agent per ongeluk doet, kan een boodschap vernietigen.
• Een domein kan niet worden verwijderd als er mailboxen op staan. Je krijgt 409 domain_has_mailboxes een lijst van de adressen en de gebruikte adressen. Verwijder eerst elke mailbox: dat is de stap waar de vraag over de mail wordt gesteld, eenmaal per mailbox, door degene die het recht heeft om deze te beantwoorden.

Als u een agent bent: Beantwoord geen van beide vragen namens de mens. Het verwijderen van een brievenbus is omkeerbaar totdat de post is vernietigd en nooit daarna. Wanneer een taak vernietiging impliceert, zeg dan wat vernietigd zou worden en laat de persoon beslissen.

De post naar buiten halen

Een mailbox kan worden gedownload als een zip van mbox-bestanden, elke map, elk bericht, maar niet met een API-sleutel. GET /mailboxes/:id/export antwoorden 403 browser_only naar een sleutel, want die ene route geeft de post zelf over in plaats van de configuratie er omheen, en een sleutel leeft op precies de plaatsen waar geheimen lekken.

Exporteren: open de mailbox in het paneel en gebruik Download. Het stroomt naarmate het opbouwt, zodat er nog steeds een mailbox komt die groter is dan het geheugen, en er is geen taak om op te wachten. Als je het wilt van een terminal, meld je aan in het paneel in een browser en bel dezelfde URL met die sessie. De route is ongewijzigd, alleen sleutels worden geweigerd.

Doe dit. voor Alles verwijderen wat je maar terug wilt. Een export is het enige exemplaar dat een vernietiging overleeft.

Wat een sleutel niet kan doen

Een sleutel is op één rekening en, binnenin, op de drie bovenstaande dingen gericht. Het kan geen mailbox downloaden, kan geen facturering bereiken, kan geen domein registreren (dat geld uitgeeft), geen app-wachtwoorden aanmaken, uw wachtwoord of 2FA niet wijzigen en kan geen andere API-sleutel aanmaken of intrekken, inclusief zichzelf. Die hebben allemaal een ingelogde browser nodig.

De reden is de vorm van het geloof in plaats van wantrouwen: een sleutel leeft in een .env bestand, een geheime CI-winkel en de omgeving van een agent, en een geheim dat op drie plaatsen woont mag niet in staat zijn om een rekening over te nemen of de eigenaar buiten te sluiten. Als een sleutel lekt, herroept u het in Instellingen: de houder kan een vervanging niet eerst slaan.

Wat die grens niet claimt. Een sleutel kan een mailbox wachtwoord instellen, omdat het maken en uitdelen van mailboxen de taak is waarvoor het bestaat, en iedereen die een mailbox wachtwoord kan instellen kan zich dan aanmelden bij die mailbox boven IMAP en het lezen. Sluiting export dat niet verandert, en doen alsof anders zou een slechter soort beveiliging dan geen. Wat wel verandert is dat het pad niet langer stil is: het resetten van een wachtwoord vergrendelt de echte gebruiker uit zijn eigen mailbox, wat binnen het uur wordt opgemerkt, terwijl een download niets achterlaat dan een logregel. Als die handel niet degene is die je wilt voor een bepaalde sleutel, maak dan niet de sleutel: managementsleutels hebben geen per-resource scopes. Gebruik een Agentic Inbox OAuth verbinding voor een mailbox die via webmail is geverifieerd.

Beheerssleutels verlopen niet. Tien live keys per account, dat is een maximum in plaats van een quota, dus noem ze per script of per machine dus het intrekken van een is een voor de hand liggende beslissing.

Het wijzigen van het wachtwoord van het account trekt elke sleutel in, op een routine rotatie net zo veel als op een herstel. Niemand kan die twee uit elkaar houden op het moment dat ze een nieuw wachtwoord typen, dus het veilige antwoord hangt niet af van het weten welke het was. Plan voor het: een langlopend script zou moeten falen luid op een 401 in plaats van opnieuw te proberen, en wie het wachtwoord munt een nieuwe sleutel achteraf. We e-mailen de accounthouder telkens wanneer een sleutel wordt aangemaakt, en opnieuw wanneer een wachtwoordwijziging hen intrekt, zodat een sleutel gemaakt door iemand anders niet onopgemerkt blijft.

Beheer API en uitvoerpercentages

Twee tellers, beide per account in plaats van per sleutel, zodat het roteren van een sleutel ze niet reset:

• 120 schrijft elke 5 minuten over domeinen, mailboxen en aliassen. Leest worden niet geteld, dus polling een domein totdat het controleren is gratis. Het verplaatsen van tien domeinen en dertig brievenbussen kost in totaal ruim onder de honderd brieven, zodat normaal bulkwerk dit niet bereikt.
• 30 mailbox export per uur. Een export streamt elk bericht in de mailbox, dat is het duurste wat deze API kan worden gevraagd om te doen.

Over beide krijg je 429 met { "error": { "code": "rate_limited" } } en a Retry-After Header in seconden. Wacht zo lang in plaats van onmiddellijk opnieuw te proberen: herhaaldelijk raken van de limiet verlengt de pauze. Als een legitieme baan meer hoofdruimte nodig heeft, schrijf ons dan in plaats van er omheen te werken; we verhogen liever het aantal dan erachter te komen van een wetsvoorstel.

Meerdere domeinen tegelijk verhuizen

De volgorde die werkt: POST /domains voor elke naam, publiceren van de gegevens die het retourneert, poll GET /domains totdat elk wordt geverifieerd, dan POST /mailboxes per adres. Mail kan worden gekopieerd van de oude host voor de MX cutover, omdat een domein hoeft alleen de DKIM record bewezen voor POST /mailboxes/:id/import om te lopen, zodat de migratie en de omschakeling niet hoeven te gebeuren op dezelfde dag.

MCP

Agentic Inbox geeft het MCP-eindpunt op afstand op https://franklymail.com/api/agent/mcp voor het lezen van de brievenbus, het zoeken en het opstellen van ontwerpen. Verbinden via OAuth met behulp van de setup guide. Domein provisioning en mailbox administratie gebruiken de gescheiden beheer HTTP API die hierboven is gedocumenteerd.