Email API

Connect a mailbox and let the assistant draft or auto-send grounded replies, governed by a confidence threshold. Early access.

On this page

Early access / preview. The Email API is available to design partners. Fields and endpoints may change before general availability.

The Email API connects directly to a mailbox — Gmail, Outlook, or any IMAP/SMTP account — reads inbound messages, and produces grounded reply drafts using your connected knowledge. Every reply carries a confidence score. You set a per-mailbox auto-send threshold: replies at or above it are sent automatically, while less confident ones are saved as drafts for a human to review. It shares the base URL, Bearer authentication, and error format described in the API overview.

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

How it works

1. Connect a mailbox once via OAuth (Gmail/Outlook) or IMAP credentials.
2. An inbound email arrives; we notify your server with an email.inbound webhook.
3. You (or our automatic pipeline) request a draft — a grounded reply with a confidence score.
4. If confidence ≥ the mailbox autosend_threshold, the reply is sent automatically; otherwise it is saved as a draft.

Start with a high threshold (e.g. 0.9) so almost everything is reviewed by a human, then lower it as you build trust in the drafts.

Connect a mailbox

POST /v1/email/mailboxes/

Connect a mailbox the assistant will read from and reply on behalf of. For Gmail and Outlook, pass the `provider` and complete the returned OAuth `authorization_url`; for other servers, pass IMAP/SMTP settings. The mailbox stores the auto-send policy.

Parameter	Type	Required	Description
provider	string	yes	One of `gmail`, `outlook`, or `imap`.
address	string	yes	The email address of the mailbox, e.g. `support@acme.com`.
autosend_threshold	number	no	Confidence (0–1) at or above which replies are sent automatically. Default `1.0` (never auto-send — always draft).
imap	object	conditional	Required when `provider` is `imap`: `{ host, port, username, password }` for reading.
smtp	object	conditional	Required when `provider` is `imap`: `{ host, port, username, password }` for sending.

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"
}

Field	Type	Description
id	string	Mailbox identifier, prefixed `mbx_`.
status	string	`pending_authorization`, `active`, or `error`.
autosend_threshold	number	Confidence at or above which replies auto-send.
authorization_url	string	Present for OAuth providers until the mailbox is authorized. Open it once to grant access.

Grant only the scopes you need. Read + send is enough for reply automation; the assistant never deletes mail. Revoke access any time from the admin console.

GET /v1/email/mailboxes/

List connected mailboxes and their current auto-send policy.

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

Draft a reply

POST /v1/email/draft/

Generate a grounded reply draft for an inbound message. The response includes the drafted body, the sources it relied on, and a `confidence` score between 0 and 1. If `confidence` is at or above the mailbox `autosend_threshold`, the reply is dispatched and `action` is `sent`; otherwise it is stored and `action` is `drafted`.

Parameter	Type	Required	Description
mailbox_id	string	yes	The mailbox the reply is drafted for.
message_id	string	conditional	Id of the inbound message to reply to. Provide this or `email`.
email	object	conditional	Raw inbound email `{ from, subject, body }` if you have not stored the message with us.
instructions	string	no	Extra guidance for tone or policy, e.g. "be concise, offer a call".

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": "Friendly, offer the self-service guide first."
  }'

{
  "id": "drf_44aa",
  "mailbox_id": "mbx_a1b2c3",
  "in_reply_to": "msg_7788",
  "subject": "Re: Password reset",
  "body": "Hi Jana, you can reset your password from the login screen using 'Forgot password'. Here is the step-by-step guide...",
  "confidence": 0.94,
  "action": "sent",
  "sources": [
    { "title": "Resetting your password", "url": "https://help.acme.com/reset", "source_id": "src_notion_01" }
  ],
  "created_at": "2026-07-16T09:20:11Z"
}

Field	Type	Description
id	string	Draft identifier, prefixed `drf_`.
body	string	The generated reply text.
confidence	number	Model confidence in the reply, from 0 to 1.
action	string	`sent` if confidence ≥ threshold and the reply was dispatched, otherwise `drafted`.
sources	array	Knowledge passages the reply was grounded in — each with `title`, `url`, and `source_id`.
in_reply_to	string	The inbound message id this reply answers.

When `action` is `drafted`, the reply is waiting in the mailbox for human review — nothing was sent. Only `action: sent` means the customer received an email.

Send an email

POST /v1/email/send/

Send a message from a connected mailbox. Use this to dispatch a reviewed draft (pass `draft_id`) or to send an ad-hoc email (pass `to`, `subject`, `body`).

Parameter	Type	Required	Description
mailbox_id	string	yes	The mailbox to send from.
draft_id	string	conditional	Send a previously generated draft as-is or after edits.
to	string	conditional	Recipient address when sending an ad-hoc email.
subject	string	conditional	Subject line for an ad-hoc email.
body	string	conditional	Body for an ad-hoc email or an edited draft body.

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: Password reset",
  "created_at": "2026-07-16T09:21:03Z"
}

Retrieve a message

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

Fetch a single inbound or outbound message by id, including its body and any linked draft.

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": "Password reset",
  "body": "Hi, I can't log in and the reset link isn't arriving.",
  "received_at": "2026-07-16T09:18:44Z"
}

Webhooks

Register a webhook endpoint in the admin console to react to email events. Each delivery is signed; verify the `PraktickAI-Signature` header against your signing secret before trusting the payload.

Event	Fires when
email.inbound	A new message arrives in a connected mailbox.
email.draft_created	A grounded draft is generated (below the auto-send threshold).
email.outbound	A reply is sent — automatically or after review.

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

Return a 2xx status quickly from your webhook. We retry failed deliveries with exponential backoff for up to 24 hours.