API belgeleri

Bir asistana posta kutusu bağlamak için Agentic Inbox kullanın veya kuruluş alanlarınızı, posta kutularını ve aliaslarınızı yönetmek için yönetim API'si kullanın. Bunlar ayrı kimlik ve izinler kullanır. Aşağıda ihtiyacınız olan entegrasyonu seçin.

Agentic Inbox

PKCE ile OAuth'e bağlanın https://franklymail.com/api/agent/mcp. The The The The The The The The bağlantı rehberi ChatGPT ve Claude kurulumunu kapsar. Webmail'e oturum açın. OAuth hibesi, doğrulanmış posta kutusuna bağlıdır. Grants use mailbox.read, message.read, message.search Ve ve draft.write. Otomatik gönderme izni yoktur.

Taslaklar bir inceleme bağlantısı döndürür. Sadece bu posta kutusu için doğrulanmış bir oturum tam mevcut sürümü onaylayabilir. Bir panel hesabı oturumu onaylanamaz veya onaylayamaz. Tool arguments or a chat message can authorize send.

klasörün özel aramaları için, geç folder As as as as as as as as as as as as as as as as as as as as as as as as as as as as inbox, sent, drafts, archive, trash veya veya junk (spam Bir aliasdır). Use Use Use Use Use list_folders Ve ve folderId Özel klasörler için. Bir seçici seçin; eksik bir klasör tüm postayı aramak yerine bir hata döndürür. Her ikisi de her klasörü arar.

prepare_forward Gerekli Gerekli Gerekli Gerekli Gerekli Gerekli mailboxId, messageId, requestKey Ve ve to; cc And introductory text Seçmelidir. Her ikisini de gerektirir message.read Ve ve draft.write. Orijinal başlıklar ve okunabilir metin otomatik olarak dahil edilir. Atalar webmail veya kullanıcının sadece metin açık seçimi gerektirir omitAttachments: true. Tamamlanmış veya uzun sayıda orijinal reddedilir. İleri taslaklar aynı incelemeyi ve onay akışını yanıtlar olarak kullanır.

İnsan incelemesi sayfası düzenleme alıcıları, konu ve mesajı destekler. Mailbox Boost ayrıca isteğe bağlı olarak ekliyor Track açılır Ve ve AI ile yaz. Takip seçilene kadar kapalıdır ve kurtarılır. Birkaç alıcıya gönderilen paylaşılan bir mesaj, hangi alıcının açtığını tanımlayamaz. Gizlilik referansları açık sinyalleri etkileyebilir; webmail'deki bakış aktivite.

AI yazarı posta kutusu onayı gerektirir ve webmail yazma ücretini paylaşır. OpenAI aracılığıyla bir öneri hazırlamak için kaydedilen taslak, konu, alıcılar ve talimatlar kullanır. Bir öneri uygulamak, kurtarma ve taze bir insan onayı tarafından takip edilen bir düzenlemedir. Ne özellik bir MCP aracı veya gönderme izni ekler; ajanlar ayarlanamaz trackOpens veya tarayıcı yazarı çağırın.

OAuth S256 PKCE ile yetki kodu kullanır ve resource=https://franklymail.com/api/agent/mcp. Hesaplamayı keşfedin Korumalı kaynak metadata Ve ve yetkilendirme sunucusu metadata. Dinamik müşteri kaydı dasteklenmektedir. Son bir saat içinde jetonlara erişim; yenilenen jetonlar döner. Yeni bir token tekrarlamak bağlantıyı geri döndürür. 90 güne kadar Grants.

MCP, JSON yanıtlarıyla devletsiz akışlanabilir HTTP kullanır. Call Call Call Call tools/list şemalar için. Başarılı çağrılar da dahil olmak üzere result.structuredContent; araç başarısızlıkları HTTP 200'e geri dönebilir result.isError=true ve içeren bir JSON metin bloğu error. Hem HTTP yanıt hem de araç sonucu kontrol edin. Kimlik başarısızlıkları HTTP 401'i kullanır.

Eşdeğer HTTP rotaları: GET /api/v1/mailboxes/:id/messages, GET /api/v1/mailboxes/:id/messages/:messageId, POST /api/v1/drafts, GET /api/v1/drafts/:id Ve ve PUT /api/v1/drafts/:id. Arama Kabulü folder veya veya folderId, text, from, subject, unread, limit (1 ila 25) ve position. Taslak yaratımı gerektirir mailboxId, requestKey, to, subject, text; cc Ve ve replyToMessageId Seçmelidir. Revision şu anki mevcut durumu gerektirir version ve tam yedek alıcılar, konu ve metin.

Folder listesi ve MCP araçlarını kullanmayı dört gözle bekliyor list_folders Ve ve prepare_forward; ayrı HTTP rotaları yok. Taslaklar çoğunda destek 10 Ve Cc alıcıları bir araya, bir araya, 256-character konu ve 20,000-character mesajı ve sonra sona er 24 saatler. Onaylanana kadar Agentic Inbox'de kalıyorlar; gönderilen mesajlar webmail'de görünüyor.

Agentic Inbox, posta kutusu başına 25 istek/gün ve 5/ dakika sağlar; Boost bunu 2,500 / gün ve 60 / dakikaya yükseltmektedir. Aynı posta kutusunun bağlantılarını paylaşıyor. Şifre değişiklikleri posta kutusu seanslarını ve bağlantıları geri döndürür. Mevcut hesap yetkili Inbox hibeleri webmail aracılığıyla yeniden bağlantı kurmak zorundadır. Günlük ödenekler gece yarısı UTC'de sıfırlanır. Kılavuz incelemesi ve onayı bu ücreti kullanmaz. Limit bir hatada, saygı Retry-After Ve ve error.resetsAt; standart plan egzozunda tedarik edilen Boost bağlantısını göster.

Kimler için posta kutusu oluşturabilirsiniz?

Bir hesap bir organizasyondur. Mailboxlar sizinki insanlar içindir: personel, müteahhitler, kendi projeleriniz, aliaslarınız ve paylaşılan adresler. Onlardır. Yüklediğiniz veya hizmet ettiğiniz müşteriler için değil. FranklyMail posta kutusu ya da ödediğiniz bir hizmet olarak başka birinin adına bir hesap çalıştırın, ödediğiniz bir ihlaldir. terimleri terimleri. Oradaki en çok satan maddelerine bakın. Sahip olduğunuz birkaç domaini çalıştırın ve her zaman olmuştur; on beş markalı bir holding şirketi bir organizasyondur. On beş müşteri ile bir ajans değil.

Bu ayrımı uygulamak için posta kutusu alan kotası yoktur. Bir hesap birkaç organizasyon olarak okuyan bir şekil büyürse, yazıyoruz ve soruyoruz. Hiçbir şey bir soru üzerinde askıya alınmaz.

Legacy resource API: metadata sadece

Var olan kaynak kimlikleri orijinal izinlerini tutar. posta içeriği erişimini sağlamak için, yeni bir bağlantı oluşturmak Yardımcı bağlantı rehberi. Anahtarlar sadece sadece verilen anahtarlar domain.read Ve ve mailbox.read metadata'yı sadece okuyun. Mesajları okuyamıyorlar, posta gönderebilirler veya kaynakları değiştirebilirler. Yeni olarak, posta kutuları ve domainler asla otomatik olarak erişimi kazanmıyor.

Anahtarı gönder Authorization: Bearer fma_.... Aşağıdaki yollar, aşağıdaki yollara göre bağlıdır https://franklymail.com/api.

Listeler kabul ediyor limit 1 ila 100 (default 50) ve bir UUID cursor Önceki yanıttan. Onlar geri döndüler { data: [...], nextCursor, requestId }Detaylar geri dönüş { data: {...}, requestId }. Byte count are decimal strings. DNS sonuçları depolanır gözlemler.

Standart sınırlı erişim, 25 istek / gün ve 5/ dakika, hesabın anahtarları arasında paylaşılan. Mailbox Boost Bunu abone e-posta kutusu başına 2.500 / gün ve 60/ dakika yükseltin. Günler gece yarısı UTC'de sıfırlanıyor. Anahtar tavanlar 60 / dakikaya varsayılan olarak 1 ila 600 arasında ayarlanabilir, 600 / dakika ayrı paylaşılan bir hesap güvenlik tavanı ile.

Her biri Boost postabox'ı kendi izninden bir istek kullanır. Sayfadaki herhangi bir standart kaynak bir standart istek paylaşıyor. Tüm gerekli ödenekler mevcut olmalıdır; reddedilen bir sayfa bunlardan hiçbirini geçirir. Boş bir sayfa standart ücreti kullanır. Domain ve DNS, bu alanda UUID tarafından ilk Boost posta kutusunun ödenmesini kullanabilir, ancak anahtar açıkça verilen zaman mailbox.read Bunun için de. Bu, diğer posta kutularına erişimi arttırmaz.

Onda 429şereflendirmek, Retry-After Ve ve error.resetsAt. Günlük egzoz kullanımı kullanır daily_quota_exceeded3. dakika limitleri kullanımı rate_limited. Standart plan limitleri içerir error.metadata.upgrade Boost bağlantı ve daha yüksek ödeneklerle. Bu bağlantıyı posta kutusunu yönetmek için kişiye gösterin. Bir ajan bir yükseltme satın alamaz. Boost egzozion ve anahtar / hesap güvenlik tavanları yükseltme teklifine sahip değildir. X-Agent-Plan Standart, güçlendirme veya karışık erişim tanımlayın; X-Agent-Daily-Limit, X-Agent-Daily-Remaining Ve ve X-Agent-Daily-Reset Gerekli günlük ödenekleri soldaki en az taleplerle tarif edin. Anahtar tavanlar hala inkarları saymaktadır. Eksik kapsamı geri döndürür 403hibenin dışındaki bir kaynak geri döndürür; 404; süresiz veya iptal edilen anahtar geri dönüşleri 401. Sınırlı kimlikler üzerinde çalışır /api/v1 Ve ve /api/agent/mcp Onların orijinal kapsamı içinde. Bu rotalar ne tarayıcı kurabiyelerini ne de yönetim anahtarlarını kabul eder.

Yönetim API doğrulama

Aşağıdaki “Yeni yönetim anahtarı” seçin Ayarlar → API anahtarları. Bir kez gösterilir, yaratımda; sadece bir tane saklarız ve tekrar gösteremeyiz. Her istekte bir ayıcı olarak gönderin:

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

İstekler JSON ve JSON'da. Bir hatadır { "error": { "code", "message", "field? } } eşleşen HTTP statüsü ile: 401 Eksik olan bir anahtar için, iptal edilmiş veya bilinmeyen, 403 Bir yol için bir anahtar ulaşmayabilir, 422 Kötü bir alan için.

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

Bir yönetim anahtarı ne çağırabilir

Yollar, Patriğe bağlıdır https://franklymail.com/api. Bu liste yorucudur: cevaplar üzerinde olmayan bir rota 401 Bir anahtara, imzalanmış bir tarayıcı için ne yaparsa.

Domainler

Mailboxes

Takma adresler ve yönlendirme

Adım adım alan adı ekleme

POST /domains Bunu yaratır ve yayımlamak için kayıtları geri döndürür. Başka hiçbir şey doğrulamaya başlamak için çağrılmamalı, çünkü kontroller kendi programlarında çalışır.

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

Her Şeyi Keşfedin records[] DNS sağlayıcınıza giriş yapın, sonra izle GET /domainsHer alan için aynı ücret yükü, bu yüzden bir anket bütün bir toplu kapsar. Üç alan üç farklı soruya cevap verir ve onları şişirmek her zamanki hatadır:

• records[].status: live DNS ne beklediğimize cevap verir, missing O zamana kadar.
• ownership: proven DKIM rekor bir kez yukarı. Bu, kapıların posta kutularının ve ithalatın tekidirMX'den önce bu kadar posta kopyalanabilir.
• status: Tüm alan, active MX dahil her şey yaşıyor ve posta aslında gelecek.

recheckIn Bir sonraki otomatik kontrole kadar saniyeler; kabaca o kadar uzun ki kirleticiler arasında uyuyun. POST /domains/:id/recheck Hemen bir kuvvet ve alan başına sınırlı, bu yüzden yayın kayıtlarından sonra kullanın, bir kirletici döngü olarak değil. Yol, hesap ve isim için idempotent: Zaten mevcut olanı tekrar tekrar tekrar tekrar tekrar geri döndürürseniz, bir tekrar veya bir hatadan ziyade.

Bir posta kutusu taşıyın, adım adım adım adım

Bu, en çok senaryolar için yazılır ve keşfedilmeye değer hareketli parçalarla birlikte.

1. Başlayın. POST /mailboxes/:id/import Eski sunucunun bağlantı ayrıntılarıyla. Şifre bir sütuna dokunmadan önce şifrelenir, hiçbir zaman herhangi bir rotaya geri dönmez ve işi durdurur.

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

Cevaplar 202Ama değil, 200: Bir kopya saatlerce alır, bu yüzden iş kuyruklanır ve istek hemen döndürür. posta kutusu için bir seferde bir ithalat. Bir saniyeye başlayın, bir cevap koşarken 409 import_in_progress Çalışan işinin boşluğu ile, aynı kaynağın iki eş zamanlı kopyaları her mesajı tekrarladı ve bir retry bunu geri almamaktadır. Otuz posta kutusu bir kez ithal edebilir; sınır posta kutusu başına değil.

2. Takip et. GET /mailboxes/:id/import Bu posta kutusu için en son işi döndürür veya {"import": null} Hiç bir zaman olmadıysa.

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 Bir tanesidir. pending, running, done, failed veya veya cancelledVe son üç terminaldir. Birkaç saniye boyunca Anket, milisans değil; okur oranı sınırlı değil, ancak karşıtlar yalnızca diğer sunucu cevapları kadar hızlı hareket ederler. folders_done / folders_total Dürüst ilerleme figürüdür: messages_done Bir klasörün açılmasına kadar hiçbir denominatörü yok, bu yüzden ondan yapılmış bir yüzdesi geriye atacaktır. Başarısızlık üzerine, last_error Bir kişiye gösterilen bir cümle taşır.

3. Bunu durdurun, gerekiyorsa.POST /mailboxes/:id/import/cancel Çalışan işi sona erdirmek. Bu herhangi bir tarafından eski sağlayıcıda hiçbir şey değişmez. Bir ithalat sadece ondan okur. Mesajlar zaten talep açıkça başka türlü sormadığı sürece kopyalanır.

Bunu senaryolamadan önce bilmeniz gereken iki şey. Bir posta kutusu, DKIM kaydının kanıtlanmasına ihtiyaç duyar, MX kesintiye uğramaz, bu yüzden kopya postayı geçmeden günler sürebilir. Ve bizimkilerin bir dağıtma paneli yeniden başlatır: Koşuya çalışan bir iş durduruldu ve kendi başına yeniden başlamadı, bu yüzden otuz ithalata başlayan bir senaryo başarı anlamına gelir.

Şeyleri Deletmek

İki kural ve bu API'nin sorduğu tek yerler şunlardır:

• Bir posta kutusu onu sildiğinizde postasını tutar.DELETE /mailboxes/:id Hizmetten gelen adresi alır ve nerede olduğu her mesajı bırakır. Postayı da yok etmek için, istek bunu söylemek ve panelin size gösterdiği kesin saymak zorundadır. Posta kutusu o zamandan beri büyüdüyse, yok, sessizce ekstra almak yerine reddedilir. Bir ajan kazayla yaptığı hiçbir şey bir mesajı yok edebilir.
• Bir alan posta kutularının üzerindeyken silinemez. Size sunulanlar 409 domain_has_mailboxes adresleri listelemek ve hangileri kullanıldı. Her posta kutusu ilk olarak: posta ile ilgili soru sorulduğunda, posta kutusu başına bir kez, kime cevap verme hakkı verilir.

Eğer bir ajansanız: İnsan adına ya da soru cevap vermeyin. Bir posta kutusu silme, posta yok olana kadar geri dönüşümlüdür ve hiçbir zaman geç değildir. Bir görev yıkımı ima ettiğinde, neyin yok olacağını ve kişinin karar vermesine izin verin.

Posta almak için

Bir posta kutusu, mbox dosyalarının bir posta kutusu olarak indirilebilir, her klasör, her mesaj, ama API anahtarı ile değil. GET /mailboxes/:id/export Cevap cevaplar cevaplar 403 browser_only Bir anahtara, çünkü bu bir rota, etrafındaki konfigürasyondan ziyade postayı ele geçiriyor ve tam olarak yerdeki sırları sızdırıyor.

İhracat için: Paneldeki posta kutusunu açın ve Download kullanın. Oluşturduğu gibi akışlar, bu yüzden bir posta kutusu hafızadan daha büyük geliyor ve beklemek için bir iş yok. Bir terminalden istiyorsanız, bir tarayıcıda panele oturum açın ve bu oturumla aynı URL'yi arayın. Yol değişmeden kalır, sadece anahtarlar reddedilir.

Bunu yap Daha önce daha önce daha önce daha önce Geri isteyebileceğiniz her şeyi ortadan kaldır. Bir ihracat, bir yokluğa hayatta kalan tek kopyadır.

Bir anahtar ne yapamaz

Bir anahtar bir hesapla kaplıdır ve içinde, yukarıdaki üç şeye. Bir posta kutusu indirmez, faturaya ulaşamaz, bir alan kayıt edemez (bu para harcar), uygulama şifrelerini oluşturamaz, hesap şifrenizi veya 2FA'nızı değiştiremez ve kendisi de dahil olmak üzere başka bir API anahtarı da oluşturamaz. Bunların hepsinin imzalanmış bir tarayıcıya ihtiyacı var.

Sebep, güvensizlikten ziyade haçlının şeklidir: Bir anahtar yaşam .env Dosya, bir CI gizli mağazası ve bir ajanın ortamı ve üç yerde yaşayan bir sır, sahibini devralmak veya kilitlemek zorunda kalmamalıdır. Anahtar sızıntıları varsa, onu Ayarlara geri döndürür: Sahibi ilk önce bir yedekten vazgeçemez.

Hangi sınır iddia etmez. Bir anahtar bir posta kutusu şifresi ayarlayabilir, çünkü oluşturmak ve posta kutusu oluşturmak için mevcut olan işdir ve bir posta kutusu şifresi oluşturabilen herkes daha sonra IMAP üzerinden bu posta kutusuna işaret edebilir ve okuyabilirsiniz. Kapanış kapanış export Bunu değiştirmez ve aksi takdirde hiçbir şeyden daha kötü bir güvenlik olurdu. Değişim nedir, yol artık sessiz değildir: bir şifre kilitleri, saat içinde fark edilen gerçek kullanıcıyı, bir indirme arkadan başka bir şey bırakmazken, bir indirme bir log hattının arkasında hiçbir şey bırakmaz. Bu ticaret belirli bir anahtar için istediğiniz kişi değilse, anahtar yaratmaz: yönetim anahtarlarının per-resource kapsamı yoktur. Webmail yoluyla doğrulanmış bir posta kutusu için Agentic Inbox OAuth bağlantı kullanın.

Yönetim anahtarları sona ermez. Hesap başına 10 canlı anahtar, bu bir kota yerine bir tavandır, bu yüzden onları senaryoya veya makineye çağırın, böylece iptal edilen bir karardır.

Hesap şifresini değiştirmek tüm anahtarları geçersiz kılarBir kurtarmada olduğu kadar rutin bir rotasyonda. Hiç kimse bu iki şeyi yeni bir şifre türünde anlatamaz, bu yüzden güvenli cevap, hangi olduğunu bilmeye bağlı değildir. Bunun için plan: uzun süren bir senaryo yüksek sesle başarısız olmalıdır 401 Yeniden denemeden ziyade, ve kim şifre mizanlarını daha sonra yeni bir anahtar döndürür. Hesap sahibine anahtar ne zaman yaratıldık ve bir şifre değişikliği onları geri döndürdüğünde, başka biri tarafından yapılan bir anahtar da istenmeyen gitmez.

Yönetim API ve ihracat oranı limitleri

İki karşı, her iki hesap da anahtardan ziyade, bu yüzden bir anahtar onları sıfırlamaz:

• Her 5 dakikada 120 yazma işlemi Sahalar, posta kutuları ve aliazlar. Okumalar sayılmıyor, bu nedenle, doğrulayana kadar bir alan anketi ücretsiz. On domain ve otuz posta kutusu toplam yüz yazar altında iyi çalışır, bu yüzden normal toplu iş buna ulaşmıyor.
• Saatte 30 posta kutusu dışa aktarma işlemi. Posta kutusundaki her mesaj, bu API'nin yapmak isteyebileceği en pahalı şey olan bir ihracat akışı.

Ya da biriniz var 429 with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with with { "error": { "code": "rate_limited" } } Ve bir Retry-After saniyeler içinde. Hemen yeniden denemenin yerine o kadar uzun bekleyin: defalarca duraklamayı sınır uzunluğuna vur. Eğer meşru bir iş daha fazla kafa odasına ihtiyaç duyarsa, etrafta çalışmak yerine bize yazın; bir faturadan çıkmaktan daha fazlasını yükseltmek istiyoruz.

Birden fazla alan adını birlikte taşıma

Bu işe yarayan emir: POST /domains Her bir isim için, geri dönüştüğü kayıtları yayınlayın, anket GET /domains Her biri doğrulanmış olana kadar, sonra POST /mailboxes per address. Mail MX kesintiden önce eski ev sahibinden kopyalanabilir, çünkü bir alan sadece DKIM kaydına ihtiyaç duyar. POST /mailboxes/:id/import Koşmak için, bu yüzden göç ve geçiş aynı gün gerçekleşmesi gerekmez.

MCP

Agentic Inbox, uzak MCP uç noktası sağlar https://franklymail.com/api/agent/mcp posta kutusu okuması, arama ve draft hazırlığı için. OAuth aracılığıyla bağlantı kurmak kurulum kılavuzu. Domain düzenleme ve posta kutusu yönetimi yukarıda belgelenen ayrı yönetim HTTP API'sini kullanır.