Статус «письмо отправлено» доказывает только то, что транспорт принял сообщение. Он не подтверждает, что 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 | Сервер принял сообщение и вернул идентификатор | Ограничение размера или политика транспорта |
| Mailbox | Raw 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 связывает четыре журнала
- Создать обезличенный PDF с уникальным document_id.
- Зафиксировать размер и SHA-256 сразу после генерации.
- Перед отправкой сверить те же значения в worker.
- Сохранить .eml и подтвердить attachment обычным клиентом.
- Отправить на контролируемый ящик и записать SMTP message ID.
- Скачать принятое вложение и сравнить checksum.
Повтор отправки использует тот же неизменяемый артефакт
Retry после сетевой ошибки не должен заново генерировать документ с другим содержимым под тем же письмом. Сохраните версию PDF и idempotency key операции доставки. Если SMTP принял письмо, но клиент не получил ответ, повтор решается по вашей политике дедупликации и журналу провайдера, а не безусловной отправкой второго счёта.
Для разбора нужны document_id, временная шкала состояний, размер и checksum, результат attachment-метода, обезличенная структура .eml и SMTP-ответ. Пароли, токены и сам клиентский PDF присылать не требуется. Такой набор точно отделяет проблему генерации, очереди, MIME и почтовой политики.