Отправка писем через SMTP

Уже используете SMTP в своем приложении? Вы можете мгновенно переключить доставку писем на наш сервис. Эта функция позволяет отправлять сообщения через обычный SMTP — для этого нужно лишь указать SMTP-сервер Haskimail.

Почему стоит использовать SMTP вместо API?

Зачастую веб-приложения уже настроены на отправку писем через SMTP, а переход на Haskimail потребовал бы изменения кода. Благодаря доступу по SMTP вы можете просто изменить настройки в конфигурации вашего приложения и мгновенно переключить доставку на Haskimail.

Как это работает?

Существует два способа отправки через SMTP, в зависимости от возможностей вашего SMTP-клиента. Разница между ними заключается только в настройках.

SMTP-клиент — это любое веб-приложение или почтовый клиент, позволяющий настраивать и вводить данные SMTP (такие как SMTP-сервер, имя пользователя, пароль и т.д.) для отправки писем.

Для отправки вы должны использовать SMTP-реквизиты. Их вы можете найти, выбрав сервер, затем нужный канал и перейдя в его «Настройки». SMTP-реквизиты состоят из логина и пароля. Их всегда можно перевыпустить.

SMTP-реквизиты уникальны для каждого канала.

Вы можете отдельно включить или отключить доступ по SMTP для каждого сервера на странице его Настроек.

Посмотреть реквизиты SMTP-подключений — Параметры подключения по SMTP

После включения доступа вы сможете использовать следующий адрес для подключения: smtp.haskimail.ru.

Параметры подключения по SMTP

Сервер - smtp.haskimail.ru
Порт - 25, 2525, or 587
Шифрование - TLS или Auto STARTTLS . Использование шифрования обязательно для всех соединений.
Логин и пароль для авторизации. Вы можете найти их в разделе "Настройки"

Глобальная сеть SMTP-серверов

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

Чем SMTP отличается от REST API

Наш основной и самый функциональный инструмент — это REST API. SMTP-интерфейс — это, в первую очередь, простой способ перейти на Haskimail, если ваше приложение уже работает с SMTP. Он позволяет обойтись без изменения кода, но при этом вы не сможете использовать некоторые возможности, которые доступны только через API:

Многие клиентские библиотеки для REST API предлагают дополнительные возможности, например, повторные попытки отправки при сетевых сбоях. Это помогает в случаях временных проблем с доступом к серверам Haskimail.
API также поддерживает пакетную отправку для повышения производительности при отправке большого количества писем.
Еще одно важное преимущество REST API — это коды ответа. REST API немедленно возвращает вашему приложению сообщение об успехе или ошибке после получения запроса на отправку. Например, если адрес получателя был деактивирован из-за постоянной ошибки доставки (hard bounce), вы сразу же получите уведомление об этом при попытке отправки. Кроме того, ответ будет содержать Message-ID для отслеживания, а также коды ошибок для их корректной обработки. При отправке через SMTP сервер примет любое сообщение, а ошибки доставки будут зарегистрированы позже. Получить информацию о них можно с помощью наших вебхуков для отслеживания ошибок доставки или через соответствующий эндпоинт в API..
Теги можно использовать в SMTP-сообщениях, так же, как и при работе с API. Чтобы присвоить тег сообщению, необходимо добавить его в SMTP-заголовок с именем X-HM-Tag. Следовательно, ваш SMTP-клиент должен поддерживать добавление таких заголовков. Большинство языков программирования, имеющих модули для работы с SMTP, предоставляют способ добавления пользовательских заголовков к сообщениям. Для одного письма можно использовать только один тег. Максимальная длина тега — 1000 символов.

Хотя первоначальная настройка REST API сложнее, в дальнейшем он обеспечивает более быстрое и эффективное взаимодействие вашего приложения с Haskimail.

X-HM-Tag: welcome-email

Отслеживание открытий

Активировать отслеживание открытий для ваших писем можно следующими способами:

Чтобы отключить отслеживание открытий в конкретном письме следует передавать заголовок X-HM-No-Track-Opens, содержащий любое значение.

Отслеживание ссылок

Отслеживание ссылок можно включить несколькими способами, как описано в руководстве.

Чтобы отключить отслеживание кликов в конкретном письме следует передавать заголовок X-HM-No-Track-Click, содержащий любое значение.

Поддержка пользовательских переменных

Вы можете добавлять пользовательские переменные в письма, отправляемые через SMTP, с помощью специального SMTP-заголовка. Заголовок X-HM-Metadata должен содержать JSON-массив параметров, которые вы бы хотели получить в вебхуке. Например, чтобы передать и получить обратно пользовательские значения для color и client-id-id, добавьте в письмо следующий заголовок:

X-HM-Metadata: {"color":"blue","client_id": 12345}

Выбор определенного домена отправки

Вы можете выбрать конкретный домен отправки, используемый для DKIM-подписи, с помощью специального SMTP-заголовка X-HM-Domain

X-HM-Domain: kremlin.ru

Если он не будет задан, то будет подбираться соответствующий полю From или использовать просто первый в списке настроенных.

Установка MessageID

Вы можете задать внутренний идентификатор письма в Хаски в заголовке X-HM-Domain. Этот идентификатор используется при передачи вебхуков, отображении логов писем и других внутренних процессах

X-HM-MessageID: test-123-abc-777

Если он не задан, то генерируется в HaskiMail случайным образом.

Устранение неполадок с SMTP #

Из-за особенностей протокола SMTP мы не можем напрямую вернуть ошибку вашему SMTP-клиенту, если в самом сообщении обнаружится проблема. Чтобы обойти это ограничение, мы регистрируем особый тип отклоненного письма – SMTPApiError. В описании такого письма будет содержаться краткое сообщение об ошибке. Для получения более подробной информации, включая код ошибки, проверьте исходный код возврата (raw source). В нем также будет содержаться исходное тело самого SMTP-сообщения. Вам следует периодически проверять отклоненные письма или настроить вебхук для отклоненных писем , который будет оповещать вас о сбоях доставки по SMTP.

Почему для получателей из полей «Копия» и «Скрытая копия» создается отдельное письмо?

Такое может произойти, если ваш SMTP-клиент не полностью совместим с сервисом Haskimail. Некоторые клиенты передают адреса получателей (из полей «Кому», «Копия» и «Скрытая копия») не единой транзакцией, а несколькими последовательными командами. Из-за этого наш сервис воспринимает каждую команду как запрос на отправку нового, отдельного письма. Такое поведение характерно для некоторых почтовых клиентов, например, Gmail или Office 365, при отправке писем через сторонний SMTP-сервер.

Почему не проходит аутентификация на SMTP-сервере?

Убедитесь, что вы используете корректные реквизиты от вашего транзакционного канала одновременно в качестве имени пользователя и пароля. Также проверьте, что для вашего сервера включен доступ по SMTP на странице настроек этого канала.

Что еще можно предпринять при проблемах с отправкой по SMTP?

Проверьте все доступные порты. Поочередно попробуйте указать в настройках SMTP порты 25, 2525 и 587. Иногда определенный порт может быть перегружен, что приводит к временным сбоям, или просто заблокирован вашим интернет-провайдером.
Убедитесь в корректности указываемых логина и пароля для аутентификации.
Проверьте файрвол и сеть. Убедитесь, что настройки вашего файрвола (межсетевого экрана) или сети не блокируют доступ к нашим SMTP-серверам.

Устранение неполадок с кодировками и наборами символов

Haskimail стремится обеспечить поддержку максимально широкого спектра кодировок, наборов символов и почтовых клиентов. Однако иногда встречаются комбинации, которые могут обрабатываться некорректно. Например, Mozilla Thunderbird для кодировки ISO-8859-2 использует метод передачи Content-Transfer-Encoding: 8bit, который не добавляет необходимую сигнатуру BOM (Byte Order Mark). В результате некоторые спецсимволы могут отображаться неправильно. Для обеспечения максимальной совместимости с системами обработки почты мы рекомендуем использовать метод кодирования Quoted-Printable.