Опубликовано:

26 сентября 2025

Персонализация рассылок через API

Используя Sendsay Транспорт, вы можете хранить базу контактов со всеми данными в своей системе. При этом данные получателей можно использовать для персонализации писем, передавая необходимую информацию в запросах к API.

Для персонализации из внешних данных можно использовать:

данные, которые связаны с конкретным получателем — например, его имя, фамилию, номер телефона;
общие для всех данные, связанные с группой или сегментом получателей, например, промокоды, предложения или тарифы.

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

Персонализировать письма можно несколькими способами, в зависимости от целей рассылки и того, в каком виде вы храните данные получателей:

Для массовых и транзакционных рассылок через Sendsay API:
- передача email-адресов и реестра с данными персонализации к ним в явном виде в параметре users.list;
- передача общих данных в явном виде внутри параметра extra;
- передача общих данных в файле в шаблоне, в виде функции [% external_extra() %] шаблонизатора;
- передача данных получателей и общих данных через файлы в параметрах external_anketa и external_extra.
Для рассылок через Stream API:
- указание данных в параметре extra с ключом anketa.

Массовые и транзакционные рассылки через Sendsay API

Основная задача Sendsay API — отправка массовых рассылок или небольшого количества транзакционных писем. Для больших объёмов транзакционных рассылок рекомендуем использовать Stream API.

Как протестировать отправку рассылок через Sendsay API

Передача email-адресов и реестра с данными персонализации к ним в явном виде в параметре users.list

Содержимое письма можно взять из шаблона выпуска, а адреса и данные получателей добавить в JSON-массиве в параметр users.list. Этот способ подходит для небольших реестров. Если реестр получателей большой — более оптимальным вариантом будет передать файл с получателями в параметре users.url.

Массовая рассылка
Транзакционная рассылка

{
  "action": "issue.send",
  "group": "masssending",
  "sendwhen": "now",
  "letter": {
    "subject": "тема письма",
    "from.name": "имя отправителя",
    "from.email": "email-адрес отправителя",
    "message": {
      "html": "Привет,[% anketa.personal.firstName %]! Рады сообщить, что у нас скидка на все тарифы!"
    },
    "users.list": [
      {
        "member": {
          "email": "pochta1@gmail.com"
        },
        "personal": {
          "firstName": "Петр",
          "lastName": "Петров"
        }
      },
      {
        "member": {
          "email": "pochta2@gmail.com"
        },
        "personal": {
          "firstName": "Анастасия",
          "lastName": "Егорова"
        }
      }
    ]
  }
}

Если данных для персонализации много, их можно собрать в отдельный файл (JSON или CSV), а файл добавить в ZIP-архив. Ссылку на файл нужно сообщить в запросе в параметре users.url.

Для JSON-файла:

{
  "action": "issue.send",
  "group": "masssending",
  "users.url": "rfs://upload/users.json",
  "relink": "1",
  "letter": {
    "subject": "тема письма",
    "from.name": "имя отправителя",
    "from.email": "email-адрес отправителя",
    "message": {
        "html": "Привет,[% anketa.personal.firstName %]! Рады сообщить, что у нас скидка на все тарифы!"
    }
  }
}

где rfs://upload/users.json — это ссылка на файл с email-адресами и реестром данных персонализации.

Важно

Вместо RFS-хранилища можно использовать и внешний адрес: http(s) или ftp(s).

Файл users.json должен содержать данные получателей в такой структуре:

[
{
  "member": {
    "email": "pochta1@gmail.com"
  },
  "personal": {
    "firstName": "Петр",
    "lastName": "Петров"
  }
},
{
  "member": {
    "email": "pochta2@gmail.com"
  },
  "personal": {
    "firstName": "Анастасия",
    "lastName": "Егорова"
  }
}
]

Для CSV-файла:

{
  "action": "issue.send",
  "group": "masssending",
  "users.url": "rfs://upload/users.csv",
  "letter": {
    "subject": "Тема письма",
    "from.name": "Имя отправителя",
    "from.email": "email-отправителя",
    "message": {
      "html": "Привет, [% anketa.firstName %] [% anketa.lastName %]!"
    }
  }
}

Структура файла:

email;firstName;lastName
pochta1@gmail.com;Петр;Петров
pochta2@gmail.com;Анастасия;Егорова

{
  "action": "issue.send",
  "group": "personal",
  "relink": "1",
  "letter": {
    "subject": "тема письма",
    "from.name": "имя отправителя",
    "from.email": "email-адрес отправителя",
    "message": {
      "html": "Привет, [% anketa.personal.firstName %]! Рады приветствовать в Sendsay"
    }
  },
  "users.list": [
    {
      "member": {
        "email": "pochta1@gmail.com"
      },
      "personal": {
        "firstName": "Петр",
        "lastName": "Петров"
      }
    }
  ]
}

Узнать о других форматах данных при использовании users.list можно в Sendsay API.

Передача общих данных в явном виде внутри параметра extra

Этот вариант подходит для передачи общих данных в запросе, без использования внешнего источника. Данные передаются в параметре extra.

Массовая рассылка
Транзакционная рассылка

{
    "action": "issue.send",
    "sendwhen": "now",
    "group": "masssending",
    "relink": "1",
    "users.url": "rfs://upload/users.json",
    "letter": {
        "subject": "тема письма",
        "from.name": "имя отправителя",
        "from.email": "email-адрес отправителя",
        "message": {
            "html": "Привет, [% anketa.personal.firstName %]! Рады сообщить, что у нас январская скидка [% Discount.january %] на все тарифы!"
        }
    },
    "extra": {
        {
            "Discount": {
                "january": "15%",
                "june": "10%",
                "october": "30%"
            }
        }
    }
}

где rfs://upload/users.json — это файл с email-адресами и реестром данных персонализации.

Файл users.json должен содержать данные получателей в такой структуре:

[
{
  "member": {
    "email": "pochta1@gmail.com"
  },
  "personal": {
    "firstName": "Петр",
    "lastName": "Петров"
  }
},
{
  "member": {
    "email": "pochta2@gmail.com"
  },
  "personal": {
    "firstName": "Анастасия",
    "lastName": "Егорова"
  }
}
]

{
  "action": "issue.send",
  "group": "personal",
  "email": "email-адрес получателя",
  "relink": "1",
  "letter": {
    "subject": "тема письма",
    "from.name": "имя отправителя",
    "from.email": "email-адрес отправителя",
      "message": {
        "html": "Привет, [% FirstName %]! Рады приветствовать в Sendsay"
    }
  },
	"extra": {
		"FirstName": "Петр"
	}
}

где extra — данные персонализации, которые нужно показать в письме.

Подробнее про параметр extra можно узнать в Sendsay API.

Передача общих данных в файле в шаблоне, в виде функции шаблонизатора

В этом варианте в письме используется функция шаблонизатора:

[% external_extra() %]

В параметрах функции указывается URL, который должен вернуть JSON с данными персонализации (по адресу может находиться файл или API-эндпоинт).

Массовая рассылка
Транзакционная рассылка

{
    "action": "issue.send",
    "sendwhen": "now",
    "group": "masssending",
    "relink": "1",
    "users.url": "rfs://upload/users.json",
    "letter": {
        "subject": "тема письма",
        "from.name": "имя отправителя",
        "from.email": "email-адрес отправителя",
        "message": {
            "html": "Привет, [% anketa.base.firstName %]! Рады сообщить, что у нас январская скидка [% Discount.january %] [% external_extra(\"rfs://upload/discount.json\",\"method\",\"get\",\"ignore_error\",\"1\",\"format",\"json\") %] на все тарифы!"
        }
    }
}

где rfs://upload/discount.json — это адрес файла с общими данными получателей. Содержимое файла:

{
  "Discount": {
    "january": "15%",
    "june": "10%",
    "october": "30%"
  }
}

а rfs://upload/users.json — адрес файла с получателями и данными персонализации. Структура данных в файле:

[
{
  "member": {
    "email": "pochta1@gmail.com"
  },
  "personal": {
    "firstName": "Петр",
    "lastName": "Петров"
  }
},
{
  "member": {
    "email": "pochta2@gmail.com"
  },
  "personal": {
    "firstName": "Анастасия",
    "lastName": "Егорова"
  }
}
]

{
  "action": "issue.send",
  "group": "personal",
  "email": "pochta1@gmail.com",
  "relink": "1",
  "letter": {
    "subject": "тема письма",
    "from.name": "имя отправителя",
    "from.email": "email-адрес отправителя",
    "message": {
      "html": "Привет, [% Data.name %] [% external_extra(\"rfs://upload/userdata.json\",\"method\",\"get\",\"ignore_error\",\"1\",\"timeout\",\"3\") %]! Рады приветствовать в Sendsay"
    }
  }
}

где rfs://upload/userdata.json — адрес файла с данными. Содержимое файла:

{
    "Data": {
        "name": "Петр"
    }
}

Передача данных получателей и общих данных в файлах

В этом варианте персональные данные каждого получателя передаются в отдельном JSON-файле, ссылка на который указывается в параметре external_anketa внутри extra. Письмо не содержит информацию о конкретных данных пользователей — они подставляются автоматически при рассылке.

Если нужно добавить общие данные для всех писем (например, скидки или акции), их можно указывать через параметр external_extra в том же объекте extra.

Массовая рассылка
Транзакционная рассылка

{
    "action": "issue.send",
    "sendwhen": "now",
    "group": "masssending",
    "relink": "1",
    "letter": {
        "subject": "тема письма",
        "from.name": "имя отправителя",
        "from.email": "email-адрес отправителя",
        "message": {
            "html": "Привет, [% anketa.base.firstName %]! Рады сообщить, что у нас январская скидка [% Discount.january %] на все тарифы!"
        }
    },
    "extra": {
        "external_extra": [
            {
                "url": "rfs://upload/discount.json",
                "method": "get"
            }
        ],
        "external_anketa": [
            {
                "url": "rfs://upload/users.json",
                "method": "get"
            }
        ]
    }
}

где rfs://upload/discount.json — это адрес файла с общими данными. Содержимое файла:

{
  "Discount": {
    "january": "15%",
    "june": "10%",
    "october": "30%"
  }
}

а rfs://upload/users.json — адрес файла с получателями и данными персонализации. Структура данных в файле:

{
  "member": {
    "email": "pochta1@gmail.com"
  },
  "personal": {
    "firstName": "Петр",
    "lastName": "Петров"
  }
},
{
  "member": {
    "email": "pochta2@gmail.com"
  },
  "personal": {
    "firstName": "Анастасия",
    "lastName": "Егорова"
  }
}

{
    "action": "issue.send",
    "group": "personal",
    "email": "pochta1@gmail.com",
    "relink": "1",
    "letter": {
        "subject": "тема письма",
        "from.name": "имя отправителя",
        "from.email": "email-адрес отправителя",
        "message": {
            "html": "Привет, [% anketa.base.firstName %]! Рады приветствовать в Sendsay"
        }
    },
    "extra": {
        "external_anketa": [
            {
                "url": "rfs://upload/userdata.json",
                "method": "get"
            }
        ]
    }
}

где rfs://upload/userdata.json — адрес файла с данными. Содержимое файла:

{
    "Data": {
        "name": "Петр"
    }
}

Подробнее про параметр external_extra можно узнать в Sendsay API.

Рассылки через Stream API

Stream API позволяет передавать по одному письму в одном запросе, если нет возможности передать задание с полным реестром.

Как протестировать отправку рассылок через Stream API

Указание данных в параметре extra с ключом anketa

{
    "apikey": "ваш API-ключ",
    "action": "issue.send",
    "group": "personal",
    "relink": "1",
    "email": "email-адрес получателя",
    "dkim.id": "идентификатор DKIM для подписи письма",
    "letter": {
        "subject": "тема письма",
        "from.name": "имя отправителя",
        "from.email": "email-адрес отправителя",
        "message": {
            "html": "Привет, [% anketa.firstName %]! Рады сообщить, что у нас январская скидка [% anketa.discount %] на все тарифы!"
        }
    },
    "extra": {
      "anketa": {
        "firstName": "Петр",
        "discount": "15%",
        }
    }
}

где extra.anketa — данные персонализации, которые нужно показать в письме. Для подготовки запроса вам понадобится API-ключ.

Как получить API-ключ

Читайте также:
Шаблоны популярных запросов к API

Массовые и транзакционные рассылки через Sendsay API​

Передача email-адресов и реестра с данными персонализации к ним в явном виде в параметре users.list​

Передача общих данных в явном виде внутри параметра extra​

Передача общих данных в файле в шаблоне, в виде функции шаблонизатора​

Передача данных получателей и общих данных в файлах​

Рассылки через Stream API​

Указание данных в параметре extra с ключом anketa​