Ваша почта.
В вашем приложении.

Проверить API

Вставьте токен и выполните запрос прямо здесь. Консоль выполняет только чтение; токен остаётся в памяти этой страницы и передаётся серверу LiteMail в заголовке Authorization.

Здесь появится JSON ответа.

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

Выполнить первый запрос

LiteMail API использует Bearer Token авторизацию. Токен передаётся в HTTP-заголовке Authorization.

curl "https://litemail.one/api/v1/mailboxes/test123@litemail.one/messages/latest" \
  -H "Authorization: Bearer lm_YOUR_API_TOKEN"

Авторизация

API поддерживает два типа токенов. Они предназначены для разных сценариев использования.

Заголовок запроса

Authorization: Bearer YOUR_TOKEN

LM API — пользовательский токен

Токен lm_... принадлежит аккаунту LiteMail. Он позволяет обращаться к почтовым ящикам этого пользователя.

curl "https://litemail.one/api/v1/me" \
  -H "Authorization: Bearer lm_YOUR_API_TOKEN"

{
  "id": 123,
  "username": "testuser",
  "balance": 250.0,
  "mailbox_count": 5
}

curl "https://litemail.one/api/v1/mailboxes" \
  -H "Authorization: Bearer lm_YOUR_API_TOKEN"

curl "https://litemail.one/api/v1/mailboxes/test123@litemail.one" \
  -H "Authorization: Bearer lm_YOUR_API_TOKEN"

MT API — конкретная почта

Токен mt_... привязан к одному почтовому ящику. При его использовании указывать email почты уже не требуется: mailbox определяется сервером из самого токена.

curl "https://litemail.one/api/v1/mail/me" \
  -H "Authorization: Bearer mt_YOUR_TOKEN"

curl "https://litemail.one/api/v1/mail/messages/latest" \
  -H "Authorization: Bearer mt_YOUR_TOKEN"

curl "https://litemail.one/api/v1/mail/messages?limit=10" \
  -H "Authorization: Bearer mt_YOUR_TOKEN"

Получение писем

Для пользовательского lm_-токена используется email почтового ящика непосредственно в URL.

curl "https://litemail.one/api/v1/mailboxes/test123@litemail.one/messages/latest" \
  -H "Authorization: Bearer lm_YOUR_API_TOKEN"

curl "https://litemail.one/api/v1/mailboxes/test123@litemail.one/messages/latest?unread=true" \
  -H "Authorization: Bearer lm_YOUR_API_TOKEN"

curl "https://litemail.one/api/v1/mailboxes/15/messages?limit=10&offset=0" \
  -H "Authorization: Bearer lm_YOUR_API_TOKEN"

Фильтры

Endpoint списка сообщений поддерживает несколько фильтров. Их можно комбинировать.

Пример: найти письма от Discord

curl "https://litemail.one/api/v1/mailboxes/test123@litemail.one/messages?sender=discord" \
  -H "Authorization: Bearer lm_YOUR_API_TOKEN"

Пример: Discord + verification + unread

curl "https://litemail.one/api/v1/mailboxes/test123@litemail.one/messages?sender=discord&subject=verification&unread=true&limit=10" \
  -H "Authorization: Bearer lm_YOUR_API_TOKEN"

Read / Unread

curl -X POST \
  "https://litemail.one/api/v1/mailboxes/15/messages/482/read" \
  -H "Authorization: Bearer lm_YOUR_API_TOKEN"

curl -X POST \
  "https://litemail.one/api/v1/mailboxes/15/messages/482/unread" \
  -H "Authorization: Bearer lm_YOUR_API_TOKEN"

Удаление письма

curl -X DELETE \
  "https://litemail.one/api/v1/mailboxes/15/messages/482" \
  -H "Authorization: Bearer lm_YOUR_API_TOKEN"

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

Отправитель определяется сервером из выбранного mailbox. Поле From нельзя подменить через API.

{
  "to": [
    "example@gmail.com"
  ],
  "subject": "Тестовое письмо",
  "text": "Привет! Это письмо отправлено через LiteMail API.",
  "html": "<p>Привет!</p>"
}

curl -X POST \
  "https://litemail.one/api/v1/mailboxes/15/send" \
  -H "Authorization: Bearer lm_YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["example@gmail.com"],
    "subject": "Тестовое письмо",
    "text": "Привет из LiteMail API"
  }'

Смена пароля mailbox

curl -X POST \
  "https://litemail.one/api/v1/mailboxes/15/password" \
  -H "Authorization: Bearer lm_YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "new_password": "NewPassword123!"
  }'

MT-токены

Владелец аккаунта может выпустить отдельный токен для конкретной почты. Старый активный mt-токен этого mailbox при этом отзывается.

curl -X POST \
  "https://litemail.one/api/v1/mailboxes/test123@litemail.one/token" \
  -H "Authorization: Bearer lm_YOUR_API_TOKEN"

{
  "status": "ok",
  "mailbox_id": 15,
  "email": "test123@litemail.one",
  "token": "mt_xxxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer"
}

curl -X DELETE \
  "https://litemail.one/api/v1/mailboxes/test123@litemail.one/token" \
  -H "Authorization: Bearer lm_YOUR_API_TOKEN"

Лимиты и защита

LiteMail API имеет встроенную защиту от большого количества запросов и перебора токенов.

HTTP 429

Если лимит превышен, API возвращает 429 Too Many Requests и заголовок Retry-After.

{
  "code": "RATE_LIMITED",
  "message": "Слишком много запросов",
  "retry_after": 12
}

Защита от перебора

Серия неверных API-токенов с одного IP приводит к временной блокировке этого IP. Это относится как к lm_, так и к mt_ авторизации.

Ошибки API

Ошибки обработанных маршрутов возвращают code и message; поле detail сохранено для совместимости. HTTP 422 означает ошибку полей запроса. X-Request-ID можно передать поддержке, Server-Timing показывает время обработки приложения. Для 429 соблюдайте Retry-After; POST/DELETE автоматически не повторяйте.

Пример обработки ошибки

{
  "detail": {
    "code": "INVALID_TOKEN",
    "message": "Неверный API-токен"
  }
}

Пример на Python

Простейший вариант получения последнего письма по email:

import requests

API = "https://litemail.one/api/v1"

TOKEN = "lm_YOUR_API_TOKEN"
EMAIL = "test123@litemail.one"

response = requests.get(
    f"{API}/mailboxes/{EMAIL}/messages/latest",
    headers={
        "Authorization": f"Bearer {TOKEN}"
    },
    timeout=20
)

response.raise_for_status()

data = response.json()

message = data.get("message")

if message:
    print("От:", message["from"])
    print("Тема:", message["subject"])
    print("Дата:", message["date"])
    print("Текст:")
    print(message["text"])
else:
    print("Писем нет")

Поиск по критериям

import requests

API = "https://litemail.one/api/v1"

TOKEN = "lm_YOUR_API_TOKEN"
EMAIL = "test123@litemail.one"

response = requests.get(
    f"{API}/mailboxes/{EMAIL}/messages",
    headers={
        "Authorization": f"Bearer {TOKEN}"
    },
    params={
        "sender": "discord",
        "subject": "verification",
        "unread": True,
        "limit": 10
    },
    timeout=20
)

response.raise_for_status()

data = response.json()

for message in data["messages"]:
    print(
        message["date"],
        message["from"],
        message["subject"]
    )

Безопасность