MailSMMO
Zaloguj się

// REST API

Dokumentacja REST API

Endpointy dla narzędzi używają GET i zwracają JSON w postaci { "status": "success", "data": … }. Uwierzytelniaj się parametrem ?api_key= ze strony Dokumentacja API po zalogowaniu.

Endpointy

Bazowy URL: https://mailsmmo.com

GET/api/v1/services

Serwisy — cena i dostępność

Bez ?service= zwraca całą listę. Z ?service= zwraca cenę i dostępność jednego serwisu. Klucz API nie jest potrzebny.

Bez uwierzytelniania

  • service (opcjonalny) — Zostaw puste, aby pobrać całą listę; podaj kod, aby pobrać jeden serwis (akceptowane są też same kody, np. facebook)

Sukces

{ "status": "success", "data": { "services": [
    { "code": "otp_gmail_facebook", "name": "Facebook", "price": 5000, "stock": 42 }
  ] } }

GET/api/v1/me

Informacje o koncie

ID, e-mail i saldo konta, do którego należy użyty klucz API.

Wymagany klucz API

Sukces

{ "status": "success", "data": { "id": "b7e5...-uuid", "email": "demo@mailsmmo.com", "balance": 1000000, "created_at": "2026-01-15T08:30:00Z" } }

GET/api/v1/orders

Utwórz zamówienie

Jeden endpoint do obu zastosowań: kod Gmail OTP (otp_gmail_*) wydaje jedną skrzynkę OTP; kod produktu z magazynu (hotmail_*…) kupuje w podanej ilości. Saldo jest obciążane zgodnie z ceną z listy.

Wymagany klucz API

  • service — Kod serwisu OTP (otp_gmail_*) lub kod produktu z magazynu (np. hotmail_imap_12m_36m)
  • quantity (opcjonalny) — Tylko dla e-maili sprzedawanych jednorazowo — ilość (domyślnie 1)
  • unique_key (opcjonalny) — Samodzielnie wygenerowany UUID — ponowne wysłanie nie utworzy zamówienia ani nie pobierze opłaty drugi raz

Sukces

{ "status": "success", "data": {
    "id": "b7e5a1c2-3d4e-4f60-8a91-2c3d4e5f6a7b", "email": "zurhansuzu@gmail.com",
    "service": "otp_gmail_facebook", "amount": 5000
  } }

GET/api/v1/orders/otp

Pobierz OTP dla zamówienia

Odczytuje OTP jednego zamówienia. Klucz API nie jest potrzebny — kod zamówienia (order_id) pełni rolę klucza dostępu.

Bez uwierzytelniania

  • order_id — Kod zamówienia (zwracany przy tworzeniu zamówienia)
  • unique_key (opcjonalny) — Nowy, samodzielnie wygenerowany UUID dla każdego wywołania
  • from (opcjonalny) — Sekundy Unix — otp/received_at są pomijane, dopóki nie pojawi się nowszy kod

Sukces

{ "status": "success", "data": {
    "otp": "481253", "amount": 5000, "received_at": 1732000000,
    "from": "security@facebookmail.com", "otp_history": [
      { "value": "481253", "received_at": 1732000000 }
    ] } }

GET/api/v1/otp/orders

Lista zamówień OTP

Wynajęte zamówienia Gmail OTP ze stronicowaniem, z najnowszym OTP każdego zamówienia.

Wymagany klucz API

  • page (opcjonalny) — Strona (domyślnie 1)
  • page_size (opcjonalny) — Wierszy na stronę (domyślnie 20, maks. 200)

Sukces

{ "status": "success", "data": { "orders": [
    { "id": "b7e5a1c2-3d4e-4f60-8a91-2c3d4e5f6a7b", "email": "...", "service": "otp_gmail_facebook",
      "latest_otp": "481253", "latest_link": null }
  ], "page": 1, "page_size": 20, "total": 137 } }

GET/api/v1/mail

Odczytaj wszystkie wiadomości

Wszystkie wiadomości z jednej skrzynki, wraz z wyciągniętym OTP/linkiem.

Wymagany klucz API

  • order_id — Kod zamówienia

Sukces

{ "status": "success", "data": { "count": 1, "messages": [
    { "id": 88, "from": "...", "subject": "...", "otp": "481253", "received_at": "..." }
  ] } }

typowe kody błędów

{ "status": "error", "message": "out_of_stock", "retryable": true }
  • unauthorized — Klucz API jest nieprawidłowy lub go brakuje (HTTP 401)
  • invalid_request — Nieprawidłowe parametry żądania (HTTP 400)
  • not_found — Nie znaleziono usługi, zamówienia ani endpointu (HTTP 404)
  • insufficient_balance — Niewystarczające saldo (HTTP 402)
  • out_of_stock — Brak w magazynie (HTTP 409) — Gmail OTP: retryable, spróbuj ponownie za kilka sekund; konta e-mail sprzedawane jednorazowo: poczekaj na uzupełnienie zapasów
  • service_unavailable — Serwer nie mógł teraz sfinalizować zamówienia — spróbuj ponownie z tym samym unique_key (HTTP 503, retryable)
  • in_progress — Zamówienie jest finalizowane lub mogło już powstać u dostawcy — spróbuj ponownie z tym samym unique_key (HTTP 409, retryable)
  • forbidden — Brak uprawnień do zasobu (HTTP 403)
  • idempotency_mismatch — unique_key został użyty w innym żądaniu — użyj nowego unique_key (HTTP 422)
  • order_cancelled — Zamówienie zostało zwolnione przed obciążeniem, nic nie pobrano — spróbuj ponownie (HTTP 409, retryable)
  • too_many_requests — Zbyt wiele żądań — odczekaj i spróbuj ponownie (HTTP 429, retryable)
  • auth_unavailable — Nie udało się teraz sprawdzić klucza API, klucz jest w porządku — spróbuj ponownie (HTTP 503, retryable)
  • shutting_down — Serwer się restartuje — spróbuj ponownie za kilka sekund (HTTP 503, retryable)
  • payload_too_large — Treść żądania jest zbyt duża (HTTP 413)
  • internal_server_error — Błąd serwera, spróbuj ponownie później (HTTP 500)

Dokumentacja dla AI i narzędzi

Pełna dokumentacja w Markdown jest dostępna pod adresem https://mailsmmo.com/llms.txt — wklej ją do Cursor, Claude lub ChatGPT, aby wygenerować kod integracji.

Bezpieczne ponawianie z unique_key

Wysyłaj unique_key (samodzielnie wygenerowany UUID) przy każdym zamówieniu. Jeśli połączenie się zerwie, ponów żądanie z tym samym unique_key: dostaniesz to samo zamówienie, bez nowego zamówienia i bez drugiej opłaty.

Format błędów

W razie błędu odpowiedź zawiera tylko status, message (kod błędu w snake_case) i retryable, które mówi, czy warto spróbować ponownie.

Zacznij z MailSMMO

Zarejestruj się za darmo, doładuj portfel i wynajmij pierwszą pocztę w kilka minut.

Załóż konto →