FichaMail API

REST API для отправки писем и управления контактами. Базовый адрес: https://fichamail.com. Все запросы и ответы — JSON в UTF-8.

Авторизация

Создайте ключ в разделе API-ключи и передавайте его в заголовке Authorization: Bearer fm_…. Ключ показывается один раз, у нас хранится только его хэш. Права send позволяют только отправлять письма, full — ещё и управлять контактами.

Отправка письма

POST /v1/emails ставит письмо в очередь и сразу возвращает его ID. Домен в поле from должен быть подтверждён.

curl -X POST https://fichamail.com/v1/emails \
  -H "Authorization: Bearer fm_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Команда <hello@вашдомен.ru>",
    "to": "[email protected]",
    "subject": "Добро пожаловать!",
    "html": "<h1>Привет 👋</h1>"
  }'

{ "id": "4f1c9a0e2b7d8c3a5e6f1b2c" }
// для нескольких получателей: { "ids": ["...", "..."] }

Вложения

Добавьте в запрос массив attachments: до 10 файлов, вместе не больше 10 МБ. Содержимое файла передаётся в base64, тип определяется по расширению или задаётся в content_type.

curl -X POST https://fichamail.com/v1/emails \
  -H "Authorization: Bearer fm_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Бухгалтерия <billing@вашдомен.ru>",
    "to": "[email protected]",
    "subject": "Счёт №128",
    "html": "<p>Счёт во вложении.</p>",
    "attachments": [
      { "filename": "invoice-128.pdf", "content": "JVBERi0xLjQK..." }
    ]
  }'

SMTP

Для WordPress, 1С-Битрикс, почтовых плагинов и любых программ, которые умеют только SMTP. Письма попадают в ту же очередь, что и через API: подписываются DKIM, видны в журнале, учитываются в лимитах и стоп-листах. Вложения и скрытая копия поддерживаются.

import smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "Магазин <hello@вашдомен.ru>"
msg["To"] = "[email protected]"
msg["Subject"] = "Заказ оплачен"
msg.set_content("Спасибо за заказ!")

with smtplib.SMTP("smtp.fichamail.com", 587) as s:
    s.starttls()
    s.login("fichamail", "fm_ваш_ключ")
    s.send_message(msg)

До 50 получателей в одном письме, размер до 10 МБ. Ошибки приходят стандартными кодами SMTP: 550 5.7.1 — домен отправителя не подтверждён, 451 4.7.1 — исчерпан дневной лимит.

Тестовый режим

Создайте ключ в режиме «Тестовый» (он начинается с fm_test_). С ним API и SMTP принимают письма как обычно, но ничего не отправляют: письмо сразу получает статус sent, помечается как тестовое и видно в журнале. Подтверждённый домен не нужен, лимит не расходуется — удобно для разработки и автотестов.

Статус письма

GET /v1/emails/:id — текущий статус: queued, sent, deferred (временная ошибка, будет повтор), bounced, failed или suppressed (адрес в стоп-листе).

curl https://fichamail.com/v1/emails/4f1c9a0e2b7d8c3a5e6f1b2c \
  -H "Authorization: Bearer fm_ваш_ключ"

Контакты

POST /v1/contacts добавляет или обновляет контакт и кладёт его в группы. Удобно для форм подписки на сайте. Нужен ключ с правами full.

curl -X POST https://fichamail.com/v1/contacts \
  -H "Authorization: Bearer fm_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","first_name":"Анна","group_ids":[1]}'

Формы подписки

Создайте форму в разделе Формы подписки и вставьте готовый HTML-код на сайт. Либо отправляйте данные сами: POST /f/:token принимает обычную форму или JSON с полями email и first_name. Запросы с других сайтов разрешены (CORS). С двойным подтверждением подписчик сначала получает письмо со ссылкой и только после клика попадает в группу.

const res = await fetch('https://fichamail.com/f/ТОКЕН_ФОРМЫ', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
  body: JSON.stringify({ email: '[email protected]', first_name: 'Анна' }),
})
const { ok, message } = await res.json()

Персонализация

В теме и тексте рассылок можно использовать переменные {{first_name}}, {{last_name}}, {{email}} и {{unsubscribe_url}}. Ссылка отписки и заголовок List-Unsubscribe добавляются к каждому письму автоматически.

Вебхуки

Доступны на тарифах от «Старт». Мы отправляем POST на ваш URL при событиях sent, bounced, failed, complained, opened, clicked, unsubscribed. Если ваш сервер не ответил кодом 2xx за 10 секунд, повторим через 1, 5 и 30 минут, 2 и 6 часов. Все попытки и ответы видны в журнале доставок вебхука, оттуда же событие можно отправить повторно. Тело подписано HMAC-SHA256 секретом вебхука, подпись лежит в заголовке X-FichaMail-Signature.

import crypto from 'node:crypto'

const sig = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(rawBody).digest('hex')
if (sig !== req.headers['x-fichamail-signature']) return res.status(401).end()

Ошибки и лимиты

Полная OpenAPI-схема: /api/docs.