Настройка DKIM-ключей рассылок¶
DKIM-ключ используется для двух целей
-
Добавление в email-сообщения клиентской dkim-подписи для лучшей доставляемости
-
Возможности заменить стандартные системые технические адреса и домены на свои
Минимальное использование - для dkim-подписи - применимо только к выпускам по email
Максимальное - с кастомизацией - позволяет заменить служебные адреса и домены на свои не только в email, но и для других каналов выпуска.
Кастомизация доменов с помощью dkim-ключа¶
При успешной настройке кастомизации служебные почтовые адрес (например, используемый в MAILFROМ) и домены (например, используемый для учёта переходов link.sendsay.ru) будут использовать ваш домен.
Например, при выделении под кастомизацию домена mail.client.tld домен учёта переходов станет link.mail.client.tld
Перед тем как настраивать dkim-ключ, необходимо правильно настроить DNS-записи для домена link.mail.client.tld
Самый простой и безболезненный пусть - делегировать его нам - мы проведем все настройки и они будут всегда в актуальном состоянии
Если делегирование не возможно, то вы сами вносите необходимые записи в ваш DNS.
Инструкции для обоих способов настройки можно получить в Службе Поддержки.
После настройки DNS указать в dkim-ключе что его домен кастомизированный (issue.dkim.set) и провести проверку (issue.dkim.check).
Ниже приведено описание доступных параметров кастомизации из которых вам, скорее всего, понадобится только domain.custom.
domain.custom: 1 - использовать для кастомизации, все ниже описанные настройки не действуют если domain.custom = 0 или пуст или отсутствует
domain.email: "+" - признак того, что почта настроена клиентом самостоятельно и проверять корректность её настройки при проверки MX DKIM не надо - остальные значения игнорируются. ОСТАВЛЯТЬ ПУСТЫМ если не "+" !!!
domain.secure: - 0 - использовать http 1 - использовать https - при делегировании домена нам установите свой сертификат через Службу Поддержки или попросите настроить Let's Encrypt
domain.http- домен используемый для кастомизации тематических доменов "-" - для тематических доменов если они не указаны полность будет использоваться домен dkim. при проверках дким правильность настройки для domain.http проверяться НЕ будет пусто - для тематических доменов если они не указаны полность будет использоваться домен dkim. при проверках дким правильность настройки для domain.http проверяться БУДЕТ другой домен - для тематических доменов если они не указаны полность будет указаный домен. при проверках дким правильность настройки для него проверяться БУДУТ
domain.link- префикс к domain/domain.http (если без точек) или полный домен для ссылок. пусто - префикс "link", "-" - отключает кастомизацию данного урла
domain.image- префикс к domain/domain.http (если без точек) или полный домен для картинок. пусто - "image", "-" - отключает кастомизацию данного урла
domain.read- префикс к domain/domain.http (если без точек) или полный домен для учёта чтения. пусто - read.sendsay.ru, "-" - отключает кастомизацию данного урла (это поведение отличается от всех прочих !!!)
domain.arch- префикс к domain/domain.http (если без точек) или полный домен для архива выпусков. пусто - если domain.http непусто то префикс "arch" к domain.http иначе равно просто domain; "-" - отключает кастомизацию данного урла
domain.unsub- префикс к domain/domain.http (если без точек) или полный домен для ссылок отписок от подписки и подтверждения подписки. пусто - если domain.http непусто то префикс "unsub" к domain.http иначе равно просто domain; ; "-" - отключает кастомизацию данного урла
domain.rt- префикс к domain/domain.http (если без точек) или полный домен для проксирования ответов на письма выпуска. пусто - префикс "rt", "-" - отключает кастомизацию данного урла
email.mailfrom- префикс к domain (если без@) или полный адрес для MAILFROM. и учитывается long для loggluck. пусто - email@$domain и всегда активен longgluck, '-' - отключает кастомизацию параметра. возможно понадобится domain.email="+"
email.mailfrom.long- если email.mailfrom не пусто, то 1 - он подходит для longgluck
email.fbl- префикс к domain (если без@) или полный адрес для fbl. пусто - *fbl*@$domain, '-' - отключает кастомизацию параметра. возможно понадобится domain.email="+"
Список dkim-ключей¶
{
"action" : "issue.dkim.list"
-- параметры фильтрации, должен быть хотя бы один параметр
--
-- если выбрана последняя порция списка то ответ содержит "last_page" : 1
--
-- доступны поля
--
-- dkim.id -- "идентификатор dkim-ключа"
-- dkim.domain -- "домен"
-- dkim.selector -- "селектор"
-- dkim.onmoderation -- 0|1 -- 0 - dkim-ключ подтверждён, 1 - dkim-ключ ещё не подтверждён
-- dkim.create.date -- дата и время создания Ys
-- dkim.update.date -- дата и время обновления Ys
-- dkim.domain.custom -- 0|1 - домен DKIM используется для кастомизации всех служебных доменов
-- dkim.domain.secure -- 0|1 - при этом используется http:// (0) или https:// (1)
-- dkim.sublogin -- привязан к конкретному пользователю
,"filter" : [ фильтр в синтаксисе stat.uni ]
,"order" : [ сортировка ответа в синтаксисе stat.uni ]
,"skip" : количество пропускаемых записей от начала списка -- по умолчанию 0
,"first" : количество выбираемых записей после skip -- по умолчанию 50, не более 50
}
ответ
{
<общие поля>
,"list" : [
{
"id" : уникальный идентификатор
,"domain" : "домен"
,"selector" : "селектор"
,"onmoderation" : 0|1 -- 0 - dkim-ключ подтверждён, 1 - dkim-ключ ещё не подтверждён
,"create.date" : "дата и время создания" -- Ys, null
,"update.date" : "дата и время последнего изменения" -- Ys, null
,"domain.custom" : 0|1 - домен DKIM используется для кастомизации всех служебных доменов
,"domain.secure" : 0|1 - при этом используется http:// (0) или https:// (1)
}
...
]
}
Чтение dkim-ключа¶
{
"action" : "issue.dkim.get"
-- или
,"id" : идентификатор dkim-ключа
-- или
,"id" : {
"domain" : "домен" -- при использовании интернациональных доменов записывайте их "как есть", без xn-- кодирования
,"selector" : "селектор"
}
}
ответ
{
<общие поля>
"obj" : {
,"id" : "идентификатор dkim-ключа" (или {"domain" : "домен", "selector" : "селектор"})
,"domain" : "домен"
,"selector" : "селектор"
,"public-key" : "публичный ключ"
,'version' : 'DKIM1'
,'key-type' : 'rsa'
,'dns_record' : "<select>._domainkey.<domain> IN TXT \"v=<version>; k=<key_type>; p=<public_key>\""
,"onmoderation" : 0|1 -- 0 - проверка дкима и если есть,кастомной настройки, прошла не удачно. дким и кастомная настройка не действуют
-- 1 - проверки прошли удачно, дким и его настройки действуют
,"domain.custom": 0|1|-1 - 1 - домен делегирован нам для кастомной настройки и дкима
- -1 - клиент сам в меру сил провёл кастомную настройку и дким
,"settings" : { -- настройки которые будут действовать когда проверка пройдёт успешно
"email" : {
"fbl" : "адрес для FBL",
"mailfrom" : "адрес для MAILFROM"
},
"site" : {
"link" : "сайт для учёта кликов",
"unsub" : "сайт для страниц отписки ",
"arch" : "сайт для архива выпусков",
"read" : "сайт для учёта чтений",
"image" : "сайт для хранимых изображений "
},
"domain" : {
"rt" : "домен для проксирования ответов на письма выпуска"
}
-- настройки кастомизации, если заданы
,'domain.secure'
,'domain.http'
,'domain.link'
,'domain.image'
,'domain.read'
,'domain.arch'
,'domain.unsub'
,'domain.rt'
,'domain.email'
,'email.mailfrom'
,'email.mailfrom.long'
,'email.fbl'
}
}
Создание dkim-ключа¶
{
"action" : "issue.dkim.create"
,"obj" : {
"domain" : "домен" -- при использовании интернациональных доменов записывайте их "как есть", без xn-- кодирования
,"sublogin" : "дополнительный логин аккаунта" -- не обязательно. может быть установлено только при работе от основного логина
-- привязка dkim-ключа к дополнительному пользователю
-- при выпуске рассылки дополнительным пользователем аккаунта поиск dkim-ключа
-- для домена будет вначале пытаться найти ключ среди тех dkim-ключей у которых
-- установлен соответствующий sublogin и только если такого не найдётся, то
-- будет осуществлён обычный поиск среди тех dkim-ключей у которых не задан sublogin
-- урлы отправки колбеков для событий из выпусков с этим dkim. позволяет переопределить глобальные настройки. все не обязательны
-- если не пусто заменяет глобальную настройку, но глобальный урл должен быть сконфигурирован чтобы срабатывал этот. не зависит от domain.custom
,"url.callback" : "url" -- общий, если не задан один из специфических. если нет не специфического и тут пусто, то как настроено глобально. не обязательно
,"url.callback.read" : "url"
,"url.callback.click" : "url"
,"url.callback.target" : "url"
,"url.callback.unsub" : "url"
,"url.callback.deliv" : "url"
,"url.callback.form" : "url"
,"url.callback.tracker" : "url"
,"url.callback.confirm" : "url"
,"url.callback.draft" : "url"
,"url.callback.emailreply" : "url"
,"url.callback.promocode" : "url"
}
-- необязательные
,"return_fresh_obj" : "нужно вернуть данные объекта -- да, нет ( 1 | 0 )"
}
ответ
{
<общие поля>
,"obj" { ... } -- объект в формате issue.dkim.get если "return_fresh_obj" : 1
,"id" : идентификатор dkim-ключа
}
Изменение настроек dkim-ключа¶
{
"action" : "issue.dkim.set"
,"id" : "идентификатор dkim-ключа"
,"obj" : { -- не указанные параметры остаются неизменными
,"protected" : 0 | 1
-- урлы отправки колбеков для событий из выпусков с этим dkim. позволяет переопределить глобальные настройки. все не обязательны
-- если не пусто заменяет глобальную настройку, но глобальный урл должен быть сконфигурирован чтобы срабатывал этот. не зависит от domain.custom
,"url.callback" : "url" -- общий, если не задан один из специфических. если нет не специфического и тут пусто, то как настроено глобально
,"url.callback.read" : "url"
,"url.callback.click" : "url"
,"url.callback.target" : "url"
,"url.callback.unsub" : "url"
,"url.callback.deliv" : "url"
,"url.callback.form" : "url"
,"url.callback.tracker" : "url"
,"url.callback.confirm" : "url"
,"url.callback.draft" : "url"
,"url.callback.emailreply" : "url"
,"url.callback.promocode" : "url"
-- настройки кастомизации. изменение любой настройки переводит DKIM в состояние "требуется проверка"
,'domain.custom'
,'domain.secure'
,'domain.http'
,'domain.link'
,'domain.image'
,'domain.read'
,'domain.arch'
,'domain.unsub'
,'domain.rt'
,'domain.email'
,'email.mailfrom'
,'email.mailfrom.long'
,'email.fbl'
}
,"return_fresh_obj": "0|1" -- вернуть объект в формате issue.dkim.get
}
ответ
Удаление dkim-ключа¶
ответ
Проверка настройки dkim-ключа¶
Производится проверка DNS-записи необходимой для использования dkim-ключа - запись
Если домен дополнительно настроен как "делегированный", то проверяются все другие записи DNS необходимые для его использования как делегированного.
При успешной проверке onmoderation становится 0 и ключом можно пользоваться для выпуска рассылок. Иначе onmoderation становится 1 и ключ блокируется.
ответ
{
<общие поля>
-- одно из
"onmoderation" : 0 -- запись успешно проверена
-- одно из
"onmoderation" : 1 -- запись проверить не удалось, использовать нельзя
,"warnings" : [ -- ошибки встреченные при проверке записей
{
"id" : "error/notfound" -- не найдено ни одно записи вообще
}
,{
"id" : "error/value" -- у найденной записи в указанном поле не то значение что ожидается
,"explain" : "имя поля"
,"record" : "значение проверяемой DNS-записи"
}
......
]
}