Подключение места через API

Как это устроено?

Ваша система собирает письмо, делает один запрос к RMEX и получает готовый HTML-блок для рекламного места (плейсмента). Блок вставляется в письмо как есть. Что в нём показать, решает RMEX: смотрит, какие сделки сейчас действуют на этом месте, и выбирает одну. Вёрстку, картинку и ссылки собираем мы.

Что нужно для начала

1. Номер места

Номер появляется, когда вы создаёте место в кабинете. У каждого места в шаблоне письма свой номер. Готовый запрос с номером лежит в карточке места: вкладка «Код вставки», строка «Запрос блока в момент отправки».

2. Ключ API

Ключ вы выпускаете сами: «Настройки → Ключи API», кнопка «Выдать ключ». Раздел виден владельцу кабинета.
app.rmex.io/sp/settings/api-keys
Ключ показывается один раз: скопируйте его сразу, второй раз посмотреть будет негде. Ключ открывает только ваши места. Храните его на сервере: в письмо он не попадает. Ненужный ключ отзовите там же, кнопкой «Отозвать»: запросы с ним сразу перестанут проходить.

Получаем ключ API · 0:36

Запрос

Когда вызывать?

Один раз на каждое письмо, в момент сборки письма, с вашего сервера.

Как выглядит запрос?

GET https://app.rmex.io/v1/ad-slot/{номер места}?u={id письма}
Authorization: Bearer {ключ}

Вместо Authorization можно передать заголовок X-API-Key: {ключ}.

То же самое на curl:

curl -G https://app.rmex.io/v1/ad-slot/123 \
  -H "Authorization: Bearer <ВАШ_КЛЮЧ>" \
  --data-urlencode "u=8f14e45f-ea3f-4b1f-9f1a-2c0d5a7b1e33"

Где посмотреть все параметры?

В документации API (Swagger). Она открывается из кабинета, пункт «API» в левом меню: там запрос GET /v1/ad-slot, его параметры u и ctx и поля ответа. Нужно войти в кабинет.
app.rmex.io/swagger-ui.html

Документация API · 0:31

Параметр u

Что это?

u — это ваш идентификатор конкретного письма. У каждого письма свой, у одного письма всегда один и тот же. Мы вписываем его в ссылки блока: в ссылку перехода и в пиксель открытия.

Зачем он нужен?

По нему мы понимаем, что два открытия это одно письмо, открытое дважды, а не два разных письма. Без u приходится угадывать по адресу и браузеру. Яндекс Почта и Gmail загружают картинки через свои серверы, поэтому разные получатели выглядят для нас одинаково, и открытий в отчёте получается меньше, чем было на самом деле.

Что может быть u?

Любой ваш внутренний идентификатор, уникальный для письма:

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

Что нельзя?

Почту и телефон получателя. u попадает в ссылки внутри письма открытым текстом.
Один и тот же u для разных писем. Открытия разных писем сольются в одно.
Знаки { } [ ] % * |. Значение с ними мы считаем незаменённой заглушкой (см. ниже).

Длина: не больше 64 знаков. Латиница, цифры, дефис и подчёркивание подходят всегда.

Влияет ли u на деньги?

Если место оплачивается за клики, нет: от u зависит только точность счёта открытий. Если место оплачивается за открытия, открытие без u не засчитывается.

Если вы кэшируете ответ

Обязательно вызывать на каждое письмо?

Нет. Можно забрать блок один раз и использовать для пачки писем. Держите такой кэш не дольше 5 минут: за это время на месте может смениться сделка.

Как тогда передать u?

Вызывайте без u. В ссылках блока вместо идентификатора письма придёт заглушка {{U}}. Перед отправкой каждого письма замените в блоке все {{U}} на идентификатор этого письма. Заглушка встречается в блоке несколько раз, заменить нужно каждую.

Если заглушку не заменить, письмо считается письмом без u: открытия считаются по адресу и браузеру, а при оплате за открытия не засчитываются.

Ответ

Ответ всегда приходит с кодом 200, если запрос правильный. Есть ли в нём блок, показывает поле no_fill.

Что приходит, если на месте есть действующая сделка?

no_fill равно false, в banner_block готовый HTML. Вставьте его в письмо как есть.

{
  "banner_block": "<table role=\"presentation\" ...>...</table><img src=\"https://app.rmex.io/t/open/c/77?...\" .../>",
  "no_fill": false,
  "campaign_id": 77,
  "advertiser_name": "ООО «Пример»",
  "price_cpm": null,
  "currency": "RUB"
}

Поля campaign_id, advertiser_name, price_cpm и currency справочные, для ваших логов. В письмо они не идут.

Что приходит, если действующей сделки нет?

{ "banner_block": "", "no_fill": true }

Это обычный ответ, а не ошибка. Так бывает, когда на месте нет сделки, показы остановлены или ни один баннер сделки не подходит под место. Так же мы отвечаем при сбое на нашей стороне: письмо не должно пострадать из-за нас. Покажите в письме то, что стоит на этом месте у вас без рекламы.

Какие бывают ошибки?

401: ключа нет, он неверный или отозван.
403: учётная запись, которой выдан ключ, не активна.
404: место не ваше или его нет.
409: место не настроено на выдачу в момент отправки письма. Напишите нам.

Если RMEX не ответил?

Поставьте на запрос таймаут. При ошибке или по истечении таймаута отправляйте письмо так, как будто пришёл ответ без сделки: с вашим содержимым места. Письмо важнее рекламы.

Как выглядит блок

Что внутри?

Блок свёрстан под почтовые программы: таблицы, встроенные стили и отдельная разметка для Outlook. Внутри:

картинка и, в зависимости от формата баннера, заголовок, подпись и кнопка. Всё это ведёт по одной ссылке перехода https://app.rmex.io/c/c/...;
пиксель открытия https://app.rmex.io/t/open/c/..., невидимая картинка 1×1;
если баннер рекламный, внизу строка маркировки: «Реклама. Рекламодатель. erid: …». Оставьте под неё место в вёрстке. У информационного блока этой строки нет.

Можно ли править блок?

Нет, кроме замены {{U}}. В ссылках стоит наша подпись: переход по изменённой ссылке уведёт на главную RMEX, а не к рекламодателю. Если переходы нужно заворачивать через ваш домен, напишите нам.

Как выглядит готовый блок?

Ниже настоящий блок из нашего теста: информационный, без маркировки, u равен msg-uuid-1. Блок приходит одной строкой, так его и вставляйте.

<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="max-width:600px;margin:0 auto;background:#ffffff;border-radius:8px"><tr><td align="center" style="padding:16px;font-size:0;text-align:center"><!--[if mso]><table role="presentation" width="100%" cellpadding="0" cellspacing="0"><tr><td valign="middle" width="110"><![endif]--><div style="display:inline-block;vertical-align:middle;width:100%;max-width:110px"><a href="https://app.rmex.io/c/c/77?t=ctok123456&amp;u=msg-uuid-1" target="_blank" style="text-decoration:none;border:0"><img src="https://app.rmex.io/ad/img/c/77?t=ctok123456" width="110" height="92" alt="Вам подарок" style="display:block;border:0;width:100%;max-width:110px;height:auto;border-radius:6px;margin:0 auto"/></a></div><!--[if mso]></td><td valign="middle"><![endif]--><div style="display:inline-block;vertical-align:middle;width:100%;max-width:380px"><a href="https://app.rmex.io/c/c/77?t=ctok123456&amp;u=msg-uuid-1" target="_blank" style="display:block;text-decoration:none"><div style="font-family:Arial,Helvetica,sans-serif;font-size:16px;font-weight:bold;color:#111827;background:#ffffff;padding:10px 6px 0;text-align:center">Вам подарок</div><div style="font-family:Arial,Helvetica,sans-serif;font-size:13px;color:#4b5563;background:#ffffff;padding:4px 6px 0;text-align:center">До конца недели</div></a><div style="background:#ffffff;padding:12px 4px 4px;text-align:center"><a href="https://app.rmex.io/c/c/77?t=ctok123456&amp;u=msg-uuid-1" target="_blank" style="display:inline-block;max-width:100%;box-sizing:border-box;background:#2563eb;color:#ffffff;font-family:Arial,Helvetica,sans-serif;font-size:14px;font-weight:bold;white-space:nowrap;text-decoration:none;padding:12px 28px;border-radius:8px">Забрать</a></div></div><!--[if mso]></td></tr></table><![endif]--></td></tr></table><img src="https://app.rmex.io/t/open/c/77?t=ctok123456&amp;u=msg-uuid-1" width="1" height="1" alt="" style="display:none"/>

Дополнительно

Можно ли сообщить что-то о получателе?

Да, необязательным параметром ctx: сумма чека, ИНН, ваши сегменты. Он описан в отдельной статье «Контекст запроса». Без него всё работает.