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

ВЕРСИЯ 2.0.4 // СЕКРЕТНЫЙ ПРОТОКОЛ СВЯЗИ

Добро пожаловать в документацию API PetrovnaMail. Наш RESTful API позволяет вам программно интегрировать функции зашифрованной электронной почты в ваши собственные приложения. Вся коммуникация с нашими серверами должна осуществляться через защищенные каналы (HTTPS/TLS 1.3).

ВНИМАНИЕ: Из-за нашей архитектуры Zero-Access, сервер не может расшифровать ваши письма. API возвращает только зашифрованные PGP-блоки (Ciphertext). Дешифровка должна происходить исключительно на стороне клиента с использованием вашего закрытого ключа.

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

Для каждого запроса требуется действующий токен API. Вы можете сгенерировать токен в панели управления вашей учетной записью. Токен должен передаваться в заголовке запроса.

Authorization: Bearer <ВАШ_СЕКРЕТНЫЙ_ТОКЕН>

2. Ограничения (Rate Limits)

В целях предотвращения DDoS-атак и спама, мы применяем строгие ограничения количества запросов. Если вы превысите лимит, ваш IP-адрес будет временно заблокирован в сети.

Стандартные аккаунты: 60 запросов в минуту.
Отправка сообщений (POST): 10 сообщений в минуту.

3. Эндпоинты (Endpoints)

GET /api/v1/account/status

Возвращает текущий статус вашей учетной записи, квоту хранения и список связанных открытых ключей (Public Keys).

Пример Запроса:

curl -X GET "https://api.petrovna.net/v1/account/status" \
-H "Authorization: Bearer ВАШ_ТОКЕН"

Ответ (200 OK):

{
  "status": "active",
  "identifier": "user_883a9f",
  "storage_used_mb": 12.4,
  "public_key_fingerprint": "9F8A 2B3C 4D5E 6F70"
}

POST /api/v1/messages/send

Отправляет зашифрованное сообщение другому пользователю. Вы должны самостоятельно зашифровать тело сообщения с помощью открытого ключа получателя до выполнения этого запроса.

Тело Запроса (JSON):

{
  "recipient": "[email protected]",
  "encrypted_body": "-----BEGIN PGP MESSAGE-----\nwcBMA3...",
  "destroy_after_read": true
}

Ответ (201 Created):

{
  "message_id": "msg_00918274",
  "delivery_status": "queued_for_encryption"
}

GET /api/v1/messages/inbox

Получает список непрочитанных сообщений. Сервер возвращает зашифрованные блоки. Для чтения содержимого необходимо локально применить ваш закрытый ключ.

Ответ (200 OK):

{
  "unread_count": 1,
  "messages": [
    {
      "id": "msg_00918275",
      "timestamp": 1711039422,
      "ciphertext": "-----BEGIN PGP MESSAGE-----\n..."
    }
  ]
}

4. Коды Ошибок

Если что-то пойдет не так, API вернет стандартные HTTP-коды статуса вместе с сообщением об ошибке в формате JSON.

400 Bad Request — Неверный формат тела запроса (например, невалидный PGP блок).
401 Unauthorized — Неверный токен API. Они отклонили ваш доступ.
429 Too Many Requests — Превышен лимит запросов. Спрячьтесь и подождите.
500 Internal Server Error — Критический сбой маршрутизации.