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/emailHow 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`. |
| 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.