Документация Email API

Создание API ключа

Создание API ключа доступно по ссылке: https://beta.rusender.ru/api.

Подробную информацию о создании API ключа можно прочитать в нашей Базе знаний.

Важно: тестовые письма необходимо слать только на существующие email адреса, иначе ключ будет забанен.

Роут отправки письма (с готовым HTML)

POST `/v1/external-mails/send`

В заголовке «X-Api-Key» необходимо передать строкой ключ API для аутентификации.

Отправка письма с HTML/текстовым содержимым. Необходимо указать хотя бы одно из полей html или text.

Пример тела запроса

{
  "mail": {
    "to": {
      "email": "recipient@example.com",
      "name": "Recipient Name"
    },
    "from": {
      "email": "sender@example.com",
      "name": "Sender Name"
    },
    "subject": "Тема письма",
    "html": "<h1>Привет!</h1><p>Содержимое письма</p>",
    "text": "Привет! Содержимое письма",
    "previewTitle": "Прехедер письма",
    "headers": {},
    "cc": "copy1@example.com,copy2@example.com",
    "bcc": "hidden@example.com",
    "attachments": [{ "document.pdf": "<base64-encoded content>" }, { "image.png": "<base64-encoded content>" }]
  },
  "idempotencyKey": "unique-key-123"
}

Отправка письма с использованием шаблона RuSender

POST `/v1/external-mails/send-by-template`

В заголовке «X-Api-Key» передать строкой ключ API для аутентификации.

Отправка письма по шаблону. Вместо html/text указывается idTemplateMailUser и params.

Пример тела запроса

{
  "mail": {
    "to": {
      "email": "recipient@example.com",
      "name": "Recipient Name"
    },
    "from": {
      "email": "sender@example.com",
      "name": "Sender Name"
    },
    "subject": "Тема письма",
    "idTemplateMailUser": 42,
    "params": {
      "firstName": "Name",
      "orderNumber": 12345
    },
    "previewTitle": "Прехедер письма",
    "headers": {},
    "cc": "copy@example.com",
    "bcc": "hidden@example.com",
    "attachments": [{ "document.pdf": "<base64-encoded content>" }]
  },
  "idempotencyKey": "unique-key-456"

Описание полей

Поле	Тип	Обязательное	Описание
`mail.to.email`	`string (email)`	да	Email получателя
`mail.to.name`	`string`	нет	Имя получателя
`mail.from.email`	`string (email)`	да	Email отправителя
`mail.from.name`	`string`	нет	Имя отправителя
`mail.subject`	`string`	да	Тема письма
`mail.html`	`string`	да*	HTML-содержимое письма
`mail.text`	`string`	да*	Текстовое содержимое письма
`mail.idTemplateMailUser`	`number`	да**	ID шаблона
`mail.params`	`object`	нет**	Параметры подстановки в шаблон
`mail.previewTitle`	`string`	нет	Прехедер письма
`mail.headers`	`object`	нет	Дополнительные заголовки письма
`mail.cc`	`string`	нет	Копия — email через запятую
`mail.bcc`	`string`	нет	Скрытая копия — email через запятую
`mail.attachments`	`array`	нет	Вложения (макс. 20 шт.). Каждый элемент — объект `{ "имя_файла": "base64" }`
`idempotencyKey`	`string`	нет	Ключ идемпотентности. Если не указан — в ответе будет warning

* Для /v1/external-mails/send необходимо указать хотя бы одно из полей html или text.

** Для /v1/external-mails/send-by-template необходимо указать idTemplateMailUser и params если такие есть в шаблоне.

Возможные ответы сервера

200 OK — Успешная отправка

Письмо принято в обработку.

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "additionalRecipients": [
    { "uuid": "661e8400-e29b-41d4-a716-446655440001" },
    { "error": "Invalid email \"bad-email\" — does not conform to RFC 5322 or RFC 6854 formatting standards." }
  ],
  "warning": "Idempotency key not provided."
}

Поле	Тип	Описание
`uuid`	`string (uuid)`	UUID отправленного письма
`additionalRecipients`	`array`	Массив результатов для дополнительных получателей (cc/bcc). Каждый элемент — либо `{ uuid }` (успех), либо `{ error }` (невалидный email)
`warning`	`string \ undefined`	Предупреждение. Возвращается `"Idempotency key not provided."`, если не передан `idempotencyKey`

400 Bad Request — Ошибка валидации

Возникает при невалидном теле запроса или при ошибках вложений.

{
  "message": "Attachments size more than allowed",
  "statusCode": 400
}

Возможные причины:

Сообщение	Описание
`Attachments parse failed`	Вложения не удалось распарсить (невалидный base64 и т.д.)
`Attachments size more than allowed`	Суммарный размер вложений превышает допустимый лимит
`Attachments type forbidden`	Тип файла вложения запрещён
`HTML template is not valid`	HTML-шаблон невалиден (для `/send-by-template`)

401 Unauthorized — Невалидный API-ключ

API-ключ не прошёл проверку (невалидный ключ).

{
  "message": "Invalid API key",
  "statusCode": 401
}

402 Payment Required — Недостаточно средств

На балансе пользователя недостаточно ресурсов для отправки письма.

{
  "message": "Is not enough resource on user balance",
  "statusCode": 402
}

403 Forbidden — API-ключ не активен

API-ключ найден, но деактивирован.

{
  "message": "API key is not active",
  "statusCode": 403
}

404 Not Found — Ресурс не найден

Один из необходимых ресурсов не найден.

{
  "message": "ExternalMailApiKey not found",
  "statusCode": 404
}

Возможные варианты сообщений:

Сообщение	Описание
`ExternalMailApiKey not found`	API-ключ с указанным идентификатором не существует
`User Domain not found`	Домен отправителя не найден / не привязан к пользователю
`TemplateMailUser not found by id`	Шаблон письма не найден (для `/send-by-template`)
`MailUuid not found`	Внутренняя ошибка — UUID письма не найден

{
  "message": "ExternalMailApiKey not found",
  "statusCode": 404
}

422 Unprocessable Entity — Получатель недоступен

Письмо не может быть доставлено данному получателю.

{
  "message": "Email receiver doesn't exist",
  "statusCode": 422
}

Возможные варианты:

Сообщение	Описание
`Email receiver unsubscribed from this API key mails`	Получатель отписался от рассылок данного API-ключа
`Email receiver complained from this API key mails`	Получатель пожаловался на рассылки данного API-ключа
`Email receiver doesn't exist`	Email получателя не существует (hard bounce)
`Email receiver unavailable`	Email получателя временно недоступен (soft bounce)
`Template not found by templateId`	Шаблон письма не найден (для `/send-by-template`)

500 Internal Server Error — Внутренняя ошибка сервера

Непредвиденная ошибка на стороне сервера.

{
  "message": "Internal Server Error",
  "statusCode": 500
}

503 Service Unavailable — Сервис недоступен

Сервис обработки писем временно недоступен.

{
  "message": "Service unavailable",
  "statusCode": 503
}

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

PHP

$url = 'https://api.rusender.ru/api/v1/external-mails/send';
$data = array(
   'idempotencyKey' => 'unique-key-string',
   'mail' => array(
       'to' => array(
           'email' => 'user@example.com',
           'name' => 'string'
       ),
       'from' => array(
           'email' => 'user@example.com',
           'name' => 'string'
       ),
       'subject' => 'string',
       'previewTitle' => 'string',
       'html' => 'string'
   )
);
$headers = array(
   'Content-Type' => 'application/json',
   'X-Api-Key' => 'YOUR_API_KEY'
);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

Python

import requests
import json
url = 'https://api.rusender.ru/api/v1/external-mails/send'
data = {
    'idempotencyKey': 'unique-key-string',
    'mail': {
        'to': {
            'email': 'user@example.com',
            'name': 'string'
        },
        'from': {
            'email': 'user@example.com',
            'name': 'string'
        },
        'subject': 'string',
        'previewTitle': 'string',
        'html': 'string'
    }
}
headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
}
response = requests.post(url, json=data, headers=headers)

Node.js

const axios = require('axios');
const url = 'https://api.rusender.ru/api/v1/external-mails/send';
const data = {
    idempotencyKey: 'unique-key-string',
    mail: {
        to: {
            email: 'user@example.com',
            name : 'string'
        },
        from: {
            email: 'user@example.com',
            name: 'string'
        },
        subject: 'string',
        previewTitle: 'string',
        html: 'string'
    }
};
const headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
};
axios.post(url, data, { headers })
    .then(response => {
        // Обработка ответа API
    })
    .catch(error => {
        // Обработка ошибки
    });

JavaScript

const url = 'https://api.rusender.ru/api/v1/external-mails/send';
const data = {
    idempotencyKey: 'unique-key-string',
    mail: {
        to: {
            email: 'user@example.com',
            name: 'string'
        },
        from: {
            email: 'user@example.com',
            name: 'string'
        },
        subject: 'string',
        previewTitle: 'string',
        html: 'string'
        }
    };
const headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
};
fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
    .then(response => response.json())
    .then(data => {
        // Обработка ответа API
    })
    .catch(error => {
        // Обработка ошибки
    });

Примеры использования API с шаблоном письма RuSender

PHP

$url = 'https://api.rusender.ru/api/v1/external-mails/send-by-template';
$data = array(
   'idempotencyKey' => 'unique-key-string',
   'mail' => array(
       'to' => array(
           'email' => 'user@example.com',
           'name' => 'string'
       ),
       'from' => array(
           'email' => 'user@example.com',
           'name' => 'string'
       ),
       'subject' => 'string',
       'previewTitle' => 'string',
       'idTemplateMailUser' => number,
       'params' => array(
           'test' => 'string',
           'test1' => 'string',
           'test2' => 'string'
       )
   )
);
$headers = array(
   'Content-Type' => 'application/json',
   'X-Api-Key' => 'YOUR_API_KEY'
);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

Python

import requests
import json
url = 'https://api.rusender.ru/api/v1/external-mails/send-by-template'
data = {
    'idempotencyKey': 'unique-key-string',
    'mail': {
        'to': {
            'email': 'user@example.com',
            'name': 'string'
        },
        'from': {
            'email': 'user@example.com',
            'name': 'string'
        },
        'subject': 'string',
        'previewTitle': 'string',
        'idTemplateMailUser': number,
        'params': {
            'test': 'string',
            'test1': 'string',
            'test2': 'string'
        }
    }
}
headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
}
response = requests.post(url, json=data, headers=headers)

Node.js

const axios = require('axios');
const url = 'https://api.rusender.ru/api/v1/external-mails/send-by-template';
const data = {
    idempotencyKey: 'unique-key-string',
    mail: {
        to: {
            email: 'user@example.com',
            name: 'string'
        },
        from: {
            email: 'user@example.com',
            name: 'string'
        },
        subject: 'string',
        previewTitle: 'string',
        idTemplateMailUser: number,
        params: {
            test: 'string',
            test1: 'string',
            test2: 'string'
        }
    }
};
const headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
};
axios.post(url, data, { headers })
    .then(response => {
        // Обработка ответа API
    })
    .catch(error => {
        // Обработка ошибки
    });

JavaScript

const url = 'https://api.rusender.ru/api/v1/external-mails/send-by-template';
const data = {
    idempotencyKey: 'unique-key-string',
    mail: {
        to: {
            email: 'user@example.com',
            name: 'string'
        },
        from: {
            email: 'user@example.com',
            name: 'string'
        },
        subject: 'string',
        previewTitle: 'string',
        idTemplateMailUser: number,
        params: {
            test: 'string',
            test1: 'string',
            test2: 'string'
        }
    }
};
const headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
};
fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
    .then(response => response.json())
    .then(data => {
        // Обработка ответа API
    })
    .catch(error => {
        // Обработка ошибки
    });

Если запрос возвращает ошибку: «Неверный ключ API», замените код передачи API-ключа на:
$headers = array( 'Content-Type: application/json', 'X-Api-Key: YOUR_API_KEY');

Ограничения по прикрепляемым файлам и размеру

Ограничение на размер тела запроса	5 мб
Ограничение на общий размер вложений в письме	5 мб
Ограничение на количество вложений в письме	20 штук
Ограничение на вложения в письме (тип файла)	`ADE, ADP, APK, APPX, APPXBUNDLE, BAT, CAB, CHM, CMD, COM, CPL, DIAGCAB, DIAGCFG, DIAGPACK, DLL, DMG, EX, EX_, EXE, HTA, IMG, INS, ISO, ISP, JAR, JNLP, JS, JSE, LIB, LNK, MDE, MSC, MSI, MSIX, MSIXBUNDLE, MSP, MST, NSH, PIF, PS1, SCR, SCT, SHB, SYS, VB, VBE, VBS, VHD, VXD, WSC, WSF, WSH, XLL.`

Дата публикации: 2 сентября 2025 Обновлено: 26 февраля 2026

Автор статьи

Дарья Л.

Написано статей: 116

Контент-менеджер и email маркетолог в RuSender.

Поделиться статьёй

Документация Email API

Создание API ключа

Роут отправки письма (с готовым HTML)

POST `/v1/external-mails/send`

Пример тела запроса

Отправка письма с использованием шаблона RuSender

POST `/v1/external-mails/send-by-template`

Пример тела запроса

Описание полей

Рекомендации по использованию

Отправка с использованием ключа идемпотентности

Примечания

Возможные ответы сервера

200 OK — Успешная отправка

400 Bad Request — Ошибка валидации

401 Unauthorized — Невалидный API-ключ

402 Payment Required — Недостаточно средств

403 Forbidden — API-ключ не активен

404 Not Found — Ресурс не найден

422 Unprocessable Entity — Получатель недоступен

500 Internal Server Error — Внутренняя ошибка сервера

503 Service Unavailable — Сервис недоступен

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

PHP

Python

Node.js

JavaScript

Примеры использования API с шаблоном письма RuSender

PHP

Python

Node.js

JavaScript

Ограничения по прикрепляемым файлам и размеру

Автор статьи

Запустите первую рассылку в RuSender

Документация Email API

Создание API ключа

Роут отправки письма (с готовым HTML)

POST /v1/external-mails/send

Пример тела запроса

Отправка письма с использованием шаблона RuSender

POST /v1/external-mails/send-by-template

Пример тела запроса

Описание полей

Рекомендации по использованию

Отправка с использованием ключа идемпотентности

Примечания

Возможные ответы сервера

200 OK — Успешная отправка

400 Bad Request — Ошибка валидации

401 Unauthorized — Невалидный API-ключ

402 Payment Required — Недостаточно средств

403 Forbidden — API-ключ не активен

404 Not Found — Ресурс не найден

422 Unprocessable Entity — Получатель недоступен

500 Internal Server Error — Внутренняя ошибка сервера

503 Service Unavailable — Сервис недоступен

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

PHP

Python

Node.js

JavaScript

Примеры использования API с шаблоном письма RuSender

PHP

Python

Node.js

JavaScript

Ограничения по прикрепляемым файлам и размеру

Автор статьи

Запустите первую рассылку в RuSender

POST `/v1/external-mails/send`

POST `/v1/external-mails/send-by-template`