Переезд с SendGrid
Оставьте SDK SendGrid и отправляйте через OpenEmail. Смените его базовый URL и ключ, а код отправки останется как есть.
Что изменить
Направьте SDK на https://api.openemail.uk/compat/sendgrid и дайте ему вместо ключа SendGrid ключ API OpenEmail с разрешением emails:send. Он передаётся в том же заголовке Authorization: Bearer. Ваши вызовы, которые отправляют почту, остаются как есть, а адрес From решает, может ли письмо уйти, как и везде в OpenEmail.
import sgMail from '@sendgrid/mail'import client from '@sendgrid/client' client.setApiKey(process.env.OPENEMAIL_API_KEY)client.setDefaultRequest('baseUrl', 'https://api.openemail.uk/compat/sendgrid')sgMail.setClient(client) await sgMail.send({ from: '[email protected]', to: '[email protected]', subject: 'Your invoice', html: '<p>Your invoice is attached.</p>',})В Node сначала задайте ключ на клиенте, затем базовый URL, а потом передайте клиент почтовому пакету. Не вызывайте после этого sgMail.setApiKey, потому что он возвращает базовый URL SendGrid. SDK предупреждает, что ключ не начинается с SG., и это безвредно. В Python, Ruby и PHP указывайте хост без завершающей косой черты.
Что чему соответствует
Обслуживается эндпоинт POST /v3/mail/send. Каждый элемент personalizations становится отдельным письмом OpenEmail со своим id, поэтому один запрос отправляет не больше 100 писем.
| SendGrid | В OpenEmail |
|---|---|
| from | Отправитель вместе с именем. Персонализация может указать свой from. |
| personalizations | По одному письму на каждую. Её to, cc и bcc вместе вмещают до 50 получателей, а её subject, headers, custom_args, send_at и substitutions относятся только к этому письму. |
| subject | Тема, если персонализация не задаёт свою. |
| content | text/plain становится текстовой частью, а text/html частью HTML. text/x-amp-html опускается, потому что письмо и так несёт часть HTML. |
| attachments | Файлы, не больше 20 и 5 МБ в сумме. Встроенное изображение, чей content_id HTML использует как cid:, встраивается там, где оно стоит. Любой другой встроенный файл приходит обычным вложением. |
| reply_to | Адрес для ответа. reply_to_list тоже работает, пока в нём один адрес. |
| headers | Свои заголовки: X-*, List-*, Reply-To, Precedence, Auto-Submitted, Importance, Priority и Feedback-ID. Персонализация добавляет свои. |
| categories | Теги с именами category, category_2 и так далее, в каждом по одной категории. |
| custom_args | Теги с теми же именами и значениями. Значения персонализации имеют приоритет. |
| send_at | Отложенная отправка, до года вперёд. Время, которое уже прошло, означает отправку сразу. |
| substitutions | Каждый ключ заменяется своим значением в теме, текстовой части и части HTML этого письма. |
| template_id | id (tpl_...) или slug шаблона OpenEmail, заполненного из dynamic_template_data. |
| tracking_settings | open_tracking.enable и click_tracking.enable включают или выключают отслеживание открытий и кликов для письма. |
| mail_settings | sandbox_mode.enable проверяет запрос, отправителя и шаблон, а затем отвечает 200, ничего не отправляя. |
У письма не больше 10 тегов, считая категории и custom_args вместе. Запрос, которому нужно больше, отклоняется, а не обрезается, чтобы ничего из отправленного вами не пропало молча.
Что отклоняется и почему
- id шаблона SendGrid в
template_id, напримерd-…. Шаблоны остаются в SendGrid, поэтому создайте шаблон заново в OpenEmail и отправляйте его id или slug. contentрядом сtemplate_id, потому что шаблон OpenEmail даёт всё тело письма.substitutionsс шаблоном по той же причине: передавайте значения вdynamic_template_data.- Больше одного адреса для ответа,
reply_toиreply_to_listвместе, а также типы содержимого, кроме текста и HTML. Приглашение в календарь отправляйте вложением.ics. - Включённый
mail_settings.footer, а такжеsections, потому что OpenEmail не дописывает текст в ваше письмо. - Больше 10 тегов, имя тега из чего-то, кроме букв, цифр,
_и-, заголовок вне списка выше и больше 100 персонализаций в одном запросе.
asm, batch_id, ip_pool_name, настройки обхода в mail_settings, subscription_tracking, ganalytics, click_tracking.enable_text и open_tracking.substitution_tag принимаются и ничего не меняют. Адреса из списка подавления рабочего пространства всегда пропускаются, что бы ни говорила настройка обхода.
Ответы и ошибки
- Отправка отвечает 202 с пустым телом и id письма OpenEmail в
X-Message-Id, тем самым id, который используютGET /emails/{id}и вебхуки. При нескольких персонализациях там id первого письма. ЗаголовокIdempotency-Keyработает так же, как в остальном API. - Ошибки приходят как
errors, список изmessage,fieldиhelp: 400 для запроса, который нельзя отправить, 401 для отсутствующего или неизвестного ключа, 403 для ключа безemails:sendили адреса From, который ключу нельзя использовать или чей домен ещё не может отправлять, 413 для тела больше 30 МБ или вложений больше 5 МБ и 429, когда рабочее пространство исчерпало лимит отправки. - Если персонализация не прошла после того, как предыдущие были приняты, ошибка называет уже отправленные письма, чтобы повторная попытка могла их пропустить.