Ссылка на API

Используйте Agentic Inbox для подключения почтового ящика к помощнику или API управления для администрирования доменов, почтовых ящиков и псевдонимов вашей организации. Они используют отдельные учетные данные и разрешения. Выберите интеграцию, которая вам нужна ниже.

Agentic Inbox

Соединение через OAuth с PKCE https://franklymail.com/api/agent/mcp.. The руководство по подключению Покрывает ChatGPT и Claude установки. Войдите в веб-почту. Каждый грант OAuth привязан к одному проверенному почтовому ящику. Гранты используют mailbox.read, message.read, message.search и draft.write.. Автоматического разрешения на отправку нет.

Проекты возвращают ссылку на обзор. Только сеанс, проверенный для этого почтового ящика, может утвердить точную текущую версию. Сессия панельного счета не может дать согласие или одобрить. Аргументы инструмента или сообщение чата не могут разрешить отправку.

Для поиска по конкретным папкам, пройдите folder как inbox, sent, drafts, archive, trash или junk (spam Это псевдоним. Использовать list_folders и folderId Для пользовательских папок. Выберите один селектор; отсутствующая папка возвращает ошибку вместо поиска всей почты. Отказ от обоих поисков в каждой папке.

prepare_forward требует mailboxId, messageId, requestKey и to; cc и вводный text являются необязательными. Для этого требуется оба message.read и draft.write.. Оригинальные заголовки и читаемый текст включаются автоматически. Приложения требуют веб-почты или явного выбора текста пользователем только с использованием omitAttachments: true.. Неполные или негабаритные оригиналы отклоняются. В предварительных проектах используется тот же поток обзора и утверждения, что и в ответах.

Страница обзора человека поддерживает редактирование получателей, темы и сообщения. Mailbox Boost также необязательно Трек открывается и Пишите с AI.. Отслеживание прекращается до тех пор, пока не будет выбрано и сохранено. Общее сообщение, отправленное нескольким получателям, не может определить, какой получатель открыл его. Прокси конфиденциальности могут влиять на открытые сигналы; просматривать активность в веб-почте.

Автор ИИ требует согласия почтового ящика и разделяет пособие на написание веб-почты. Он использует сохраненный проект, предмет, получателей и письменные инструкции для подготовки предложения через OpenAI. Применение предложения - это редактирование, за которым следует сохранение и свежее одобрение человека. Ни одна функция не добавляет инструмент MCP или разрешение на отправку; агенты не могут установить trackOpens Или позвоните автору браузера.

OAuth использует код авторизации с S256 PKCE и resource=https://franklymail.com/api/agent/mcp.. Найти конфигурацию в Защищенные метаданные ресурса и Авторизация сервера метаданных.. Поддерживается динамическая регистрация клиентов. Доступ к токенам длится один час; токены обновления вращаются. Повторное использование токена обновления отменяет соединение. Гранты длятся до 90 дня.

MCP использует потоковый HTTP без состояния с ответами JSON. Звони. tools/list Для схем. Успешные звонки включают в себя result.structuredContentСбои в работе инструмента могут вернуть HTTP 200 result.isError=true текстовый блок JSON, содержащий error.. Проверьте как HTTP-ответ, так и результат инструмента. Неисправности аутентификации используют HTTP 401.

Эквивалентные HTTP маршруты: GET /api/v1/mailboxes/:id/messages, GET /api/v1/mailboxes/:id/messages/:messageId, POST /api/v1/drafts, GET /api/v1/drafts/:id и PUT /api/v1/drafts/:id.. Поиск принимает folder или folderId, text, from, subject, unread, limit (1-25) и position.. Проект создания требует mailboxId, requestKey, to, subject, text; cc и replyToMessageId являются необязательными. Пересмотр требует текущего version и полные замещающие получатели, предмет и текст.

Перечень папок и пересылка используют инструменты MCP list_folders и prepare_forwardУ них нет отдельных HTTP-маршрутов. Проекты поддерживают не более 10 получателей To и Cc вместе взятых, 256-символ и 20,000-символ сообщения и истекают через 24 часа. Они остаются в Agentic Inbox до утверждения; отправленные сообщения появляются в веб-почте.

Agentic Inbox допускает 25 запросов/день и 5/минуту на почтовый ящик; Boost повышает это до 2,500/день и 60/минуту. Подключения к одному и тому же почтовому ящику делят его скидку. Изменения пароля отменяют сеансы и соединения почтового ящика. Существующие авторизованные учетные записи входящие гранты должны повторно подключаться через веб-почту. Ежедневные надбавки сбрасываются в полночь UTC. Ручная проверка и утверждение не используют эту надбавку. Ограниченная ошибка, уважение Retry-After и error.resetsAt; показать поставляемую ссылку Boost на исчерпание стандартного плана.

Для кого можно создавать почтовые ящики

Один аккаунт : это одна организация. Почтовые ящики предназначены для ваших сотрудников, подрядчиков, ваших собственных проектов, псевдонимов и общих адресов. Они являются Не для клиентов, которых вы заряжаете или обслуживаете... Перепродажа почтовых ящиков FranklyMail или управление учетной записью от имени кого-то другого в качестве услуги, за которую вы платите, является нарушением закона. термины.. См. пункт перепродажи там. Запуск нескольких доменов, которыми вы владеете, хорош и всегда был; холдинговая компания с пятнадцатью брендами - это одна организация. Агентства с пятнадцатью клиентами нет.

Нет квоты на почтовый ящик, чтобы обеспечить соблюдение этого различия. Если учетная запись приобретает форму, которая читается как несколько организаций, мы пишем и спрашиваем. Ничего не приостанавливается из-за вопроса.

Наследие ресурса API: только метаданные

Существующие учетные данные ресурса сохраняют свои первоначальные разрешения. Чтобы обеспечить доступ к почтовому контенту, создайте новое соединение с помощью Помощник по подключению Руководство.. Ключи, предоставленные только domain.read и mailbox.read Читайте только метаданные. Они не могут читать сообщения, отправлять почту или менять ресурсы. Недавно созданные почтовые ящики и домены никогда не получают автоматический доступ.

Отправьте ключ как Authorization: Bearer fma_..... Пути, расположенные ниже, относительны https://franklymail.com/api.

Списки принимаются limit от 1 до 100 (по умолчанию 50) и UUID cursor из предыдущего ответа. Они возвращаются { data: [...], nextCursor, requestId }; детали возвращаются { data: {...}, requestId }.. Число байтов : десятичные струны. Результаты DNS хранятся наблюдениями.

Стандартный ограниченный доступ позволяет выполнять 25 запрос/день и 5 запрос/минуту, совместно используемые ключами учетной записи. Mailbox Boost Повышает этот показатель до 2 500/сутки и 60/минуты на каждый почтовый ящик. Дни перезагрузки в полночь UTC. Ключевые потолки по умолчанию до 60/минута, регулируемые от 1 до 600, с отдельным потолком безопасности общего счета 600/минута.

Каждый возвращенный почтовый ящик Boost использует один запрос из своего собственного пособия. Все стандартные ресурсы на странице имеют один стандартный запрос. Все необходимые надбавки должны быть доступны; ни одна из них не тратится на отклоненную страницу. Пустая страница использует стандартное пособие. Домен и DNS считывания могут использовать разрешение первого почтового ящика Boost UUID в этом домене, только когда ключ явно предоставляет mailbox.read И за это тоже. Это не увеличивает доступ к другим почтовым ящикам.

Включено 429Честь Retry-After и error.resetsAt.. Ежедневное использование истощения daily_quota_exceeded• Минутные ограничения использования rate_limited.. Ограничения стандартного плана включают error.metadata.upgrade Связь с Boost и более высокие надбавки. Покажите эту ссылку человеку, управляющему почтовым ящиком. Агент не может купить апгрейд. Повышенное истощение и потолки безопасности ключа / счета не предлагают обновления. X-Agent-Plan идентифицирует стандартный, расширенный или смешанный доступ; X-Agent-Daily-Limit, X-Agent-Daily-Remaining и X-Agent-Daily-Reset Опишите требуемую суточную надбавку с наименьшим количеством оставшихся запросов. Ключевые потолки по-прежнему считаются аутентифицированными отрицаниями. Недостающий объем возвращается 403Ресурс, выходящий за пределы гранта 404истекший или отозванный возврат ключей; 401.. Ограниченные полномочия работают на /api/v1 и /api/agent/mcp в своих первоначальных пределах. Эти маршруты не принимают ни куки браузера, ни ключи управления.

Управление аутентификацией API

Выберите «Новый ключ управления» Настройки → Ключи API.. Он показан один раз, при сотворении; мы храним только хеш и не можем показать его снова. Отправьте его в качестве маркера на предъявителя по каждому запросу:

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

Запросы JSON в и JSON вне. Ошибка является { "error": { "code", "message", "field? } } Соответствующий статус HTTP: 401 для ключа, который отсутствует, отозван или неизвестен, 403 Для маршрута ключ может не дойти, 422 За плохое поле.

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

Как может называться ключ управления

Пути относительны к https://franklymail.com/api.. Этот список исчерпывающий: маршрут на него не отвечает 401 на ключ, независимо от того, что он делает для зарегистрированного браузера.

Домены

Почтовые ящики

Алиасы и пересылка

Добавление домена, шаг за шагом

POST /domains Создает его и передает обратно записи для публикации. Больше ничего не нужно вызывать для начала проверки, так как проверки проводятся по собственному графику.

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

Опубликовать каждый records[] Запись у вашего провайдера DNS, а затем смотреть GET /domainsОдинаковая полезная нагрузка для каждого домена, поэтому один опрос охватывает целую партию. Три поля отвечают на три разных вопроса, и смешивание их является обычной ошибкой:

• records[].status: live Когда DNS ответит на наши ожидания, missing До тех пор.
• ownership: proven Рекорд DKIM был достигнут. Это тот, который открывает почтовые ящики и импортируетТаким образом, почта может быть скопирована задолго до переключения MX.
• statusВся область, active Когда все, включая MX, будет в прямом эфире, и почта действительно прибудет.

recheckIn Это секунды до следующей автоматической проверки; спите примерно так долго между опросами, а не молотите. POST /domains/:id/recheck Вынуждает немедленно и имеет ограниченную ставку на домен, поэтому используйте его после публикации записей, а не в качестве цикла опроса. Маршрут является идемпотентным для каждой учетной записи и имени: повторное размещение домена, который у вас уже есть, возвращает существующий, а не дубликат или ошибку.

Перемещение почтового ящика, шаг за шагом

Это поток, для которого написано большинство сценариев, и тот, с движущимися частями, который стоит указать, а не оставлять открытым.

1. Начни. POST /mailboxes/:id/import со старыми деталями подключения сервера. Пароль шифруется до того, как он коснется столбца, никогда не возвращается по какому-либо маршруту и очищается в тот момент, когда работа прекращается.

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

Отвечает 202Нет. 200Копия занимает от нескольких минут до нескольких часов, поэтому работа стоит в очереди, и запрос немедленно возвращается. Один импорт за раз на почтовый ящик.. Начало секунды, пока один запускает ответы 409 import_in_progress Идентификатор запущенной работы, потому что две параллельные копии одного и того же источника дублируют каждое сообщение, и повторная запись не отменяет этого. Тридцать почтовых ящиков могут импортировать сразу; лимит составляет на почтовый ящик, а не на аккаунт.

2. Следуй за ним. GET /mailboxes/:id/import возвращает последнюю работу для этого почтового ящика, или {"import": null} Если такового никогда не было.

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 является одним из pending, running, done, failed или cancelledПоследние три являются терминальными. Оцените его по порядку секунд, а не миллисекунд; считывания не ограничены, но счетчики движутся только так быстро, как отвечает другой сервер. folders_done / folders_total Это честная цифра прогресса: messages_done У него нет знаменателя, пока папка не будет открыта, поэтому процент, построенный из нее, будет прыгать назад. В случае неудачи, last_error несет предложение, написанное, чтобы быть показанным человеку.

3. Прекрати, если надо.POST /mailboxes/:id/import/cancel Заканчивает работу. Ничто не меняется у старого провайдера. Импорт всегда только читается из него. Сообщения, уже скопированные, остаются, если запрос явно не требует иного.

Две вещи, которые стоит знать, прежде чем писать это. Для почтового ящика нужна проверенная запись домена DKIM, а не полная обрезка MX, поэтому копия может работать за несколько дней до переключения почты. И развертывание нашего перезапускает панель: работа, которая была запущена, останавливается и не возобновляется сама по себе, поэтому сценарий, который запускает тридцать импортов, должен проверять их статус после этого, а не предполагать, что молчание означает успех.

Удаление вещей

Два правила, и они являются единственными местами, где этот API отказывается делать то, что вы просили:

• Почтовый ящик сохраняет свою почту, когда вы ее удаляете.DELETE /mailboxes/:id Вынимает адрес из службы и оставляет каждое сообщение там, где оно есть. Чтобы уничтожить почту, запрос должен сказать это и подтвердить точный подсчет байтов, который показал вам панель. Если почтовый ящик с тех пор вырос, в уничтожении отказывают, а не молча берут лишнее. Ничто из того, что агент делает случайно, не может уничтожить сообщение.
• Домен не может быть удален, пока на нем находятся почтовые ящики. Ты получишь 409 domain_has_mailboxes Перечислите адреса и какие из них были использованы. Сначала удалите каждый почтовый ящик: это шаг, на котором вопрос о почте задается, один раз на почтовый ящик, тем, кто имеет право ответить на него.

Если вы являетесь агентом: Не отвечайте ни на один вопрос от имени человека. Удаление почтового ящика обратимо до тех пор, пока почта не будет уничтожена, и никогда после. Когда задача подразумевает уничтожение, скажите, что будет уничтожено, и пусть человек решает.

Получить почту

Почтовый ящик может быть загружен как zip из файлов mbox, каждой папки, каждого сообщения, но Не с ключом API. GET /mailboxes/:id/export ответы 403 browser_only К ключу, потому что один маршрут передает саму почту, а не конфигурацию вокруг нее, и ключ живет именно в тех местах, откуда утекают секреты.

Для экспорта: откройте почтовый ящик в панели и используйте Download. Он транслируется по мере сборки, поэтому почтовый ящик больше, чем память, все еще прибывает, и нет работы, которую нужно ждать. Если вы хотите получить его с терминала, войдите в панель в браузере и позвоните по тому же URL-адресу с этим сеансом. Маршрут не изменился, отказались только ключи.

Сделай это. перед Удаление всего, что вы хотите вернуть. Экспорт : единственная копия, которая выживает после уничтожения.

Что не может сделать ключ

Ключ относится к одной учетной записи и в ней к трем вышеперечисленным вещам. Он не может загрузить почтовый ящик, не может получить биллинг, не может зарегистрировать домен (который тратит деньги), не может создавать пароли приложений, не может изменить пароль учетной записи или 2FA и не может создавать или отзывать другой ключ API, включая себя. Всем им нужен встроенный браузер.

Причина в форме верительных грамот, а не недоверия: ключ живет в одной точке. .env Файл, секретный магазин CI и агентская среда, а также секрет, который живет в трех местах, не должны быть в состоянии принять во внимание или заблокировать его владельца. Если ключ просачивается, отмените его в настройках: держатель не может сначала отчеканить замену.

О чем эта граница не говорит. Ключ может установить пароль почтового ящика, потому что создание и раздача почтовых ящиков - это работа, для которой он существует, и любой, кто может установить пароль почтового ящика, может затем войти в этот почтовый ящик более IMAP и прочитать его. закрытие export Это не меняет ситуацию, и делать вид, что иначе было бы хуже, чем ничего. Что действительно меняется, так это то, что путь больше не молчит: сброс пароля блокирует реального пользователя из его собственного почтового ящика, который заметен в течение часа, в то время как загрузка не оставляет ничего, кроме линии журнала. Если эта сделка не та, которую вы хотите для определенного ключа, не создавайте ключ: ключи управления не имеют диапазона ресурсов. Используйте соединение Agentic Inbox OAuth для почтового ящика, проверенного через веб-почту.

Ключи управления не истекают. Десять живых ключей на учетную запись, что является потолком, а не квотой, поэтому назовите их по сценарию или на машине, поэтому отзыв одного из них является очевидным решением.

Изменение пароля учетной записи отменяет каждый ключНа рутинной ротации столько же, сколько на выздоровлении. Никто не может отличить этих двоих в тот момент, когда они вводят новый пароль, поэтому безопасный ответ не зависит от того, какой он был. План для него: длительный сценарий должен громко провалиться на 401 Вместо того, чтобы повторять, тот, кто повернет пароль, впоследствии отчеканит новый ключ. Мы отправляем владельцу учетной записи электронное письмо всякий раз, когда создается ключ, и снова, когда изменение пароля отменяет их, поэтому ключ, сделанный кем-то другим, не остается незамеченным.

API управления и лимиты экспортных ставок

Два счетчика, оба на счет, а не на ключ, поэтому вращение ключа не сбрасывает их:

• 120 пишет каждые 5 минуты через домены, почтовые ящики и псевдонимы. Чтения не учитываются, поэтому опрос домена до тех пор, пока он не проверит, является бесплатным. Перемещение десяти доменов и тридцати почтовых ящиков стоит в общей сложности менее сотни записей, поэтому нормальная объемная работа не достигает этого.
• 30 почтовый ящик экспортируется в час. Экспорт передает каждое сообщение в почтовом ящике, что является самой дорогой вещью, которую можно попросить сделать.

Над одним из них вы получаете 429 с { "error": { "code": "rate_limited" } } и а Retry-After Заголовок в секундах. Подождите так долго, а не повторяйте сразу: многократное попадание в предел удлиняет паузу. Если законная работа нуждается в большем количестве залов, напишите нам, а не работайте над ней; мы предпочли бы увеличить число, чем узнать из счета.

Перенос нескольких доменов сразу

Порядок, который работает: POST /domains для каждого имени, публиковать записи, которые оно возвращает, опрос GET /domains До тех пор, пока каждый не будет проверен, POST /mailboxes по адресу. Почта может быть скопирована со старого хоста до обрезания MX, поскольку домену требуется только его запись DKIM, проверенная на наличие. POST /mailboxes/:id/import Чтобы работать, миграция и переход не должны происходить в один и тот же день.

MCP

Agentic Inbox обеспечивает удаленную конечную точку MCP https://franklymail.com/api/agent/mcp для чтения почтовых ящиков, поиска и подготовки проекта. Подключение через OAuth с помощью руководство по установке.. Администрация домена и почтового ящика использует отдельный HTTP API управления, описанный выше.