Статус «письмо отправлено» доказывает только то, что транспорт принял сообщение. Он не подтверждает, что PDF существовал в момент сборки, что библиотека прочитала правильный путь и что получатель увидел ту же MIME-структуру. Поэтому диагностика начинается до SMTP — с самого файла.

У артефакта должен быть собственный паспорт

После генерации запишите document_id, абсолютный путь или object key, размер, MIME type и SHA-256. Проверьте, что размер больше разумного минимума, начало соответствует PDF, а генератор закрыл поток. Только после этого переводите документ в состояние ready_for_delivery.

Контрольная точкаНормальный признакЧто означает сбой
ГенераторФайл существует, размер стабилен, checksum рассчитанРанний enqueue или незакрытый поток
WorkerЧитает тот же document_id и object keyВременный путь исчез на другой машине
MIME builderЕсть application/pdf part с filenameВызов attachment пропущен или вернул ошибку
SMTPСервер принял сообщение и вернул идентификаторОграничение размера или политика транспорта
MailboxRaw source содержит тот же attachmentФильтрация после приёма либо другой получатель

Особенно ненадёжен путь в системный temp. Веб-запрос создаёт PDF, ставит письмо в очередь и завершается; другой worker позже ищет локальный файл на другой машине или после очистки. Очередь должна хранить устойчивый object key либо неизменяемый document_id, а не случайный путь процесса.

Очередь получает ссылку на готовый документ

pdf = documentStore.create(orderId)
assert pdf.state == "ready"
assert pdf.size > 100 and pdf.sha256 is not null
job = mailQueue.enqueue(template="invoice", documentId=pdf.id)
workerPdf = documentStore.open(job.documentId)
message.attach(workerPdf.bytes, filename="invoice.pdf", contentType="application/pdf")
smtpId = transport.send(message)

Имя файла для пользователя и ключ хранилища — разные сущности. Имя нормализуйте, уберите управляющие символы и не подставляйте непроверенный ввод в локальный путь. Популярные библиотеки умеют прикреплять файл или строку байтов; используйте публичный метод библиотеки вместо ручной склейки заголовков.

MIME-структуру можно проверить без доставки

Сохраните тестовое сообщение в формате .eml до вызова SMTP и откройте его обычным почтовым клиентом. В multipart/mixed должна быть отдельная часть с Content-Type application/pdf, способом передачи и безопасным filename. RFC 2045 определяет механизмы MIME и Content-Transfer-Encoding; двоичный PDF обычно передаётся закодированным, а библиотека выставляет границы частей.

  • Не задавайте общий Content-Type письма как application/pdf — это тип одной части, а не всего сообщения.
  • Не вкладывайте base64-строку как обычный текст без заголовков MIME.
  • Не рассчитывайте лимит только по исходному размеру: транспортное кодирование увеличивает сообщение.
  • Не логируйте содержимое PDF; достаточно document_id, размера и checksum.
  • Не считайте успешным вызов, если метод добавления вложения вернул ошибку.

Размер проверяется на всём маршруте

Лимит может существовать в приложении, SMTP-реле, почтовом сервисе и ящике получателя. Перед отправкой считайте полный сериализованный размер сообщения, а не только PDF. Если документ слишком велик, предложите защищённую ссылку с ограниченным сроком и понятным сообщением пользователю вместо молчаливой отправки письма без вложения.

Один correlation ID связывает четыре журнала

  1. Создать обезличенный PDF с уникальным document_id.
  2. Зафиксировать размер и SHA-256 сразу после генерации.
  3. Перед отправкой сверить те же значения в worker.
  4. Сохранить .eml и подтвердить attachment обычным клиентом.
  5. Отправить на контролируемый ящик и записать SMTP message ID.
  6. Скачать принятое вложение и сравнить checksum.

Повтор отправки использует тот же неизменяемый артефакт

Retry после сетевой ошибки не должен заново генерировать документ с другим содержимым под тем же письмом. Сохраните версию PDF и idempotency key операции доставки. Если SMTP принял письмо, но клиент не получил ответ, повтор решается по вашей политике дедупликации и журналу провайдера, а не безусловной отправкой второго счёта.

Для разбора нужны document_id, временная шкала состояний, размер и checksum, результат attachment-метода, обезличенная структура .eml и SMTP-ответ. Пароли, токены и сам клиентский PDF присылать не требуется. Такой набор точно отделяет проблему генерации, очереди, MIME и почтовой политики.

Проверенные источники