Справка › Для разработчиков
API отправки
Отправляйте письма из своих приложений и сайтов, со своих адресов и по своим шаблонам.
Ваши приложения, сайты и скрипты могут отправлять письма с адресов вашей организации одним HTTPS-запросом: подтверждения заказов, сброс паролей, формы обратной связи, отчёты. Письма уходят так же, как те, что вы пишете в SendHaste.
| Запрос | Что делает |
|---|---|
POST https://sendhaste.com/api/v1/emails | Отправляет одно письмо: ваш собственный текст или один из ваших шаблонов со значениями. |
GET https://sendhaste.com/api/v1/templates | Возвращает письма, подключённые к шаблонам, и значения, которые использует каждое. |
GET https://sendhaste.com/api/v1/senders | Перечисляет адреса, с которых ключ может отправлять. |
GET https://sendhaste.com/api/v1/openapi.json | Весь API в виде файла OpenAPI 3.1 — для Postman, генераторов кода и других инструментов разработчика. Ключ не нужен. |
1. Создайте API-ключ
- Главный администратор организации открывает Настройки → API-ключи.
- Нажмите Создать API-ключ, дайте ключу название (например, Форма обратной связи на сайте) и в поле Отправляет с выберите любой адрес на ваших доменах, любой адрес на одном домене или только один адрес. Нажмите Создать ключ.
- В окне показан новый ключ, его название и адрес, с которого он отправляет. Нажмите Копировать, затем Готово. Ключ начинается с
sh_и показывается только один раз: если он потерян, отзовите его и создайте новый.
Для автоматических писем с одного домена (подтверждения заказов, оповещения, отчёты) откройте Настройки → Домены, выберите домен и нажмите Создать API-ключ для yourdomain.com: ключ сможет отправлять с любого адреса на этом домене и ни с какого другого. Сначала добавьте почтовый ящик для адреса отправителя, например noreply@yourdomain.com. Ограничен только отправитель: письма можно отправлять кому угодно, в вашей компании или за её пределами.
Храните ключ на своём сервере, в настройке или переменной окружения. Никогда не размещайте его на веб-странице, в мобильном приложении или в публичном репозитории кода: любой, у кого он есть, может отправлять письма от вашего имени. Если ключ утёк, нажмите Отозвать: он сразу перестанет работать.
2. Отправьте письмо
Отправьте запрос POST на https://sendhaste.com/api/v1/emails с ключом в заголовке Authorization: Bearer sh_… и письмом в формате JSON:
curl https://sendhaste.com/api/v1/emails \
-H "Authorization: Bearer sh_your_key" \
-H "Content-Type: application/json" \
-d '{
"from": "Your Company <info@yourcompany.com>",
"to": ["client@example.com"],
"subject": "Your booking is confirmed",
"html": "<p>Thank you! See you on <b>Monday</b>.</p>",
"text": "Thank you! See you on Monday."
}'const res = await fetch("https://sendhaste.com/api/v1/emails", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.SENDHASTE_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
from: "Your Company <info@yourcompany.com>",
to: "client@example.com",
subject: "Your booking is confirmed",
text: "Thank you! See you on Monday.",
}),
});
const result = await res.json(); // { id, from, to, recipients } or { error: { code, message } }3. Отправка ваших шаблонов
Вместо того чтобы писать письмо в коде, создайте его один раз в разделе Шаблоны, а сайт будет отправлять его по имени: приветствие, сброс пароля, подтверждение заказа. Чтобы позже изменить письмо, отредактируйте шаблон или подключите имя к другому — на сайте ничего менять не нужно.
- В разделе Шаблоны создайте письмо. Там, где должно быть значение от сайта, введите
{{params.first_name}}; после черты — что использовать, если его нет:{{params.first_name|there}}. Работает в теме, в тексте и в адресах кнопок и ссылок. - Org Super Admin открывает Настройки → API-ключи, в разделе Письма с ваших сайтов нажимает Подключить письмо, вводит Имя письма (например,
welcome), выбирает Шаблон, в поле Отправляется с выбирает все адреса ваших доменов, один домен или один адрес и нажимает Подключить. - В разделе Отправить тест отправьте его себе с какими-нибудь значениями, чтобы увидеть результат.
- Сайт отправляет
templateс именем иparamsсо значениями. Используется тема шаблона, если вы не передаётеsubject.
curl https://sendhaste.com/api/v1/emails \
-H "Authorization: Bearer sh_your_key" \
-H "Content-Type: application/json" \
-d '{
"from": "Your Shop <hello@yourshop.com>",
"to": "aysel@example.com",
"template": "welcome",
"params": { "first_name": "Aysel", "verify_url": "https://yourshop.com/verify?t=8f2c" }
}'- Встроенные теги тоже работают:
{{first_name}},{{name}},{{company}},{{email}}.{{email}}— первый адрес в «Кому»; имена берутся изparams, если вы их передаёте, иначе из контакта в SendHaste. - Значения вставляются как текст: HTML в значении показывается как есть, а ссылка должна начинаться с https://, http:// или mailto:.
- Значение без запасного варианта остаётся пустым, поэтому сначала проверьте через Отправить тест.
Пример: приветственное письмо новым пользователям
- Создайте шаблон Welcome с темой
Welcome, {{params.first_name|there}}!, заголовкомHi {{params.first_name|there}}и кнопкой со ссылкой{{params.verify_url}}. - Подключите его как
welcomeв Настройки → API-ключи и создайте ключ, который отправляет с вашего адреса. - Сохраните ключ в настройках сайта (например, в переменной окружения
SENDHASTE_API_KEY). - Там, где сайт сохраняет нового пользователя, отправьте запрос. Выберите язык:
await fetch("https://sendhaste.com/api/v1/emails", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.SENDHASTE_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({
from: "Your Shop <hello@yourshop.com>",
to: user.email,
template: "welcome",
params: { first_name: user.firstName, verify_url: verifyUrl },
}),
});$ch = curl_init("https://sendhaste.com/api/v1/emails");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SENDHASTE_API_KEY"), "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode([
"from" => "Your Shop <hello@yourshop.com>",
"to" => $user["email"],
"template" => "welcome",
"params" => ["first_name" => $user["first_name"], "verify_url" => $verifyUrl],
]),
]);
$result = json_decode(curl_exec($ch), true);import os, requests
requests.post(
"https://sendhaste.com/api/v1/emails",
headers={"Authorization": f"Bearer {os.environ['SENDHASTE_API_KEY']}"},
json={
"from": "Your Shop <hello@yourshop.com>",
"to": user.email,
"template": "welcome",
"params": {"first_name": user.first_name, "verify_url": verify_url},
},
timeout=10,
)Отправляйте после сохранения пользователя и не останавливайте регистрацию из-за ошибки письма: запишите ошибку и продолжайте. id из ответа поможет нам найти письмо, если вы нам напишете.
Список ваших шаблонов
GET https://sendhaste.com/api/v1/templates с тем же ключом возвращает письма, подключённые в Настройки → API-ключи, и значения, которые использует каждое:
{"data": [{"name": "welcome", "template_name": "Welcome", "subject": "Welcome, {{params.first_name|there}}!", "params": ["first_name", "verify_url"], "updated_at": "…", "scope": "domain", "for": "yourshop.com"}]}| Поле | Что это |
|---|---|
name | Что передавать в template. |
template_name | Название шаблона в SendHaste. |
subject | Тема шаблона, теги ещё не заполнены. |
params | Имена {{params.…}}, которые использует шаблон: передавайте их в params. |
updated_at | Когда шаблон менялся в последний раз. |
scope | Для кого подключено: organization (все адреса ваших доменов), domain или address. |
for | Домен или адрес, для которого оно подключено; null — для всей организации. |
Ваш код может вызывать это при запуске или в тесте, чтобы проверить, что каждое отправляемое письмо подключено и получает все свои значения.
Каждое письмо подключается для всех адресов ваших доменов, для одного домена или для одного адреса (Отправляется с). Ключ показывает и отправляет только письма для адресов, с которых он может отправлять, поэтому сайты на разных доменах видят каждый свои. Одно имя можно подключить на каждом уровне: письмо с info@yourshop.com использует подключённое для этого адреса, иначе — для его домена, иначе — для организации.
Список ваших адресов
GET https://sendhaste.com/api/v1/senders с тем же ключом возвращает адреса, с которых он может отправлять. Используйте его, чтобы люди выбирали адрес отправителя, а не прописывали его в коде.
{"data": [{"address": "info@yourcompany.com"}, {"address": "noreply@yourcompany.com"}], "domains": [{"domain": "yourcompany.com"}]}| Поле | Что это |
|---|---|
data | Все адреса с почтовым ящиком, с которых ключ может отправлять: единственный адрес, для которого он создан, все ящики на его домене или все ящики на ваших доменах. |
domains | Домены, с которых ключ может отправлять. Пусто для ключа, созданного для одного адреса. |
Каждому адресу отправителя нужен собственный почтовый ящик в SendHaste. Адрес, добавленный к ящику в разделе Также получает, использовать нельзя, как и catchall@. Для адреса только для отправки, например noreply@yourdomain.com, добавьте для него ящик в Настройки → Домены; он сразу появится в data.
Поля
| Поле | Обязательно | Что это |
|---|---|---|
from | да | Один из ваших адресов, при желании с именем: Your Company <info@yourcompany.com>. У него должен быть ящик в SendHaste. |
to | да | Адрес или список адресов. |
cc, bcc | нет | Адрес или список. Получатели скрытой копии (bcc) не видны остальным. |
reply_to | нет | Куда приходят ответы, если не на адрес From. |
subject | да, если нет template | Тема письма. С шаблоном заменяет тему шаблона. |
text | text или html | Версия обычным текстом. |
html | text или html | HTML-версия. По возможности отправляйте обе; если есть только HTML, текстовая версия создаётся из неё. |
attachments | нет | Список файлов: filename, content, content_type. Содержимое закодировано в base64. |
template | нет | Имя письма, подключённого в Настройки → API-ключи, например welcome. Вместо text и html. |
params | нет | С шаблоном: значения для его тегов {{params.…}}, например {"first_name": "Aysel"}. До 100 значений. |
Ответ
Когда письмо отправлено: статус 200 и {"id": "…", "from": "info@yourcompany.com", "to": ["client@example.com"], "recipients": 1, "status": "sent"}. С шаблоном — ещё "template": "welcome".
Когда сегодняшний дневной лимит исчерпан, а в завтрашнем ещё есть место: статус 202 и те же поля плюс "status": "queued", "deliverAfter": "2026-10-13T00:00:00Z". Письмо принято, и SendHaste сохраняет его; оно уйдёт в deliverAfter (ближайшая полночь UTC) или сразу после, как только почтовый сервер его примет. Считайте 202 успехом и не отправляйте письмо снова: повтор доставил бы его дважды.
Если нет: статус ошибки и {"error": {"code": "…", "message": "…"}}. Значение code не меняется, поэтому ваш код может его проверять; сообщение говорит, что исправить.
| Статус | code | Что делать |
|---|---|---|
401 | missing_api_key, invalid_api_key | Проверьте заголовок Authorization или создайте новый ключ: этот ключ отозван. |
403 | from_not_allowed | Отправляйте с адреса на ваших доменах (кроме catchall@, который только принимает почту), или с того домена или единственного адреса, которым ограничен ключ. |
403 | api_disabled | Отправка через API для вашей организации не включена: попросите нас на странице «Поддержка». |
400 | invalid_json | Отправьте объект JSON. |
415 | unsupported_media_type | Укажите Content-Type: application/json. |
422 | invalid_field, mailbox_not_found | Исправьте поле, указанное в сообщении, или сначала создайте ящик для адреса From. |
404 | template_not_found | Подключите имя письма к шаблону в Настройки → API-ключи — для адреса From, его домена или всей организации — или проверьте написание. |
413 | too_large | Отправляйте вложения меньшего размера. |
429 | rate_limited, daily_limit | Слишком много запросов: подождите столько секунд, сколько указано в заголовке Retry-After. Дневной лимит: письма на сегодня и на завтра уже исчерпаны или исчерпан дневной лимит почтового сервера для этого адреса; подождите столько секунд, сколько указано в Retry-After (до полуночи UTC), и отправьте тогда. |
502, 503 | send_failed, mailbox_not_ready | Не отправлено: попробуйте снова через несколько минут. Если повторяется, напишите нам. На письмо, которое почтовый сервер принял, такой ответ не приходит никогда, даже если сервер отвечал долго. |
Лимиты
- До 60 запросов в минуту на ключ.
- До 50 получателей на письмо (to, cc и bcc вместе).
- До 20 вложений и 25 МБ на письмо.
- Каждый домен может отправлять до 300 писем в день, будь то из SendHaste или через API, а каждый его ящик — писать стольким людям, каков лимит домена, или меньшему числу, если Главный администратор организации задаст Сколько людям каждый ящик может писать в день на странице домена. У недавно подключённого домена лимит сначала ниже; его страница в Настройки → Домены показывает Писем сегодня относительно лимита, Отклонено сегодня, Задержано до завтра и отметку Прогрев, пока лимит растёт.
- Письмо сверх сегодняшнего лимита не теряется: SendHaste сохраняет его и отправляет после полуночи UTC, засчитывая в завтрашний лимит (статус
202). Если почтовый сервер к тому времени ещё упирается в свой лимит, письмо уйдёт, как только сервер его примет. Отказ (daily_limit) приходит только тогда, когда исчерпан и завтрашний лимит. - Такие письма видны в боковой панели ящика в разделе Запланированные, под заголовком Задержано дневным лимитом отправки; делать ничего не нужно, они уйдут сами.
Предпочитаете SMTP? Многие приложения и фреймворки могут вместо этого отправлять письма через ящик по SMTP: сервер и порт указаны в разделе Outlook, Apple Mail и приложения на телефоне. Действуют те же дневные лимиты.
Не нашли ответ? Напишите нам.