Файлы, Байты и Авто-ZIP

Флаг auto_zip=True позволяет автоматически сжимать массивные файлы в единый архив перед отправкой. Это существенно экономит трафик и предотвращает отказ серверов из-за превышения лимитов на размер вложений.

# Данные в оперативной памяти (например, сгенерированный PDF)
pdf_data = b"%PDF-1.4 ... (сырые байты) ..."

mailer.send(
    to="boss@company.com",
    subject="Квартальные отчеты",

    # 1. Файлы с диска (будут сжаты в .zip)
    attachments=["./huge_video.mp4", "./logs.txt"],
    auto_zip=True,

    # 2. Файлы из памяти (bytes)
    attachments_bytes=[
        {"name": "report.pdf", "data": pdf_data, "mime_type": "application/pdf"}
    ],

    # 3. Встраивание изображений в тело письма (Inline images)
    html='Посмотри на этот график: <img src="cid:my_chart">',
    inline_images={"my_chart": "./sales_chart.png"}
)

Инвайты в Календарь

Библиотека автоматически формирует валидный .ics файл, корректно обрабатывает спам-фильтры (генерируя уникальные UID) и выводит интерактивную кнопку «Добавить в Календарь» в интерфейсе почтового клиента получателя.

mailer.send(
    to="team@company.com",
    subject="Еженедельный Синхрон 📅",
    text="Жду всех на звонке.",
    calendar_event={
        "title": "Синхронизация команды",
        "start": "20260224T100000Z", # Формат времени UTC (YYYYMMDDTHHMMSSZ)
        "end": "20260224T110000Z",
        "location": "Zoom / Google Meet"
    }
)

Асинхронность и Сессии (Keep-Alive)

Используйте контекстный менеджер AsyncMailSession для поддержки постоянного соединения (Keep-Alive). Это обеспечивает высокую пропускную способность при массовых рассылках, исключая издержки на повторную авторизацию (handshake) при отправке каждого нового письма.

import asyncio

async def mass_mailing():
    users = ["user1@mail.com", "user2@mail.com", "user3@mail.com"]

    # Открываем единое соединение с SMTP-сервером
    async with mailer.get_async_session() as session:
        for user in users:
            # Отправка без задержек на переподключение
            await session.send_async(to=user, subject="Дайджест", text="Привет!")

asyncio.run(mass_mailing())

Песочница и Telegram Логгер

Укажите test_mode=True во время локальной разработки — письма будут выводиться в консоль, а не уходить в сеть. Если передать параметры Telegram, внутренний логгер перехватит критические ошибки SMTP и мгновенно доставит подробный traceback напрямую в ваш админ-чат.

smtplib.SMTPAuthenticationError: (535, b'5.7.8 Username and Password not accepted. Learn more at\n5.7.8  https://support.google.com/mail/')

Гайды и Практические Примеры

from fastapi import FastAPI, Request
from py_postman import Postman
import traceback

app = FastAPI()
mailer = Postman(email="bot@site.com", password="pass", provider="gmail")

@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
    error_trace = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))

    # Отправляем письмо админу асинхронно
    await mailer.send_async(
        to="admin@site.com",
        subject=f"🚨 Ошибка на {request.url.path}",
        markdown=f"**Произошла ошибка 500:**\n\n```python\n{error_trace}\n```",
        priority="high"
    )
    return {"message": "Internal Server Error"}

mailer.send(
    to="ceo@company.com",
    subject="📊 Отчет за 24 октября",
    markdown="""
    ## Доброе утро!

    За прошедшие сутки мы наблюдаем стабильный рост. Обратите внимание на график ниже:

    

    **Ключевые метрики:**
    * Регистрации: +150
    * Доход: $4,500
    """,
    inline_images={"daily_chart": "assets/today_growth.png"}
)

История версий

Справочник API: send()