Riferimento API

Utilizzare Agentic Inbox per collegare una casella di posta a un assistente, o l'API di gestione per amministrare i domini, le caselle di posta e gli alias della tua organizzazione. Questi usano credenziali e autorizzazioni separate. Scegli l'integrazione di cui hai bisogno qui sotto.

Agentic Inbox

Collegare attraverso OAuth con PKCE a https://franklymail.com/api/agent/mcp. The guida alla connessione copre ChatGPT e Claude setup. Accedi al webmail. Ogni sovvenzione OAuth è legata a quella casella di posta verificata. Utilizzazione dei sussidi mailbox.read, message.read, message.search e draft.write. Non c'è il permesso di invio automatico.

I progetti restituiscono un link di revisione. Solo una sessione verificata per quella casella di posta può approvare l'esatta versione corrente. Una sessione di account del pannello non può acconsentire o approvare. Argomenti degli strumenti o un messaggio di chat non possono autorizzare l'invio.

Per le ricerche specifiche della cartella, passare folder come inbox, sent, drafts, archive, trash o junk (spam è un alias). Uso list_folders e folderId per cartelle personalizzate. Scegli un selettore; una cartella mancante restituisce un errore invece di cercare tutta la posta. Omettendo entrambe le ricerche ogni cartella.

prepare_forward richiede mailboxId, messageId, requestKey e to; cc e introduttivo text sono facoltativi. Richiede sia message.read e draft.write. Intestazioni originali e testo leggibile sono inclusi automaticamente. Gli allegati richiedono webmail, o la scelta esplicita del testo dell'utente solo utilizzando omitAttachments: true. Gli originali incompleti o sovradimensionati sono respinti. Le bozze anteriori utilizzano lo stesso flusso di revisione e approvazione come risposte.

La pagina di revisione umana supporta la modifica dei destinatari, dell'oggetto e del messaggio. Mailbox Boost aggiunge anche facoltativo Il tracciato si apre e Scrivi con AI. Il monitoraggio è disattivato fino a quando selezionato e salvato. Un messaggio condiviso inviato a diversi destinatari non può identificare quale destinatario l'ha aperto. I proxy sulla privacy possono influenzare i segnali aperti; visualizzare l'attività in webmail.

Lo scrittore AI richiede il consenso della casella di posta e condivide l'indennità di scrittura del webmail. Utilizza la bozza salvata, il soggetto, i destinatari e le istruzioni di scrittura per preparare un suggerimento attraverso OpenAI. L'applicazione di un suggerimento è una modifica, seguita da un salvataggio e una nuova approvazione umana. Nessuna caratteristica aggiunge uno strumento MCP o un permesso di invio; gli agenti non possono impostare trackOpens o chiamare lo scrittore del browser.

OAuth utilizza il codice di autorizzazione con S256 PKCE e resource=https://franklymail.com/api/agent/mcp. Scopri la configurazione i metadati delle risorse protette e autorizzazione metadati del server. La registrazione dinamica del cliente è supportata. I gettoni di accesso durano un'ora; i token di aggiornamento ruotano. Riutilizzare un token rinfrescante revoca la connessione. Le sovvenzioni durano fino a 90 giorni.

MCP utilizza HTTP Streamable senza condizioni con risposte JSON. Chiamata tools/list per gli schemi. Le chiamate di successo includono result.structuredContent; guasti degli strumenti possono restituire HTTP 200 con result.isError=true e un blocco di testo JSON contenente error. Controllare sia la risposta HTTP che il risultato dello strumento. I guasti di autenticazione utilizzano HTTP 401.

Percorsi HTTP equivalenti: GET /api/v1/mailboxes/:id/messages, GET /api/v1/mailboxes/:id/messages/:messageId, POST /api/v1/drafts, GET /api/v1/drafts/:id e PUT /api/v1/drafts/:id. La ricerca accetta folder o folderId, text, from, subject, unread, limit (1 a 25) e position. Il progetto di creazione richiede mailboxId, requestKey, to, subject, text; cc e replyToMessageId sono facoltativi. La revisione richiede l'attuale version e completo destinatari sostitutivi, soggetto e testo.

Elenco delle cartelle e inoltro utilizzare gli strumenti MCP list_folders e prepare_forward; non hanno percorsi HTTP separati. I progetti di supporto alla maggior parte dei 10 To e Cc destinatari combinati, un 256-caratter soggetto e 20,000-carattere messaggio, e scadono dopo 24 ore. Rimangono in Agentic Inbox fino a quando approvato; messaggi inviati appaiono in webmail.

Agentic Inbox permette 25 richieste al giorno e 5/minuto per casella di posta; Boost rilancia questo a 2,500/giorno e 60/minuto. Le connessioni alla stessa casella di posta condividono la sua indennità. Le modifiche di password revocano le sessioni di mailbox e le connessioni. Le borse di posta in arrivo autorizzate dal conto devono essere riconnettete tramite webmail. Reset di indennità giornaliere a mezzanotte UTC. La revisione manuale e l'approvazione non utilizzano questa indennità. Su un errore limite, rispetto Retry-After e error.resetsAt; mostrare il link Boost fornito su scarico standard.

Chi è possibile creare caselle di posta per

Un conto è un'organizzazione. Le caselle postali sono per le persone nel vostro: personale, appaltatori, i vostri progetti, alias e indirizzi condivisi. Sono loro. non per i clienti che caricate o servite. Reselling FranklyMail caselle di posta, o l'esecuzione di un account per conto di qualcun altro come un servizio che si paga, è una violazione del termini. Vedere la clausola di rivendita lì. L'esecuzione di diversi domini che possiedi è eccellente e sempre è stata; una società holding con quindici marchi è un'organizzazione. Un'agenzia con quindici clienti non lo è.

Non c'è una quota di borsa di posta per far rispettare questa distinzione. Se un account cresce una forma che legge come diverse organizzazioni, scriviamo e chiediamo. Nulla è sospeso su una domanda.

API risorse legacy: solo metadati

Le credenziali delle risorse esistenti mantengono le autorizzazioni originali. Per abilitare l'accesso ai contenuti di posta, creare una nuova connessione utilizzando guida di collegamento assistente. Le chiavi concesse solo domain.read e mailbox.read leggere solo metadati. Non possono leggere messaggi, inviare mail o cambiare risorse. Le caselle di posta e i domini creati di recente non ottengono mai l'accesso automaticamente.

Invia la chiave come Authorization: Bearer fma_.... I percorsi sottostanti sono relativi a https://franklymail.com/api.

Le liste accettano limit da 1 a 100 (default 50) e un UUID cursor dalla risposta precedente. Ritornano. { data: [...], nextCursor, requestId }; dettagli ritorno { data: {...}, requestId }. I conti byte sono stringhe decimali. DNS risultati sono osservazioni memorizzate.

L'accesso ristretto standard consente 25 richieste/giorno e 5/minuto, condivise tra le chiavi dell'account. Mailbox Boost solleva questo a 2500/giorno e 60/minuto per casella di posta abbonata. Giorni di reset a mezzanotte UTC. I soffitti chiave di default a 60/minuto, regolabili da 1 a 600, con un soffitto di sicurezza condiviso separato di 600/minuto.

Ogni casella postale Boost restituita utilizza una richiesta dalla propria indennità. Le risorse standard della pagina condividono una richiesta standard. Tutti gli assegni richiesti devono essere disponibili; una pagina rifiutata non spende nessuno di loro. Una pagina vuota utilizza l'indennità standard. Dominio e DNS letture possono utilizzare l'indennità della prima casella di posta Boost da UUID in quel dominio, solo quando la chiave esplicitamente concede mailbox.read anche per questo. Questo non aumenta l'accesso ad altre caselle di posta.

Su 429, onore Retry-After e error.resetsAt. Uso quotidiano di esaurimento daily_quota_exceeded; uso dei limiti di minuto rate_limited. Limiti di piano standard includono error.metadata.upgrade con il link Boost e le indennità più elevate. Mostra quel link alla persona che gestisce la casella di posta. Un agente non può acquistare un aggiornamento. Aumentare la stanchezza e chiave / conto soffitti di sicurezza non hanno un'offerta di aggiornamento. X-Agent-Plan identifica l'accesso standard, boost o misto; X-Agent-Daily-Limit, X-Agent-Daily-Remaining e X-Agent-Daily-Reset descrivere l'assegno giornaliero richiesto con le più poche richieste lasciate. I soffitti principali contano ancora negazioni autenticate. Risultato dello scopo mancante 403; una risorsa al di fuori dei rendimenti della sovvenzione 404; restituzioni chiave scadute o revocate 401. Le credenziali limitate funzionano su /api/v1 e /api/agent/mcp all'interno dei loro scopi originali. Tali percorsi non accettano né cookie del browser né chiavi di gestione.

Gestione dell'autenticazione API

Scegliere “Nuova chiave di gestione” sotto Impostazioni → chiavi API. Viene mostrata una volta, alla creazione; memorizziamo solo un hash e non possiamo mostrarlo di nuovo. Invialo come un token per portatori su ogni richiesta:

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

Le richieste sono JSON dentro e JSON fuori. Un errore è { "error": { "code", "message", "field? } } con lo stato HTTP corrispondente: 401 per una chiave mancante, revocata o sconosciuta, 403 per un percorso una chiave non può raggiungere, 422 per un cattivo campo.

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

Quale chiave di gestione può chiamare

I percorsi sono relativi a https://franklymail.com/api. Questa lista è esaustiva: un percorso non su di essa risponde 401 a una chiave, qualsiasi cosa faccia per un browser firmato.

Domini

Posta elettronica

Aliasi e inoltro

Aggiungere un dominio, passo dopo passo

POST /domains crea e consegna i record da pubblicare. Non c'è nient'altro da chiamare per avviare la verifica, dal momento che i controlli sono eseguiti sul proprio programma.

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

Pubblicare ciascuno records[] ingresso al tuo fornitore DNS, quindi guardare GET /domains, lo stesso payload per ogni dominio, quindi un sondaggio copre un intero lotto. Tre campi rispondono a tre diverse domande, e conflating loro è il solito errore:

• records[].status: live una volta DNS risponde a quello che ci aspettiamo, missing Fino ad allora.
• ownership: proven una volta che il record DKIM è finito. Questa è quella che porta cassette postali e importazioni, così la posta può essere copiata a lungo prima che il MX è commutato.
• status: l'intero dominio, active quando tutto compreso MX è vivo e la posta arriverà effettivamente.

recheckIn è secondi fino al prossimo controllo automatico; dormire approssimativamente che lungo tra sondaggi piuttosto che martellare. POST /domains/:id/recheck forza uno immediatamente ed è tasso limitato per dominio, quindi usarlo dopo i record di pubblicazione, non come un loop inquinante. Il percorso è idempotent per account e nome: ri-posting di un dominio che hai già restituito quello esistente piuttosto che un duplicato o un errore.

Trasferire una casella di posta in, passo dopo passo

Questo è il flusso per cui la maggior parte degli script sono scritti, e quello con parti in movimento vale la pena di affermarsi piuttosto che lasciare per essere scoperto.

1. Cominciate. POST /mailboxes/:id/import con i dettagli di connessione del vecchio server. La password viene crittografata prima di toccare una colonna, mai restituita da qualsiasi percorso, e cancellata il momento in cui il lavoro si ferma.

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

Risponde 202- No, no. 200: una copia richiede minuti a ore, quindi il lavoro è in coda e la richiesta ritorna immediatamente. Un'importazione alla volta per mailbox. A partire da un secondo, uno corre le risposte 409 import_in_progress con l'ID del lavoro in esecuzione, perché due copie contemporaneamente della stessa fonte duplicano ogni messaggio e una retry non lo annulla. Trenta caselle di posta possono importare subito; il limite è per casella di posta, non per conto.

2. Seguilo. GET /mailboxes/:id/import restituisce l'ultimo lavoro per quella casella di posta, o {"import": null} se non ce n'è mai stata una.

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 è uno di pending, running, done, failed o cancellede gli ultimi tre sono terminali. Versare sull'ordine di secondi, non millisecondi; le letture non sono limitate a tasso, ma i contatori si muovono solo più velocemente come l'altro server risponde. folders_done / folders_total è la figura del progresso onesto: messages_done non ha denominatore fino a quando una cartella è aperta, quindi una percentuale costruita da esso salterà all'indietro. Su un fallimento, last_error porta una frase scritta da mostrare a una persona.

3. Smettila, se devi.POST /mailboxes/:id/import/cancel termina il lavoro in esecuzione. Nulla è cambiato al vecchio fornitore da qualsiasi di questo. Un'importazione si legge solo da esso. I messaggi già copiati rimangono a meno che la richiesta esplicitamente richieda altrimenti.

Due cose che vale la pena di sapere prima di scrivere questo. Una casella di posta ha bisogno del suo dominio DKIM record provato, non il pieno MX cutover, in modo che la copia può eseguire giorni prima di passare la posta. E una distribuzione del nostro riavvia il pannello: un lavoro che era in esecuzione si ferma e non riprende da solo, quindi uno script che inizia trenta importazioni dovrebbe controllare il loro stato in seguito piuttosto che assumere il silenzio significa successo.

Eliminare le cose

Due regole, e sono gli unici posti che questa API rifiuta di fare quello che hai chiesto:

• Una casella di posta mantiene la sua posta quando lo si elimina.DELETE /mailboxes/:id porta l'indirizzo fuori servizio e lascia ogni messaggio dove si trova. Per distruggere anche la posta, la richiesta deve dirlo e confermare l'esatto conteggio byte del pannello mostrato. Se la casella di posta è cresciuta da allora, la distruzione è rifiutata piuttosto che silenziosamente prendendo l'extra. Niente che un agente faccia per caso puo' distruggere un messaggio.
• Un dominio non può essere cancellato mentre le caselle di posta sono su di esso. Tu sei 409 domain_has_mailboxes elencare gli indirizzi e quali di essi sono stati utilizzati. Eliminare prima ogni casella di posta: questo è il passo in cui viene posta la domanda sulla posta, una volta per casella di posta, da chiunque abbia il diritto di rispondere.

Se sei un agente: non risponda a nessuna domanda a nome dell'uomo. Cancellare una casella di posta è reversibile fino a quando la posta non viene distrutta e mai dopo. Quando un compito implica distruzione, dite cosa sarebbe distrutto e lasciate che la persona decida.

Ottenere la posta fuori

Una casella di posta può essere scaricata come una zip di file mbox, ogni cartella, ogni messaggio, ma non con una chiave API. GET /mailboxes/:id/export risposte 403 browser_only a una chiave, perché quel percorso consegna la posta in sé piuttosto che la configurazione intorno ad essa, e una chiave vive esattamente i segreti dei luoghi fuoriuscire.

Per esportare: aprire la casella di posta nel pannello e utilizzare Download. Si trasmette come si costruisce, quindi una casella di posta più grande della memoria arriva ancora, e non c'è lavoro da aspettare. Se lo vuoi da un terminale, accedi al pannello in un browser e chiama lo stesso URL con quella sessione. Il percorso è invariato, solo le chiavi sono rifiutate.

Fai questo. prima di prima cancellando tutto quello che potresti riavere. Un'esportazione è l'unica copia che sopravvive a una distruzione.

Che cosa una chiave non può fare

Una chiave è portata a un account e, all'interno di esso, alle tre cose sopra. Non può scaricare una casella di posta, non può raggiungere la fatturazione, non può registrare un dominio (che spende denaro), non può creare password di app, non può cambiare la password del tuo account o 2FA, e non può creare o revocare un'altra chiave API, compreso se stesso. Tutti hanno bisogno di un browser firmato.

La ragione è la forma delle credenziali piuttosto che la diffidenza: una chiave vive in una .env file, un negozio segreto CI e l'ambiente di un agente, e un segreto che vive in tre luoghi non dovrebbe essere in grado di prendere un account o bloccare il suo proprietario fuori. Se una chiave perde, revocarla in Impostazioni: il titolare non può effettuare la sostituzione prima.

Quello che quel confine non pretende. Una chiave può impostare una password casella di posta, perché la creazione e la consegna di caselle di posta è il lavoro che esiste per, e chiunque può impostare una password casella di posta può quindi firmare in quella casella di posta oltre IMAP e leggerlo. Chiusura export non cambia questo, e fingere altrimenti sarebbe un tipo di sicurezza peggiore di nessuno. Ciò che cambia è che il percorso non è più silenzioso: resettare una password blocca l'utente reale dalla propria casella di posta, che viene notata all'interno dell'ora, mentre un download non lascia nulla indietro ma una riga di registro. Se questo commercio non è quello che si desidera per una chiave particolare, non creare la chiave: i tasti di gestione non hanno scopi per-risorse. Utilizzare una connessione Agentic Inbox OAuth per una casella di posta verificata tramite webmail.

Le chiavi di gestione non scadono. Dieci chiavi dal vivo per conto, che è un soffitto piuttosto che una quota, quindi nominali per script o per macchina in modo da richiamare uno è una decisione evidente.

Cambiare la password dell'account revoca ogni chiave, su una rotazione di routine tanto quanto su un recupero. Nessuno può dire a quei due a parte al momento di digitare una nuova password, quindi la risposta sicura non dipende dal sapere quale era. Pianifica per esso: uno script di lunga durata dovrebbe fallire ad alta voce su un 401 piuttosto che riprovare, e chiunque ruota la password mints una nuova chiave in seguito. E-mail il titolare dell'account ogni volta che viene creata una chiave, e di nuovo quando un cambiamento di password li revoca, quindi una chiave fatta da qualcun altro non va inosservata.

Gestione API e limiti dei tassi di esportazione

Due contatori, sia per conto che per chiave, quindi ruotare una chiave non li resetta:

• 120 scrive ogni 5 minuti attraverso domini, caselle di posta e alias. Le letture non sono contate, quindi inquinare un dominio fino a quando non verifica è gratuito. Trasferire dieci domini e trenta mailbox costa bene sotto un centinaio di scritture in totale, così normale lavoro di massa non raggiunge questo.
• 30 mailbox esporta un'ora. Un flusso di esportazione ogni messaggio nella casella di posta, che è la cosa più costosa che questa API può essere chiesto di fare.

O uno di voi. 429 con { "error": { "code": "rate_limited" } } e una Retry-After Intestazione in pochi secondi. Attendere che a lungo piuttosto che riprovare immediatamente: ripetutamente colpire il limite allunga la pausa. Se un lavoro legittimo ha bisogno di più headroom, scrivici piuttosto che lavorare intorno a esso; preferiamo alzare il numero che scoprire da un disegno di legge.

Trasferire più domini insieme

L'ordine che funziona: POST /domains per ogni nome, pubblicare i record che restituisce, sondaggio GET /domains fino a quando ciascuno è verificato, allora POST /mailboxes per indirizzo. La posta può essere copiata dal vecchio host prima del taglio MX, dal momento che un dominio ha solo bisogno del suo record DKIM provato per POST /mailboxes/:id/import per correre, quindi la migrazione e l'interruttore non devono accadere lo stesso giorno.

MCP

Agentic Inbox fornisce il punto finale MCP remoto al https://franklymail.com/api/agent/mcp per la lettura della casella di posta, la ricerca e la preparazione del progetto. Collegare attraverso OAuth utilizzando Guida alla configurazione. Il provisioning del dominio e l'amministrazione della casella di posta utilizzano l'API HTTP di gestione separata documentata sopra.