Справка › Для разработчиков

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-ключ

  1. Главный администратор организации открывает Настройки → API-ключи.
  2. Нажмите Создать API-ключ, дайте ключу название (например, Форма обратной связи на сайте) и в поле Отправляет с выберите любой адрес на ваших доменах, любой адрес на одном домене или только один адрес. Нажмите Создать ключ.
  3. В окне показан новый ключ, его название и адрес, с которого он отправляет. Нажмите Копировать, затем Готово. Ключ начинается с sh_ и показывается только один раз: если он потерян, отзовите его и создайте новый.

Для автоматических писем с одного домена (подтверждения заказов, оповещения, отчёты) откройте Настройки → Домены, выберите домен и нажмите Создать API-ключ для yourdomain.com: ключ сможет отправлять с любого адреса на этом домене и ни с какого другого. Сначала добавьте почтовый ящик для адреса отправителя, например noreply@yourdomain.com. Ограничен только отправитель: письма можно отправлять кому угодно, в вашей компании или за её пределами.

Храните ключ на своём сервере, в настройке или переменной окружения. Никогда не размещайте его на веб-странице, в мобильном приложении или в публичном репозитории кода: любой, у кого он есть, может отправлять письма от вашего имени. Если ключ утёк, нажмите Отозвать: он сразу перестанет работать.

2. Отправьте письмо

Отправьте запрос POST на https://sendhaste.com/api/v1/emails с ключом в заголовке Authorization: Bearer sh_… и письмом в формате JSON:

curl
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."
  }'
JavaScript (Node.js 18+)
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. Отправка ваших шаблонов

Вместо того чтобы писать письмо в коде, создайте его один раз в разделе Шаблоны, а сайт будет отправлять его по имени: приветствие, сброс пароля, подтверждение заказа. Чтобы позже изменить письмо, отредактируйте шаблон или подключите имя к другому — на сайте ничего менять не нужно.

  1. В разделе Шаблоны создайте письмо. Там, где должно быть значение от сайта, введите {{params.first_name}}; после черты — что использовать, если его нет: {{params.first_name|there}}. Работает в теме, в тексте и в адресах кнопок и ссылок.
  2. Org Super Admin открывает Настройки → API-ключи, в разделе Письма с ваших сайтов нажимает Подключить письмо, вводит Имя письма (например, welcome), выбирает Шаблон, в поле Отправляется с выбирает все адреса ваших доменов, один домен или один адрес и нажимает Подключить.
  3. В разделе Отправить тест отправьте его себе с какими-нибудь значениями, чтобы увидеть результат.
  4. Сайт отправляет template с именем и params со значениями. Используется тема шаблона, если вы не передаёте subject.
curl
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:.
  • Значение без запасного варианта остаётся пустым, поэтому сначала проверьте через Отправить тест.

Пример: приветственное письмо новым пользователям

  1. Создайте шаблон Welcome с темой Welcome, {{params.first_name|there}}!, заголовком Hi {{params.first_name|there}} и кнопкой со ссылкой {{params.verify_url}}.
  2. Подключите его как welcome в Настройки → API-ключи и создайте ключ, который отправляет с вашего адреса.
  3. Сохраните ключ в настройках сайта (например, в переменной окружения SENDHASTE_API_KEY).
  4. Там, где сайт сохраняет нового пользователя, отправьте запрос. Выберите язык:
JavaScript (Node.js 18+)
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 },
  }),
});
PHP
$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);
Python
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-ключи, и значения, которые использует каждое:

JSON
{"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 с тем же ключом возвращает адреса, с которых он может отправлять. Используйте его, чтобы люди выбирали адрес отправителя, а не прописывали его в коде.

JSON
{"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Тема письма. С шаблоном заменяет тему шаблона.
texttext или htmlВерсия обычным текстом.
htmltext или htmlHTML-версия. По возможности отправляйте обе; если есть только 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Что делать
401missing_api_key, invalid_api_keyПроверьте заголовок Authorization или создайте новый ключ: этот ключ отозван.
403from_not_allowedОтправляйте с адреса на ваших доменах (кроме catchall@, который только принимает почту), или с того домена или единственного адреса, которым ограничен ключ.
403api_disabledОтправка через API для вашей организации не включена: попросите нас на странице «Поддержка».
400invalid_jsonОтправьте объект JSON.
415unsupported_media_typeУкажите Content-Type: application/json.
422invalid_field, mailbox_not_foundИсправьте поле, указанное в сообщении, или сначала создайте ящик для адреса From.
404template_not_foundПодключите имя письма к шаблону в Настройки → API-ключи — для адреса From, его домена или всей организации — или проверьте написание.
413too_largeОтправляйте вложения меньшего размера.
429rate_limited, daily_limitСлишком много запросов: подождите столько секунд, сколько указано в заголовке Retry-After. Дневной лимит: письма на сегодня и на завтра уже исчерпаны или исчерпан дневной лимит почтового сервера для этого адреса; подождите столько секунд, сколько указано в Retry-After (до полуночи UTC), и отправьте тогда.
502, 503send_failed, mailbox_not_readyНе отправлено: попробуйте снова через несколько минут. Если повторяется, напишите нам. На письмо, которое почтовый сервер принял, такой ответ не приходит никогда, даже если сервер отвечал долго.

Лимиты

  • До 60 запросов в минуту на ключ.
  • До 50 получателей на письмо (to, cc и bcc вместе).
  • До 20 вложений и 25 МБ на письмо.
  • Каждый домен может отправлять до 300 писем в день, будь то из SendHaste или через API, а каждый его ящик — писать стольким людям, каков лимит домена, или меньшему числу, если Главный администратор организации задаст Сколько людям каждый ящик может писать в день на странице домена. У недавно подключённого домена лимит сначала ниже; его страница в Настройки → Домены показывает Писем сегодня относительно лимита, Отклонено сегодня, Задержано до завтра и отметку Прогрев, пока лимит растёт.
  • Письмо сверх сегодняшнего лимита не теряется: SendHaste сохраняет его и отправляет после полуночи UTC, засчитывая в завтрашний лимит (статус 202). Если почтовый сервер к тому времени ещё упирается в свой лимит, письмо уйдёт, как только сервер его примет. Отказ (daily_limit) приходит только тогда, когда исчерпан и завтрашний лимит.
  • Такие письма видны в боковой панели ящика в разделе Запланированные, под заголовком Задержано дневным лимитом отправки; делать ничего не нужно, они уйдут сами.

Предпочитаете SMTP? Многие приложения и фреймворки могут вместо этого отправлять письма через ящик по SMTP: сервер и порт указаны в разделе Outlook, Apple Mail и приложения на телефоне. Действуют те же дневные лимиты.

Не нашли ответ? Напишите нам.