MidnightService Mailer API

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

Отправляйте письма Wallapop автоматически через HTTP-запросы.
Парсинг объявлений, генерация писем, сокращение ссылок.

5

Эндпоинтов

REST

Архитектура

JSON

Формат

Base URL https://api.midnightchamberx.com/api/v1/mailer

Быстрый старт

1

Получите API ключ

Запросите ключ через Telegram бота: Профиль → API доступ → Подать заявку. После одобрения администратором вы получите ключ формата midnight_xxxxxxxx.

2

Добавьте заголовок авторизации

Передавайте ключ в заголовке X-MIDNIGHT-TOKEN каждого запроса.

3

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

Используйте эндпоинт /send для автоматической отправки по ссылке Wallapop.

curl -X POST "https://api.midnightchamberx.com/api/v1/mailer/send" \
  -H "Content-Type: application/json" \
  -H "X-MIDNIGHT-TOKEN: midnight_your_key" \
  -d '{
    "listing_url": "https://es.wallapop.com/item/12345",
    "to_email": "[email protected]",
    "link": "https://your-link.com/pay",
    "lang": "es",
    "shorten_link": true
  }'

import requests

API_URL = "https://api.midnightchamberx.com/api/v1/mailer"
TOKEN = "midnight_your_key"

headers = {
    "Content-Type": "application/json",
    "X-MIDNIGHT-TOKEN": TOKEN,
}

response = requests.post(f"{API_URL}/send", json={
    "listing_url": "https://es.wallapop.com/item/12345",
    "to_email": "[email protected]",
    "link": "https://your-link.com/pay",
    "lang": "es",
    "shorten_link": True,
}, headers=headers)

print(response.json())

const API_URL = "https://api.midnightchamberx.com/api/v1/mailer";
const TOKEN = "midnight_your_key";

const response = await fetch(`${API_URL}/send`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-MIDNIGHT-TOKEN": TOKEN,
  },
  body: JSON.stringify({
    listing_url: "https://es.wallapop.com/item/12345",
    to_email: "[email protected]",
    link: "https://your-link.com/pay",
    lang: "es",
    shorten_link: true,
  }),
});

const data = await response.json();
console.log(data);

Аутентификация

Все запросы к API требуют заголовок X-MIDNIGHT-TOKEN. Поддерживаются два типа токенов:

🔑

API ключ

Постоянный ключ для команды/проекта. Формат: midnight_xxxxxxxx. Не имеет срока действия. Выдаётся администратором после одобрения заявки.

⏳

Ключ подписки

Временный ключ с ограниченным сроком (1/7/30 дней). Формат: UUID. Привязывается к Telegram ID при активации. Деактивируется автоматически.

⚠️

Без токена — любой запрос вернёт 401 Unauthorized:

{"detail": "Api token is required"}

Пример заголовка

X-MIDNIGHT-TOKEN: midnight_a1b2c3d4e5f6g7h8

POST /api/v1/mailer/send

Отправить письмо (авто)

Парсит объявление Wallapop по ссылке, извлекает название и цену, генерирует письмо из шаблона и отправляет на указанный email.

Параметры запроса

listing_urlstringдаURL объявления Wallapop (https://*.wallapop.com/...)

to_emailstringдаEmail получателя

linkstringдаСсылка для кнопки в письме

langstringнетЯзык шаблона: es (Испания) или it (Италия). Авто-определение по URL

shorten_linkbooleanнетСократить ссылку через Short.io. По умолчанию false

Ответ

{
  "success": true,
  "message": "Email sent successfully",
  "details": {
    "to": "[email protected]",
    "item_name": "iPhone 15 Pro Max",
    "price": "899.00",
    "template": "wallapop_es.html"
  }
}

curl -X POST "https://api.midnightchamberx.com/api/v1/mailer/send" \
  -H "Content-Type: application/json" \
  -H "X-MIDNIGHT-TOKEN: YOUR_TOKEN" \
  -d '{
    "listing_url": "https://es.wallapop.com/item/iphone-15-pro-123",
    "to_email": "[email protected]",
    "link": "https://pay.example.com/order/123",
    "lang": "es",
    "shorten_link": true
  }'

resp = requests.post(f"{API_URL}/send", json={
    "listing_url": "https://es.wallapop.com/item/iphone-15-pro-123",
    "to_email": "[email protected]",
    "link": "https://pay.example.com/order/123",
    "lang": "es",
    "shorten_link": True,
}, headers=headers)

data = resp.json()
if data["success"]:
    print(f"Отправлено: {data['details']['item_name']}")
else:
    print(f"Ошибка: {data['message']}")

const resp = await fetch(`${API_URL}/send`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-MIDNIGHT-TOKEN": TOKEN },
  body: JSON.stringify({
    listing_url: "https://es.wallapop.com/item/iphone-15-pro-123",
    to_email: "[email protected]",
    link: "https://pay.example.com/order/123",
    lang: "es",
    shorten_link: true,
  }),
});
const data = await resp.json();
console.log(data.success ? "Sent!" : data.message);

POST /api/v1/mailer/send-manual

Ручная отправка

Отправляет письмо с указанными вручную данными товара и выбранным шаблоном. Не требует парсинга — вы сами задаёте название, цену и шаблон.

Параметры запроса

to_emailstringдаEmail получателя

templatestringдаИмя файла шаблона (напр. wallapop_es.html)

linkstringдаСсылка для кнопки в письме

item_namestringдаНазвание товара

amountstringдаЦена товара (напр. "149.99")

from_namestringнетИмя отправителя. По умолчанию "Wallapop"

shorten_linkbooleanнетСократить ссылку. По умолчанию false

Ответ

{
  "success": true,
  "message": "Email sent successfully",
  "details": {
    "to": "[email protected]",
    "template": "wallapop_es.html"
  }
}

curl -X POST "https://api.midnightchamberx.com/api/v1/mailer/send-manual" \
  -H "Content-Type: application/json" \
  -H "X-MIDNIGHT-TOKEN: YOUR_TOKEN" \
  -d '{
    "to_email": "[email protected]",
    "template": "wallapop_es.html",
    "link": "https://pay.example.com/order/456",
    "item_name": "MacBook Pro M3",
    "amount": "1299.00",
    "from_name": "Wallapop",
    "shorten_link": false
  }'

resp = requests.post(f"{API_URL}/send-manual", json={
    "to_email": "[email protected]",
    "template": "wallapop_es.html",
    "link": "https://pay.example.com/order/456",
    "item_name": "MacBook Pro M3",
    "amount": "1299.00",
    "from_name": "Wallapop",
    "shorten_link": False,
}, headers=headers)

POST /api/v1/mailer/shorten

Сократить ссылку

Сокращает URL через Short.io. Можно использовать отдельно от отправки писем.

Параметры запроса

urlstringдаURL для сокращения (должен начинаться с http:// или https://)

Ответ

{
  "success": true,
  "short_url": "https://short.link/abc123",
  "original_url": "https://very-long-url.com/path/to/page"
}

curl -X POST "https://api.midnightchamberx.com/api/v1/mailer/shorten" \
  -H "Content-Type: application/json" \
  -H "X-MIDNIGHT-TOKEN: YOUR_TOKEN" \
  -d '{"url": "https://example.com/very/long/path"}'

resp = requests.post(f"{API_URL}/shorten", json={
    "url": "https://example.com/very/long/path"
}, headers=headers)

short = resp.json()["short_url"]
print(f"Short URL: {short}")

GET /api/v1/mailer/templates

Список шаблонов

Возвращает список доступных HTML-шаблонов писем. Используйте имя шаблона в /send-manual.

Ответ

{
  "templates": [
    "wallapop_es.html",
    "wallapop_it.html"
  ]
}

curl "https://api.midnightchamberx.com/api/v1/mailer/templates" \
  -H "X-MIDNIGHT-TOKEN: YOUR_TOKEN"

resp = requests.get(f"{API_URL}/templates", headers=headers)
templates = resp.json()["templates"]
for t in templates:
    print(f"  · {t}")

GET /api/v1/mailer/languages

Поддерживаемые языки

Возвращает список поддерживаемых языков с привязкой к шаблонам. Используйте код языка в поле lang эндпоинта /send.

Ответ

{
  "es": {
    "template": "wallapop_es.html",
    "name": "🇪🇸 Испания"
  },
  "it": {
    "template": "wallapop_it.html",
    "name": "🇮🇹 Италия"
  }
}

curl "https://api.midnightchamberx.com/api/v1/mailer/languages" \
  -H "X-MIDNIGHT-TOKEN: YOUR_TOKEN"

Интеграция в другое ПО

Для подключения CRM, скриптов, мобильных приложений и сервисов используйте REST API с заголовком X-MIDNIGHT-TOKEN и JSON-телом. Полное руководство с примерами на Python, JavaScript, PHP, C# и таблицами полей — в файле:

API_INTEGRATION.md

Базовый URL и список путей
Аутентификация (API-ключ и ключ подписки)
Описание details в ответе MailerResponse
Исключения middleware (без токена: /health, /openapi.json)
Рекомендации: таймауты, безопасность ключа, OpenAPI

Машиночитаемая схема: /openapi.json

Коды ошибок

API использует стандартные HTTP-коды состояния. Тело ответа содержит поле detail с описанием ошибки.

400Bad RequestНеверные параметры запроса (невалидный email, URL и т.д.)

401UnauthorizedОтсутствует или невалидный X-MIDNIGHT-TOKEN

403ForbiddenТокен просрочен или деактивирован / обязательные поля отсутствуют

500Server ErrorВнутренняя ошибка (SMTP, парсинг, база данных)

Формат ошибки

// 401 — нет токена
{"detail": "Api token is required"}

// 401 — невалидный токен
{"detail": "Invalid or expired token"}

// 400 — невалидный URL
{"detail": "listing_url must be a valid Wallapop URL"}

// 400 — невалидный email
{"detail": "to_email must be a valid email address"}

// 400 — невалидная ссылка для сокращения
{"detail": "url must start with http:// or https://"}

// 403 — отсутствует обязательное поле
{"detail": "listing_url is required"}

// 403 — несколько полей отсутствуют
{"details": "Listing_url, to_email, link are required"}

Модели данных

SendWallapopRequest

Тело запроса для авто-отправки по ссылке Wallapop.

{
  "listing_url": "string",   // URL объявления Wallapop (обяз.)
  "to_email": "string",      // Email получателя (обяз.)
  "link": "string",          // Ссылка для кнопки (обяз.)
  "lang": "string | null",   // Язык: "es" / "it" (опц.)
  "shorten_link": false       // Сократить ссылку (опц.)
}

SendManualRequest

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

{
  "to_email": "string",      // Email получателя (обяз.)
  "template": "string",      // Имя шаблона (обяз.)
  "link": "string",          // Ссылка для кнопки (обяз.)
  "item_name": "string",     // Название товара (обяз.)
  "amount": "string",        // Цена (обяз.)
  "from_name": "Wallapop",   // Имя отправителя (опц.)
  "shorten_link": false       // Сократить ссылку (опц.)
}

ShortenRequest

Тело запроса для сокращения ссылки.

{
  "url": "string"   // URL для сокращения (http:// или https://)
}

MailerResponse

Стандартный ответ эндпоинтов отправки.

{
  "success": true,            // Успех операции
  "message": "string",        // Текстовое описание результата
  "details": {}               // Детали (шаблон, получатель и т.д.)
}

ShortenResponse

Ответ сокращения ссылки.

{
  "success": true,
  "short_url": "string | null",  // Короткая ссылка (null при ошибке)
  "original_url": "string"       // Оригинальный URL
}

TemplatesResponse

Список доступных шаблонов.

{
  "templates": ["string"]   // Массив имён файлов шаблонов
}