Обзор

Docusaurus preview · 51 методов · 11 разделов

API-документация российского SMTP-сервиса СамОтправил. Сервис ориентирован на интеграцию с SaaS-решениями. Рекомендуем ознакомиться с особенностями интеграции. Также вы можете обсудить интеграцию с нашими специалистами.

Готовые библиотеки

Python. Автор: Команда SamOtpravil
PHP. Автор: Константин Пензин
Ruby. Автор: Сообщество Rubyschool

Авторизация

Авторизация происходит через использование API-ключа в заголовке Authorization: {{api_key}}

Чтобы получить API ключ к SMTP методам, отправьте запрос.

Лимиты

Лимиты на запросы

К SMTP можно обращаться не более 10 000 раз в минуту.

В случае превышения лимита, вы получите ошибку с кодом 429.
{"status":"throttling","error":"Request was throttled. Expected available in 1 second."}
Напишите нам, если требуется увеличить лимит.

Среднее время выполнения одного запроса 500мс.

Лимиты на отправки

Все рассылки при создании имеют ограничение 100 писем \ 5 минут

При превышении лимита, вы получите ошибку 450 ratelimit exceeded
Напишите в поддержку, чтобы увеличить лимит.

Лимиты на создание пакетов

Все рассылки при создании имеют ограничение 40 пакетов \ 5 минут

При превышения лимита, вы получите ошибку E429Напишите в поддержку, чтобы увеличить лимит.

Лимит на размер письма

Стандартный лимит на размер письма - 50mb

Настройки

SMTP сервер: api.samotpravil.ru
Порт: 1126 или 1127 (TLS)

Треккинг открытий и кликов

Для отслеживания кликов оберните все ссылки в в следующий редирект

[domain]/click/[X-Track-ID]?goto_url=[url]

Для отслеживания открытий добавьте следующую конструкцию в контент письма

img src="[domain]/open/[X-Track-ID]" alt="" height="1" width="1" border="0"

X-Track-ID это ваш внутренний ID отправки, нужно также его передавать и в заголовок письма. Должен быть уникальным для каждой отправки.
Хорошая практика формирования X-Track-ID -

{{login}}-{{timestamp}}-{{your_campaign_id}}-{{your_email_id}}

login - ваш логин к SMTP
timestamp - временная метка запроса
your_campaign_id - ID рассылки \ имейл-кампании
your_email_id - ID конкретной отправки

url это целевая ссылка
domain это track.smtprvl.ru или ваш домен

Для настройки вашего домена обратитесь в поддержку.

Все значения для переменных формируются на вашей стороне.
СамОтправил не взаимодействует с контентом писем.
Если вам нужна поддержка передаваемых переменных, воспользуйтесь API

Ознакомьтесь подробнее с тем, какие бывают ошибки и с нашей политикой ретраев

Если в копии есть имейл, находящийся в стоп-листе, то отправка не будет произведена ни на один имейл

Обратите внимание, что если имейл находится в любом из стоп-листов, при попытке отправить письмо на этот адрес, вы будете получать ошибку 550 bounced check filter. Каждый такой запрос будет тарифицироваться системой, настройте соответствующую обработку ошибок.
В ответе также будет присутствовать поле ttl_date, в нем указана дата выхода имейла из стоп-листа. Если имейл находится в стоп-листе без возможности выхода, в ответе вы получите
"ttl_date": "0"

Ошибка	Причина
550 bounced check filter	Имейл получателя находится в стоп-листе. Подробнее про работу стоп-листов
501 from domain not trusted	Домен, с которого производится отправка, не добавлен в список разрешенных
421 SMTP command timeout - closing connection	Если сделать подключение, отправить письмо, не закрыть его для дальнейшего переиспользования, и ничего не писать более 120s, то сервер запишет 421 ошибку и закроет соединение.
450 ratelimit exceeded	Превышен лимит запросов на отправку. Для новых клиентов ограничение 100 запросов в 5 минут. Напишите в поддержку, чтобы увеличить лимит

Кастомный Return-Path

Если Ваше програмное обеспечение работает с VERP форматом, создайте запрос на подключение выделенного сендера с этой фичей.

Формат VERP (Variable Envelope Return Path) - это метод в электронной почте, который позволяет почтовым серверам уникально идентифицировать каждого получателя массовой рассылки, встраивая его адрес в обратный путь (envelope sender), что упрощает управление баунсами и удаление недействительных адресов без парсинга содержимого писем. Если письмо не доставляется, обратный адрес (bounce message) содержит информацию о том, кому именно оно предназначалось, позволяя автоматически отписать неработающий адрес.

Пример заголовка Return-Path в VERP-формате:
Return-Path: bounce+fd1ba13a+rcptname=mail.ru@samotpravil.ru

MCP для Cursor и Claude

MCP (Model Context Protocol) — способ подключить API СамОтправил к AI-ассистентам в IDE. Сервер даёт поиск по документации, typed tools для отправки и стоп-листов, offline-fallback и безопасные пресеты (READ_ONLY, dry_run).

Установка в Cursor

Файл .cursor/mcp.json в корне проекта:

{
  "mcpServers": {
    "samotpravil": {
      "command": "npx",
      "args": ["-y", "samotpravil-mcp@latest"],
      "env": {
        "SAMOTPRAVIL_API_KEY": "ваш_api_ключ",
        "SAMOTPRAVIL_READ_ONLY": "1",
        "SAMOTPRAVIL_ALLOW_SEND": "0"
      }
    }
  }
}

Ключ API — в заголовке Authorization (см. раздел «Авторизация»). Для только документации ключ можно не указывать. После правок: Settings → MCP → Reload.

Также поддерживаются Claude Desktop и VS Code Copilot — см. docs/EXAMPLES.md.

Открыть API Reference →