Référence API

Utilisez Agentic Inbox pour connecter une boîte aux lettres à un assistant, ou l'API de gestion pour administrer les domaines, boîtes aux lettres et alias de votre organisation. Ceux-ci utilisent des identifiants et des permissions séparés. Choisissez l'intégration dont vous avez besoin ci-dessous.

Agentic Inbox

Connectez-vous à OAuth avec PKCE à https://franklymail.com/api/agent/mcpC'est vrai. Les guide de connexion couvre ChatGPT et Claude configuration. Connectez-vous à webmail. Chaque subvention OAuth est liée à cette seule boîte aux lettres vérifiée. Utilisation des subventions mailbox.read, message.read, message.search et draft.writeC'est vrai. Il n'y a pas de permission d'envoi automatique.

Les ébauches renvoient un lien d'examen. Seule une session vérifiée pour cette boîte aux lettres peut approuver la version actuelle exacte. Une session de compte d'un groupe spécial ne peut pas consentir ou approuver. Les arguments d'outil ou un message de chat ne peuvent pas autoriser l'envoi.

Pour les recherches spécifiques à un dossier, passez folder comme inbox, sent, drafts, archive, trash ou junk (spam est un pseudonyme). Utilisation list_folders et folderId pour les dossiers personnalisés. Choisissez un sélecteur; un dossier manquant renvoie une erreur au lieu de rechercher tous les courriels. L'omission des deux recherche chaque dossier.

prepare_forward nécessite mailboxId, messageId, requestKey et to; cc et introduction text sont facultatifs. Il faut que les deux message.read et draft.writeC'est vrai. Les en-têtes originaux et le texte lisible sont inclus automatiquement. Les pièces jointes nécessitent le webmail, ou le choix explicite de l'utilisateur de texte uniquement en utilisant omitAttachments: trueC'est vrai. Les originaux incomplets ou surdimensionnés sont rejetés. Les projets avancés utilisent le même flux d'examen et d'approbation que les réponses.

La page d'examen humain prend en charge l'édition des destinataires, du sujet et du message. Mailbox Boost ajoute également optionnel Ouverture de la piste et Écrire avec l'IAC'est vrai. Le suivi est désactivé jusqu'à ce que sélectionné et enregistré. Un message partagé envoyé à plusieurs destinataires ne peut pas identifier le destinataire qui l'a ouvert. Les procurations de confidentialité peuvent affecter les signaux ouverts; afficher l'activité dans le webmail.

L'auteur de l'IA a besoin du consentement de la boîte aux lettres et partage l'indemnité d'écriture du courriel Web. Il utilise l'ébauche sauvegardée, le sujet, les destinataires et les instructions d'écriture pour préparer une suggestion au moyen de OpenAI. L'application d'une suggestion est une modification, suivie d'une sauvegarde et d'une nouvelle approbation humaine. Aucune fonctionnalité n'ajoute un outil MCP ou une permission d'envoi; les agents ne peuvent pas définir trackOpens ou appelez l'auteur du navigateur.

OAuth utilise le code d'autorisation avec S256 PKCE et resource=https://franklymail.com/api/agent/mcpC'est vrai. Découvrez la configuration à les métadonnées des ressources protégées et métadonnées du serveur d'autorisationC'est vrai. L'enregistrement dynamique des clients est pris en charge. Les jetons d'accès durent une heure; les jetons de rafraîchissement tournent. La réutilisation d'un jeton rafraîchi annule la connexion. Les subventions durent jusqu'à 90 jours.

MCP utilise apatride Streamable HTTP avec les réponses JSON. Appeler tools/list pour les schémas. Les appels réussis comprennent : result.structuredContent; les erreurs d'outil peuvent renvoyer HTTP 200 avec result.isError=true et un bloc de texte JSON contenant errorC'est vrai. Vérifiez à la fois la réponse HTTP et le résultat de l'outil. Les défaillances d'authentification utilisent HTTP 401.

Routes HTTP équivalentes : GET /api/v1/mailboxes/:id/messages, GET /api/v1/mailboxes/:id/messages/:messageId, POST /api/v1/drafts, GET /api/v1/drafts/:id et PUT /api/v1/drafts/:idC'est vrai. La recherche accepte folder ou folderId, text, from, subject, unread, limit (1 à 25) et positionC'est vrai. Le projet de création nécessite mailboxId, requestKey, to, subject, text; cc et replyToMessageId sont facultatifs. La révision nécessite la révision actuelle version et complète les destinataires de remplacement, le sujet et le texte.

La liste des dossiers et le renvoi utilisent les outils MCP list_folders et prepare_forward; ils n'ont pas de routes HTTP séparées. Les ébauches soutiennent au plus 10 destinataires To et Cc combinés, un sujet de 256-caractère et un message de 20,000-caractère, et expirent après 24 heures. Ils restent en Agentic Inbox jusqu'à ce qu'ils soient approuvés; les messages envoyés apparaissent dans le webmail.

Agentic Inbox permet 25 requêtes/jour et 5/minute par boîte aux lettres; Boost augmente cela à 2,500/jour et 60/minute. Les connexions à la même boîte aux lettres partagent son avantage. Les changements de mot de passe annulent les sessions de boîte aux lettres et les connexions. Les subventions de boîtes de réception autorisées par les comptes doivent se reconnecter par courriel Web. Les indemnités journalières sont réinitialisées à minuit UTC. L'examen et l'approbation manuels n'utilisent pas cette indemnité. Sur une erreur de limite, respect Retry-After et error.resetsAt; montrez le lien Boost fourni sur l'épuisement standard du plan.

Qui vous pouvez créer des boîtes aux lettres pour

Un compte est une organisation. Les boîtes aux lettres s'adressent aux personnes qui vous appartiennent : le personnel, les entrepreneurs, vos propres projets, alias et adresses partagées. Ils sont pas pour les clients que vous facturez ou servezC'est vrai. La revente de la boîte aux lettres FranklyMail, ou l'exploitation d'un compte pour le compte d'une autre personne comme service pour lequel vous êtes payé, est une violation de la termesC'est vrai. Voyez la clause de revente là-bas. Gérer plusieurs domaines que vous possédez est bien et a toujours été; une société holding avec quinze marques est une organisation. Une agence avec quinze clients ne l'est pas.

Il n'y a pas de quota de compte de boîte aux lettres pour faire respecter cette distinction. Si un compte prend une forme qui se lit comme plusieurs organisations, nous écrivons et demandons. Rien n'est suspendu sur une question.

API de ressources héritées : métadonnées seulement

Les références de ressources existantes conservent leurs autorisations originales. Pour activer l'accès au contenu du courrier, créez une nouvelle connexion en utilisant le guide de connexion assistantC'est vrai. Clés accordées uniquement domain.read et mailbox.read lire les métadonnées seulement. Ils ne peuvent pas lire les messages, envoyer des courriels ou modifier les ressources. Les boîtes aux lettres et les domaines nouvellement créés n'ont jamais accès automatiquement.

Envoyer la clé comme Authorization: Bearer fma_...C'est vrai. Les chemins ci-dessous sont relatifs à https://franklymail.com/api.

Listes acceptées limit de 1 à 100 (par défaut 50) et un UUID cursor de la réponse précédente. Ils reviennent. { data: [...], nextCursor, requestId }; retour des détails { data: {...}, requestId }C'est vrai. Les nombres d'octets sont des chaînes décimales. DNS résultats sont stockés des observations.

L'accès restreint standard permet 25 requêtes/jour et 5/minute, partagées entre les clés du compte. Mailbox Boost le porter à 2 500/jour et 60/minute par boîte aux lettres souscrite. Jours de remise à minuit UTC. Plafonds clés par défaut à 60/minute, réglables de 1 à 600, avec un plafond de sécurité séparé du compte partagé de 600/minute.

Chaque boîte aux lettres Boost retournée utilise une demande de sa propre allocation. Toute ressource standard sur la page partage une demande standard. Toutes les indemnités requises doivent être disponibles; une page rejetée ne dépense aucune d'entre elles. Une page vide utilise l'allocation standard. Domain et DNS readis peuvent utiliser l'allocation de la première boîte aux lettres Boost par UUID dans ce domaine, seulement lorsque la clé octroie explicitement mailbox.read pour ça aussi. Cela n'augmente pas l'accès aux autres boîtes aux lettres.

À 429, honneur Retry-After et error.resetsAtC'est vrai. Utilisations quotidiennes d'épuisement daily_quota_exceeded; utilisation des limites de minute rate_limitedC'est vrai. Les limites du plan standard comprennent : error.metadata.upgrade avec le lien Boost et des indemnités plus élevées. Afficher ce lien vers la personne qui gère la boîte aux lettres. Un agent ne peut pas acheter de mise à niveau. Augmenter l'épuisement et les plafonds de sécurité des clés et des comptes n'ont pas d'offre de mise à niveau. X-Agent-Plan identifie l'accès standard, boost ou mixte; X-Agent-Daily-Limit, X-Agent-Daily-Remaining et X-Agent-Daily-Reset décrire l'indemnité journalière requise avec le nombre le plus faible de demandes restantes. Les plafonds clés comptent toujours les dénégations authentifiées. La portée manquante revient 403; une ressource en dehors des rapports de subvention 404; une déclaration de clé expirée ou révoquée 401C'est vrai. Travaux sur les pouvoirs restreints /api/v1 et /api/agent/mcp dans leur champ d'application initial. Ces itinéraires n'acceptent ni les cookies de navigateur ni les clés de gestion.

Authentification des API de gestion

Choisissez --Nouvelle clé de gestion - Paramètres → touches de l'APIC'est vrai. Il est montré une fois, à la création; nous ne stockons qu'un hachage et nous ne pouvons pas le montrer à nouveau. Envoyez-le comme jeton au porteur sur chaque demande:

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

Les demandes sont JSON in et JSON out. Une erreur est { "error": { "code", "message", "field? } } avec l'état HTTP correspondant : 401 pour une clé manquante, révoquée ou inconnue, 403 pour une route, une clé peut ne pas atteindre, 422 pour un mauvais champ.

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

Ce qu'une clé de gestion peut appeler

Les chemins sont relatifs à https://franklymail.com/apiC'est vrai. Cette liste est exhaustive: un itinéraire qui n'est pas sur elle répond 401 à une clé, quoi qu'il fasse pour un navigateur connecté.

Domaines

Boîtes aux lettres

Alias et transit

Ajouter un domaine, étape par étape

POST /domains crée et rend les documents à publier. Rien d'autre ne doit être appelé pour commencer la vérification, puisque les vérifications sont effectuées selon leur propre horaire.

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

Publier chaque records[] entrée chez votre fournisseur DNS, puis regarder GET /domains, la même charge utile pour chaque domaine, donc un sondage couvre un lot entier. Trois champs répondent à trois questions différentes, et les regrouper est l'erreur habituelle:

• records[].status: live une fois DNS répond à ce que nous attendons, missing D'ici là.
• ownership: proven Une fois le record de DKIM terminé. C'est celui qui porte les boîtes aux lettres et les importations, donc le courrier peut être copié bien avant que le MX ne soit commuté.
• status: tout le domaine, active lorsque tout y compris MX est en direct et que le courrier arrivera effectivement.

recheckIn est quelques secondes jusqu'à la prochaine vérification automatique; dormir à peu près aussi longtemps entre les sondages plutôt que de marteler. POST /domains/:id/recheck Forcez-en un immédiatement et le taux est limité par domaine, alors utilisez-le après avoir publié des documents, et non comme une boucle de vote. L'itinéraire est idempotent par compte et nom: re-afficher un domaine que vous avez déjà retourné l'ancien plutôt qu'un duplicata ou une erreur.

Déplacement d'une boîte aux lettres, étape par étape

C'est le flux pour lequel la plupart des scripts sont écrits, et celui avec des parties mobiles vaut la peine d'indiquer plutôt que de partir pour être découvert.

1. Démarre. POST /mailboxes/:id/import avec les détails de connexion de l'ancien serveur. Le mot de passe est chiffré avant qu'il touche une colonne, jamais retourné par n'importe quel itinéraire, et a effacé le moment où le travail s'arrête.

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

Il répond 202, pas 200: une copie prend des minutes à des heures, donc le travail est en attente et la demande revient immédiatement. Une importation à la fois par boîte mailC'est vrai. Commencer une seconde pendant qu'on lance des réponses 409 import_in_progress avec l'identifiant de la tâche en cours d'exécution, parce que deux copies simultanées de la même source dupliquent chaque message et qu'une réessayer n'annule pas cela. Trente boîtes aux lettres peuvent être importées en même temps; la limite est par boîte aux lettres, pas par compte.

2. Suivez-le. GET /mailboxes/:id/import retourne le dernier job pour cette boîte aux lettres, ou {"import": null} s'il n'y en a jamais eu.

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 est l'un des pending, running, done, failed ou cancelled, et les trois derniers sont terminaux. Sondagez-le sur l'ordre des secondes, pas des millisecondes; les lectures ne sont pas limitées, mais les compteurs ne bougent que aussi vite que les réponses de l'autre serveur. folders_done / folders_total est le chiffre de progrès honnête: messages_done n'a pas de dénominateur jusqu'à ce qu'un dossier soit ouvert, donc un pourcentage construit à partir de lui va sauter en arrière. Sur un échec, last_error porte une phrase écrite qui doit être montrée à une personne.

3. Arrête, s'il le faut.POST /mailboxes/:id/import/cancel C'est la fin du boulot. Rien n'est changé à l'ancien fournisseur par rien de tout cela. Une importation ne lit que d'elle. Les messages déjà copiés restent à moins que la demande ne demande explicitement le contraire.

Deux choses qui valent la peine d'être connues avant que vous n'écriviez ça. Une boîte aux lettres a besoin de l'enregistrement DKIM de son domaine prouvé, et non de la coupe complète MX, de sorte que la copie peut fonctionner quelques jours avant de passer le courrier. Et un déploiement des nôtres redémarre le panneau : un travail qui était en cours d'exécution s'arrête et ne reprend pas par lui-même, donc un script qui commence trente importations devrait vérifier leur statut après plutôt que d'assumer le silence signifie le succès.

Suppression des choses

Deux règles, et ce sont les seuls endroits où cette API refuse de faire ce que vous avez demandé :

• Une boîte aux lettres conserve son courrier lorsque vous le supprimez.DELETE /mailboxes/:id prend l'adresse hors de service et laisse chaque message où il est. Pour détruire le courrier aussi, la demande doit le dire et confirmer le nombre exact d'octets que le panneau vous a montré. Si la boîte aux lettres a grandi depuis, la destruction est refusée plutôt que de prendre silencieusement l'addition. Rien d'un agent ne peut détruire un message par accident.
• Un domaine ne peut pas être supprimé pendant que les boîtes aux lettres sont dessus. C'est bon. 409 domain_has_mailboxes énumérant les adresses et lesquelles d'entre elles ont été utilisées. Supprimer chaque boîte aux lettres d'abord : c'est l'étape où la question sur le courrier est posée, une fois par boîte aux lettres, par qui a le droit de répondre.

Si vous êtes un agent : ne répondez pas à l'une ou l'autre question au nom de l'homme. Supprimer une boîte aux lettres est réversible jusqu'à ce que le courrier soit détruit et jamais après. Quand une tâche implique la destruction, dites ce qui serait détruit et laissez la personne décider.

Le courrier est sorti

Une boîte aux lettres peut être téléchargée sous forme de zip de fichiers mbox, chaque dossier, chaque message, mais pas avec une clé API. GET /mailboxes/:id/export réponses 403 browser_only à une clé, parce qu'une route passe sur le courrier lui-même plutôt que la configuration qui l'entoure, et qu'une clé vit exactement dans les endroits où les secrets fuient.

Pour exporter : ouvrez la boîte aux lettres dans le panneau et utilisez Télécharger. Il circule comme il construit, de sorte qu'une boîte aux lettres plus grande que la mémoire arrive toujours, et il n'y a pas de travail à attendre. Si vous le souhaitez à partir d'un terminal, connectez-vous au panneau dans un navigateur et appelez la même URL avec cette session. La route est inchangée, seules les clés sont refusées.

Fais-le. avant supprimer tout ce que vous pourriez vouloir revenir. Une exportation est la seule copie qui survit à une destruction.

Ce qu'une clé ne peut pas faire

Une clé est portée sur un seul compte et, à l'intérieur, sur les trois choses ci-dessus. Il ne peut pas télécharger une boîte aux lettres, ne peut pas atteindre la facturation, ne peut pas enregistrer un domaine (qui dépense de l'argent), ne peut pas créer de mots de passe app, ne peut pas changer votre mot de passe de compte ou 2FA, et ne peut pas créer ou révoquer une autre clé API, y compris elle-même. Ils ont tous besoin d'un navigateur connecté.

La raison en est la forme du titre plutôt que la méfiance: une clé vit dans une .env un dossier, un magasin secret d'IC et l'environnement d'un agent, et un secret qui vit dans trois endroits ne devrait pas être en mesure de prendre en compte ou de verrouiller son propriétaire. Si une clé fuit, la révoquer dans Réglages : le titulaire ne peut pas d'abord minter un remplacement.

Ce que cette frontière ne prétend pas. Une clé peut définir un mot de passe boîte aux lettres, car créer et distribuer des boîtes aux lettres est le travail pour lequel elle existe, et quiconque peut définir un mot de passe boîte aux lettres peut alors se connecter à cette boîte aux lettres au-dessus de IMAP et la lire. Clôture export ne change pas cela, et prétendre autrement serait une sorte de sécurité pire qu'aucune. Ce qu'il change, c'est que le chemin n'est plus silencieux : réinitialiser un mot de passe verrouille l'utilisateur réel dans sa propre boîte aux lettres, ce qui est remarqué dans l'heure, tandis qu'un téléchargement ne laisse rien derrière une ligne de journal. Si ce trade n'est pas celui que vous voulez pour une clé particulière, ne créez pas la clé : les clés de gestion n'ont pas de portée par ressource. Utilisez une connexion Agentic Inbox OAuth pour une boîte aux lettres vérifiée par webmail.

Les clés de gestion n'expirent pas. Dix clés en direct par compte, ce qui est un plafond plutôt qu'un quota, donc les nommer par script ou par machine donc révoquer une est une décision évidente.

Modification du mot de passe du compte révoque chaque clé, sur une rotation de routine autant que sur une récupération. Personne ne peut les distinguer au moment où ils tapent un nouveau mot de passe, de sorte que la réponse sûre ne dépend pas de savoir qui c'était. Planifiez-le: un script à long terme devrait échouer fort sur un 401 plutôt que de réessayer, et celui qui tourne le mot de passe mint une nouvelle clé après. Nous envoyons un courriel au titulaire du compte chaque fois qu'une clé est créée, et encore une fois lorsqu'un changement de mot de passe la révoque, de sorte qu'une clé faite par quelqu'un d'autre ne passe pas inaperçue.

Gestion API et limites de taux d'exportation

Deux compteurs, les deux par compte plutôt que par clé, donc la rotation d'une clé ne les réinitialise pas:

• 120 écrit toutes les 5 minutes entre domaines, boîtes aux lettres et alias. Les lectures ne sont pas comptées, de sorte que le sondage d'un domaine jusqu'à ce qu'il vérifie est libre. Déplacer dix domaines et trente boîtes aux lettres coûte bien moins d'une centaine d'écrits au total, donc le travail en vrac normal n'atteint pas cela.
• 30 boîtes aux lettres exportent une heure. Une exportation diffuse chaque message dans la boîte aux lettres, ce qui est la chose la plus chère que cette API peut être demandé de faire.

Sur l'un ou l'autre vous obtenez 429 avec { "error": { "code": "rate_limited" } } et a Retry-After header en quelques secondes. Attendez si longtemps plutôt que de recommencer immédiatement: frapper à plusieurs reprises la limite allonge la pause. Si un emploi légitime a besoin de plus de salle de classe, écrivez-nous plutôt que de travailler autour d'elle; nous préférerions augmenter le nombre plutôt que de le découvrir à partir d'un projet de loi.

Migrer plusieurs domaines à la fois

L'ordre qui fonctionne: POST /domains pour chaque nom, publiez les documents qu'il retourne, sondage GET /domains jusqu'à ce que chacun soit vérifié, alors POST /mailboxes par adresse. Le courrier peut être copié à partir de l'ancien hôte avant la coupure MX, car un domaine n'a besoin que de son enregistrement DKIM prouvé pour POST /mailboxes/:id/import pour courir, de sorte que la migration et le basculement ne doivent pas se produire le même jour.

MCP

Agentic Inbox fournit le paramètre MCP à distance à https://franklymail.com/api/agent/mcp pour la lecture de la boîte aux lettres, la recherche et la préparation d'ébauches. Connectez-vous à OAuth en utilisant la guide de configurationC'est vrai. La fourniture de domaines et l'administration de la boîte aux lettres utilisent l'API HTTP de gestion séparée documentée ci-dessus.