fast-mailer: як винесення моделі з кроку надсилання скоротило лист до секунд

ІСТОРІЯ ЗБІРКИ · ІНСТРУМЕНТИ ДЛЯ АГЕНТІВ

Агент, якому потрібна від однієї до чотирьох хвилин на один лист, не думає з усіх сил. Він чекає: поки завантажиться браузер, поки зʼявиться кнопка, поки настане його наступний хід. Автор fast-mailer, невеликого open-source репозиторію, опублікованого 24 вересня 2026 року, каже, що в друга була саме така проблема. Рішенням стала не розумніша модель. Він прибрав модель із тієї частини роботи, де вона ніколи не була потрібна.

ШВИДКА ВІДПОВІДЬ

Чому це швидко

Агент пише лист і передає його далі. Звичайний скрипт збирає повідомлення й надсилає його прямо в Gmail API. Ні браузера, ні запуску додаткового сервера інструментів, ні виклику моделі між «надіслати» і «надіслано».

Проблема: агент виконує роботу скрипта

Багато агентних систем надсилають пошту так, як це зробила б людина: відкрити Gmail у браузері, натиснути «Написати», ввести текст, натиснути «Надіслати». Кожен крок - це коло через модель, яка дивиться на сторінку й вирішує, що робити далі. Файл навички в самому репозиторії ставить шлях через браузер на останнє місце й позначає його «minutes - last resort only» («хвилини - лише в крайньому разі»). Автор не описав, як саме агент друга надсилав листи раніше, тож браузер - імовірна причина, а не підтверджена.

Що лежить у репозиторії

Частина	Що робить
send.py	Лише стандартна бібліотека Python. Збирає MIME-повідомлення, оновлює OAuth-токен у пам'яті, надсилає запит на ендпоінт надсилання Gmail і друкує JSON з ID листа та витраченим часом.
Тека triggers/	Покладіть по одному файлу .txt або .json на лист і запустіть python send.py watch --once. Надіслані файли переїжджають у triggers/sent/, невдалі отримують суфікс .failed.
cli/gmaild.mjs	Необов'язковий демон на Node 18+ на 127.0.0.1: тримає тепле TLS-з'єднання з Gmail і оновлює токен кожні 5 хвилин.
cli/auth-server.js	Одноразовий вхід через Google, зберігає refresh-токен у secrets/.
skills/fast-mailer/SKILL.md, AGENTS.md	Інструкції для Claude Code, Cursor, ZCode та схожих інструментів: яку команду запускати. Плюс обгортка-плагін для ZCode.

Звідки беруться 14 секунд

До: агент керує поштовим інтерфейсом, один хід моделі на клік→Після: агент пише to, subject, body→Одна команда в терміналі→Скрипт надсилає в Gmail API→JSON: message_id + ms

Сам виклик надсилання короткий. Серце send.py - один HTTPS POST з повідомленням у base64 на gmail.googleapis.com/gmail/v1/users/me/messages/send, ендпоінт, який Google документує саме для цього. README оцінює його в 0,6-1 секунди «з холоду» і приблизно в 0,5 секунди з демоном.

Куди йдуть решта ~13 секунд? Це моє тлумачення, а не вимірювання: агентові все одно треба прочитати запит, написати команду, дочекатися результату й відповісти. Це один хід моделі замість десятків. Файл навички навіть велить відповідати «лише message_id + ms. Без розповіді», і це скорочує останній крок.

Прискорення не в швидшому надсиланні, а в меншій кількості ходів моделі між проханням і результатом.

Що я перевірив у коді

Я запустив send.py офлайн у пісочниці з фіктивними обліковими даними та підміненим мережевим викликом, тож нічого не надіслалося. Збирання повідомлення зайняло близько 1,4 мс. Заяви README про безпеку підтвердилися в тих шляхах, які я перевірив:

• Дозволено лише два хости: oauth2.googleapis.com і gmail.googleapis.com. Запит на будь-який інший URL відхиляється.
• Імена файлів у triggers мають відповідати суворому шаблону. ../x.txt, імена з пробілами та приховані файли було відхилено.
• Перед кожним запитом хост резолвиться й блокується, якщо вказує на приватну чи локальну адресу. Редиректів не більше 2.
• Python-відправник ніколи не пише у файл токена. Демон записує оновлені токени з правами файлу 0600.

Одна прогалина: поля теми й отримувача не перевіряються на переведення рядка. У моєму офлайн-тесті тема Hello + переведення рядка + Bcc: attacker@example.net дала справжній зайвий заголовок Bcc. Якщо агент надсилає лише те, що ви самі надрукували, це неважливо. Якщо він може перенести в тему текст із вебсторінки чи вхідного листа - важливо. Коротке виправлення:

# add at the top of send_email() in send.py
for field in [to, subject, sender or ""] + list(cc or []):
    if "\r" in field or "\n" in field:
        raise ValueError("line break in a header field")

Спробуйте: заміряйте свій шлях

Щоб зрозуміти, куди йде час вашого агента, заміряйте скрипт окремо й порівняйте з повним ходом агента. Скрипт сам повертає поле ms; ця обгортка додає загальний час навколо нього:

start=$(date +%s.%N)
python send.py you@example.com "timing test" "hello" | tee /tmp/send.json
end=$(date +%s.%N)
echo "script wall time: $(echo "$end - $start" | bc) s"
# the gap between this and the agent's full reply time is model time

Аналіз (Jack Gross)

Загальний урок: тримайте модель поза гарячим шляхом

Схема проста, і її варто копіювати не лише для пошти. Якщо завдання має фіксовану форму (кому, тема, текст), нехай модель заповнить поля, а решту зробить звичайний код. Кожен крок, який модель має спостерігати й схвалювати, коштує секунд і додає шанс помилки. Від 1-4 хвилин до 14 секунд - це приблизно скорочення в 4-17 разів, і майже все воно здобуте завдяки прибраним ходам моделі, а не швидшій мережі.

Тека triggers - ідея цікавіша. Вона розділяє «вирішити, що надіслати» і «надіслати». Агент, cron-завдання чи людина можуть ставити листи в чергу файлами, а одне сканування надішле їх усі. Заодно вихідні легко переглянути, перш ніж щось піде.

Обмеження, про які варто памʼятати

• Зовсім новий. Опублікований у день написання статті, v1.0.0, тестів у репозиторії немає, зовнішніх користувачів поки немає. Цифра в 14 секунд - звіт однієї людини про одну конфігурацію.
• Широкі права. Під час входу запитуються gmail.modify і gmail.readonly. У документації Google для надсилання достатньо вужчого gmail.send. Викрадений токен із такого встановлення дасть змогу читати й змінювати вашу пошту, а не лише надсилати.
• Перевірка заголовків. Додайте перевірку переведень рядка вище, перш ніж подавати недовірений текст.
• Ліміти Gmail нікуди не зникли. Google обмежує надсилання на добу (наприклад, 2000 листів на користувача в Google Workspace, 500 для пробних акаунтів) і 500 отримувачів на один лист через API. У скрипті немає обмеження швидкості й повторів, окрім одного оновлення токена, тож масові розсилки впруться в ці ліміти.
• Швидкість ріже в обидва боки. Без кроку в браузері немає екрана, на якому людина кине погляд на чернетку. Якщо агент має питати перед надсиланням, ця перевірка тепер мусить жити в його інструкціях.
• Налаштування. Потрібен власний проєкт Google Cloud і OAuth-клієнт, а помічник входу за замовчуванням займає порт 80.
• Лише Gmail. Немає Outlook чи звичайного SMTP, і в поточному коді немає вкладень.

Вердикт

fast-mailer - невелике читабельне рішення реальної та частої проблеми, а його модель безпеки охайніша, ніж у більшості інструментів першого дня. Вважайте його добрим відправним пунктом: звузьте область до gmail.send, додайте перевірку заголовків і залиште людське підтвердження там, де воно важливе. Урок виходить далеко за межі пошти: менше ходів моделі краще, ніж швидша модель.

FAQ

fast-mailer використовує AI-модель для надсилання листів?

Ні. Агент пише вміст, а потім скрипт надсилає його через Gmail API без виклику моделі між ними.

14 секунд - це час надсилання одного листа?

Це час усього ходу агента за словами автора. Сам виклик надсилання, за README, триває близько 0,6-1 секунди.

З якими агентами він працює?

З будь-яким агентом, що вміє запускати команди в терміналі. У репозиторії є інструкції для Claude Code, Cursor і ZCode.

Джерела: fast-mailer на GitHub (код, README, SKILL.md, історія комітів, прочитано 24 вересня 2026) · Gmail API: users.messages.send · Ліміти надсилання Gmail у Google Workspace. Час 1-4 хвилини та 14 секунд - зі слів автора репозиторію.