Email API

Připojte schránku a nechte asistenta tvořit nebo automaticky odesílat odpovědi s oporou v datech, řízené prahem jistoty. Předběžný přístup.

Na této stránce

Předběžný přístup / preview. Email API je dostupné vývojovým partnerům. Pole a endpointy se mohou před obecnou dostupností změnit.

Email API se připojuje přímo ke schránce — Gmail, Outlook nebo libovolný IMAP/SMTP účet — čte příchozí zprávy a tvoří návrhy odpovědí s oporou ve vašich znalostech. Každá odpověď nese skóre jistoty (confidence). Nastavíte práh automatického odeslání pro každou schránku: odpovědi na prahu nebo nad ním se odešlou automaticky, méně jisté se uloží jako návrh k lidské kontrole. Sdílí základní URL, Bearer autentizaci a formát chyb z přehledu API.

https://api.praktickai.app/v1/email

Jak to funguje

1. Jednou připojte schránku přes OAuth (Gmail/Outlook) nebo IMAP přihlašovací údaje.
2. Přijde příchozí e-mail; upozorníme váš server webhookem email.inbound.
3. Vy (nebo naše automatická linka) si vyžádáte návrh — odpověď s oporou v datech a skóre jistoty.
4. Pokud je jistota ≥ prahu autosend_threshold schránky, odpověď se odešle automaticky; jinak se uloží jako návrh.

Začněte s vysokým prahem (např. 0,9), aby téměř vše prošlo lidskou kontrolou, a snižujte ho, jak roste důvěra v návrhy.

Připojení schránky

POST /v1/email/mailboxes/

Připojte schránku, ze které bude asistent číst a jejím jménem odpovídat. U Gmailu a Outlooku předejte `provider` a dokončete vrácenou OAuth `authorization_url`; u ostatních serverů předejte IMAP/SMTP nastavení. Schránka drží pravidla pro automatické odesílání.

Parametr	Typ	Povinné	Popis
provider	string	ano	Jedno z `gmail`, `outlook` nebo `imap`.
address	string	ano	E-mailová adresa schránky, např. `support@acme.com`.
autosend_threshold	number	ne	Jistota (0–1), na které nebo nad níž se odpovědi odešlou automaticky. Výchozí `1.0` (nikdy automaticky — vždy jen návrh).
imap	object	podmíněně	Povinné, když je `provider` `imap`: `{ host, port, username, password }` pro čtení.
smtp	object	podmíněně	Povinné, když je `provider` `imap`: `{ host, port, username, password }` pro odesílání.

curl https://api.praktickai.app/v1/email/mailboxes/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gmail",
    "address": "support@acme.com",
    "autosend_threshold": 0.9
  }'

{
  "id": "mbx_a1b2c3",
  "provider": "gmail",
  "address": "support@acme.com",
  "status": "pending_authorization",
  "autosend_threshold": 0.9,
  "authorization_url": "https://admin.praktickai.app/oauth/gmail?state=mbx_a1b2c3",
  "created_at": "2026-07-16T09:12:00Z"
}

Pole	Typ	Popis
id	string	Identifikátor schránky s prefixem `mbx_`.
status	string	`pending_authorization`, `active` nebo `error`.
autosend_threshold	number	Jistota, na které nebo nad níž se odpovědi odešlou automaticky.
authorization_url	string	U OAuth poskytovatelů přítomná, dokud není schránka autorizována. Otevřete ji jednou pro udělení přístupu.

Udělte jen potřebná oprávnění. Pro automatizaci odpovědí stačí čtení + odesílání; asistent nikdy nemaže poštu. Přístup lze kdykoli odvolat v admin konzoli.

GET /v1/email/mailboxes/

Vypíše připojené schránky a jejich aktuální pravidla automatického odesílání.

{
  "data": [
    {
      "id": "mbx_a1b2c3",
      "address": "support@acme.com",
      "provider": "gmail",
      "status": "active",
      "autosend_threshold": 0.9
    }
  ]
}

Návrh odpovědi

POST /v1/email/draft/

Vygeneruje návrh odpovědi s oporou v datech na příchozí zprávu. Odpověď obsahuje navržené tělo, zdroje, o které se opírá, a skóre `confidence` mezi 0 a 1. Pokud je `confidence` na prahu `autosend_threshold` schránky nebo nad ním, odpověď se odešle a `action` je `sent`; jinak se uloží a `action` je `drafted`.

Parametr	Typ	Povinné	Popis
mailbox_id	string	ano	Schránka, pro kterou se odpověď tvoří.
message_id	string	podmíněně	Id příchozí zprávy, na kterou se odpovídá. Uveďte toto nebo `email`.
email	object	podmíněně	Surový příchozí e-mail `{ from, subject, body }`, pokud zprávu u nás nemáte uloženou.
instructions	string	ne	Doplňující pokyny k tónu či pravidlům, např. "stručně, nabídni hovor".

curl https://api.praktickai.app/v1/email/draft/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mailbox_id": "mbx_a1b2c3",
    "message_id": "msg_7788",
    "instructions": "Přátelsky, nejdřív nabídni návod pro samoobsluhu."
  }'

{
  "id": "drf_44aa",
  "mailbox_id": "mbx_a1b2c3",
  "in_reply_to": "msg_7788",
  "subject": "Re: Obnova hesla",
  "body": "Dobrý den Jano, heslo si obnovíte na přihlašovací obrazovce přes 'Zapomenuté heslo'. Zde je návod krok za krokem...",
  "confidence": 0.94,
  "action": "sent",
  "sources": [
    { "title": "Obnova hesla", "url": "https://help.acme.com/reset", "source_id": "src_notion_01" }
  ],
  "created_at": "2026-07-16T09:20:11Z"
}

Pole	Typ	Popis
id	string	Identifikátor návrhu s prefixem `drf_`.
body	string	Vygenerovaný text odpovědi.
confidence	number	Jistota modelu v odpověď, od 0 do 1.
action	string	`sent`, pokud je jistota ≥ prahu a odpověď byla odeslána, jinak `drafted`.
sources	array	Znalostní pasáže, o které se odpověď opírá — každá s `title`, `url` a `source_id`.
in_reply_to	string	Id příchozí zprávy, na kterou odpověď reaguje.

Když je `action` roven `drafted`, odpověď čeká ve schránce na lidskou kontrolu — nic se neodeslalo. Pouze `action: sent` znamená, že zákazník e-mail obdržel.

Odeslání e-mailu

POST /v1/email/send/

Odešle zprávu z připojené schránky. Použijte pro odeslání zkontrolovaného návrhu (předejte `draft_id`) nebo pro ad-hoc e-mail (předejte `to`, `subject`, `body`).

Parametr	Typ	Povinné	Popis
mailbox_id	string	ano	Schránka, ze které se odesílá.
draft_id	string	podmíněně	Odešle dříve vygenerovaný návrh beze změny nebo po úpravách.
to	string	podmíněně	Adresa příjemce při ad-hoc e-mailu.
subject	string	podmíněně	Předmět ad-hoc e-mailu.
body	string	podmíněně	Tělo ad-hoc e-mailu nebo upravené tělo návrhu.

curl https://api.praktickai.app/v1/email/send/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mailbox_id": "mbx_a1b2c3",
    "draft_id": "drf_44aa"
  }'

{
  "id": "msg_9001",
  "mailbox_id": "mbx_a1b2c3",
  "direction": "outbound",
  "status": "sent",
  "to": "jana@example.com",
  "subject": "Re: Obnova hesla",
  "created_at": "2026-07-16T09:21:03Z"
}

Načtení zprávy

GET /v1/email/messages/{id}/

Načte jednu příchozí či odchozí zprávu podle id, včetně těla a případně navázaného návrhu.

curl https://api.praktickai.app/v1/email/messages/msg_7788/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx"

{
  "id": "msg_7788",
  "mailbox_id": "mbx_a1b2c3",
  "direction": "inbound",
  "from": "jana@example.com",
  "subject": "Obnova hesla",
  "body": "Dobrý den, nemůžu se přihlásit a odkaz na obnovu nedorazil.",
  "received_at": "2026-07-16T09:18:44Z"
}

Webhooky

V admin konzoli zaregistrujte webhook endpoint a reagujte na e-mailové události. Každé doručení je podepsané; před důvěrou v payload ověřte hlavičku `PraktickAI-Signature` proti svému podpisovému tajemství.

Událost	Nastane, když
email.inbound	Do připojené schránky dorazí nová zpráva.
email.draft_created	Vytvoří se návrh s oporou v datech (pod prahem automatického odeslání).
email.outbound	Odešle se odpověď — automaticky nebo po kontrole.

{
  "type": "email.inbound",
  "created_at": "2026-07-16T09:18:45Z",
  "data": {
    "message_id": "msg_7788",
    "mailbox_id": "mbx_a1b2c3",
    "from": "jana@example.com",
    "subject": "Obnova hesla"
  }
}

Z webhooku rychle vraťte stav 2xx. Neúspěšná doručení opakujeme s exponenciálním odstupem až po dobu 24 hodin.