API

Prístup k schránkam zo skriptov a testov

Pre AI agentov

Skopírujte agentovi tento návod – bude vedieť použiť ľubovoľnú adresu @goinbox.sk a sám si prečítať prijatú poštu. Ten istý text je aj na goinbox.sk/llms.txt.

Zobraziť prompt

Na overovacie e-maily (registrácie, potvrdzovacie kódy, odkazy na stiahnutie) môžeš použiť dočasnú schránku GoInbox.

1. Vymysli si adresu v tvare <nazov>@goinbox.sk. Schránku netreba zakladať – stačí ju zadať do formulára.
   - názov: malé písmená a-z, číslice, bodka, pomlčka, podčiarkovník; začína aj končí písmenom alebo číslicou
   - použi dlhý náhodný názov (napr. agent-7f3k9q2m), schránky sú verejné a ktokoľvek, kto pozná adresu, ich môže čítať
   - vyhradené názvy (admin, postmaster, webmaster, root, info …) nefungujú
2. Poštu si prečítaj cez API (JSON, bez kľúča):
   GET https://goinbox.sk/api/inbox/<adresa>       → zoznam e-mailov, najnovšie prvé (pole "emails", "pagination.totalEmails")
   GET https://goinbox.sk/api/email/<id>           → jeden e-mail (from, subject, text, html, receivedAt)
3. Keď čakáš na e-mail, kontroluj schránku každých 10 sekúnd najviac 2–3 minúty. Overovací kód alebo odkaz nájdeš v poli "text" (prípadne "html").
4. Limity na IP: 120 požiadaviek za minútu a 15 rôznych schránok za hodinu (pri prekročení HTTP 429 s hlavičkou Retry-After). E-maily väčšie ako 1 MB a prílohy sa neprijímajú; jedna schránka pojme najviac 10 MB. Každý e-mail sa sám vymaže 60 minút po doručení.
5. Nepoužívaj schránku na hromadné zakladanie účtov, obchádzanie ochrany iných služieb ani na nič citlivé.

Dokumentácia API: https://goinbox.sk/dokumentacia/api

Úvod

GoInbox má jednoduché REST API, cez ktoré si môžete prečítať poštu dočasnej schránky – napríklad keď automaticky testujete registráciu vo vlastnej aplikácii. API slúži len na čítanie, nevyžaduje kľúč, odpovede sú v JSON a adresa API je https://goinbox.sk/api. Schránku netreba zakladať: stačí poslať e-mail na ľubovoľnú povolenú adresu @goinbox.sk.

Endpointy

GET /api/inbox/{adresa}?page=1&limit=10

Zoznam e-mailov v schránke, najnovšie prvé. limit je najviac 50. Pole expiresIn udáva počet sekúnd do zániku schránky (alebo null, ak je prázdna).

curl https://goinbox.sk/api/inbox/rychly.sokol42@goinbox.sk

{
  "emails": [
    {
      "id": "7762a07930ed4034951a",
      "to": "rychly.sokol42@goinbox.sk",
      "from": "noreply@example.com",
      "subject": "Váš overovací kód",
      "text": "Váš kód je 482 913.",
      "html": "",
      "headers": { "subject": "Váš overovací kód", "...": "..." },
      "receivedAt": "2026-11-07T09:25:23.114Z"
    }
  ],
  "expiresIn": 3541,
  "pagination": { "page": 1, "limit": 10, "totalEmails": 1, "totalPages": 1, "hasMore": false }
}

GET /api/email/{id}

Jeden e-mail podľa id zo zoznamu.

curl https://goinbox.sk/api/email/7762a07930ed4034951a

Mazať cez API nie je potrebné – každý e-mail sa sám vymaže 60 minút po doručení.

Príklad: počkať na overovací kód

ADDR="test.$(date +%s)@goinbox.sk"
# ... zaregistrujte sa vo svojej aplikácii s adresou $ADDR ...
for i in $(seq 1 12); do
  BODY=$(curl -s https://goinbox.sk/api/inbox/$ADDR)
  echo "$BODY" | grep -q '"totalEmails":0' || { echo "$BODY"; break; }
  sleep 10
done

Limity

Limity platia pre každú IP adresu spoločne pre web aj API:

120 požiadaviek za minútu.
15 rôznych schránok za hodinu – ochrana pred prehľadávaním cudzích schránok. K schránke, ktorú ste už otvorili, sa môžete vracať bez obmedzenia.

Každá odpoveď obsahuje hlavičky RateLimit-Limit, RateLimit-Remaining a RateLimit-Reset (sekundy). Po prekročení limitu príde 429 s hlavičkou Retry-After. API je určené na volanie zo serverov a skriptov – z cudzích webov v prehliadači ho volať nemožno (CORS nie je povolený).

Chyby

Chybová odpoveď má tvar {"error": "…", "code": "…"}:

HTTP	code	Význam
400	invalid_address	iná doména alebo nepovolené znaky v názve
403	reserved_address	vyhradený názov (admin@, postmaster@ …)
404	not_found	e-mail neexistuje, už bol vymazaný, alebo neexistujúci endpoint
429	rate_limited	priveľa požiadaviek za minútu
429	inbox_limit	priveľa rôznych schránok za hodinu

Pravidlá používania

API slúži na testovanie a osobné použitie. Je zakázané používať ho na hromadné zakladanie účtov v cudzích službách, obchádzanie ich ochrany či rozosielanie spamu. Pri zneužívaní môžeme prístup z konkrétnych IP adries obmedziť. Platia podmienky používania.