{ "openapi": "3.1.0", "info": { "title": "Lumbox API", "version": "1.0.0", "summary": "Email infrastructure for AI agents.", "description": "Lumbox gives AI agents real email addresses with automatic OTP extraction, IMAP access, and a REST API. One POST to create an inbox, one GET to retrieve an OTP code.\n\n## Authentication\nEvery request requires an API key. Send it as the `X-API-Key` header (preferred) or as `Authorization: Bearer `. Create a key at https://app.lumbox.co/settings/api-keys. OAuth 2.1 (authorization code + PKCE, and client credentials for machine-to-machine) is also supported with the scopes `inbox:read`, `inbox:write`, `email:read`, `email:send`, `domain:manage` — see /.well-known/oauth-authorization-server.\n\n## Versioning\nThe API is versioned in the URL path (`/v1`). Breaking changes ship under a new path prefix; additive changes do not. The current stable version is `v1`. Deprecated operations are announced ahead of removal with `Deprecation: true` and `Sunset: ` response headers plus a changelog notice.\n\n## Rate limits\nDefault 120 requests/minute per API key (per IP for unauthenticated routes). Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (unix seconds). Exceeding the limit returns `429` with `{ \"error\": \"...\", \"retry_after_seconds\": N }`.\n\n## Errors\nAll errors return JSON of the shape `{ \"error\": \"\" }` with the appropriate HTTP status (400, 401, 403, 404, 429, 5xx). Long-poll endpoints (`/wait`, `/otp`) are safe to retry.\n\n## Pagination\nList endpoints that can grow unbounded use opaque cursor pagination: pass `?limit=` and `?cursor=`; the response includes `data[]`, `cursor` (pass back as the next `cursor`, or `null` when exhausted), and `has_more`.\n\n## Webhooks\nWebhook deliveries are signed with HMAC-SHA256 over the raw request body using your endpoint's signing secret; verify the hex digest in the `X-Lumbox-Signature` header before trusting a payload.", "contact": { "name": "Lumbox Support", "email": "support@lumbox.co", "url": "https://lumbox.co" }, "license": { "name": "Proprietary", "url": "https://lumbox.co/privacy" }, "termsOfService": "https://lumbox.co/privacy" }, "externalDocs": { "description": "Full API reference", "url": "https://docs.lumbox.co/docs/api-reference" }, "servers": [ { "url": "https://api.lumbox.co/v1", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, { "OAuth2": [ "inbox:read", "inbox:write", "email:read", "email:send", "domain:manage" ] } ], "tags": [ { "name": "Inboxes", "description": "Create and manage agent email inboxes." }, { "name": "Emails", "description": "Read received email and the parsed data extracted from it." }, { "name": "OTP", "description": "Long-poll for verification codes and arriving email." }, { "name": "Sending", "description": "Send, reply, forward, and bulk-send email." }, { "name": "Threads", "description": "List conversation threads." }, { "name": "Domains", "description": "Bring your own sending domain." }, { "name": "Webhooks", "description": "Receive signed event callbacks." }, { "name": "Agent Tasks", "description": "Asynchronous agent jobs you create then poll." }, { "name": "Q&A", "description": "Retrieval-augmented questions over your inboxes." } ], "paths": { "/inboxes": { "post": { "operationId": "createInbox", "tags": [ "Inboxes" ], "summary": "Create an inbox", "description": "Creates a new email inbox and returns its address plus IMAP credentials.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "inbox:write" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInboxRequest" }, "example": { "name": "github-bot" } } } }, "responses": { "201": { "description": "Inbox created", "headers": { "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "default": { "$ref": "#/components/responses/Error" } } }, "get": { "operationId": "listInboxes", "tags": [ "Inboxes" ], "summary": "List inboxes", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "inbox:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of inboxes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxPage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{id}": { "parameters": [ { "$ref": "#/components/parameters/InboxId" } ], "get": { "operationId": "getInbox", "tags": [ "Inboxes" ], "summary": "Get an inbox", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "inbox:read" ] } ], "responses": { "200": { "description": "The inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateInbox", "tags": [ "Inboxes" ], "summary": "Update an inbox", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "inbox:write" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboxRequest" } } } }, "responses": { "200": { "description": "Updated inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "deleteInbox", "tags": [ "Inboxes" ], "summary": "Delete an inbox", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "inbox:write" ] } ], "responses": { "204": { "description": "Deleted" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{id}/emails": { "parameters": [ { "$ref": "#/components/parameters/InboxId" } ], "get": { "operationId": "listEmails", "tags": [ "Emails" ], "summary": "List received emails", "description": "Returns a cursor-paginated list of received emails with their parsed data (OTP codes, links, category).", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "email:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "Filter by sender substring." }, { "name": "category", "in": "query", "schema": { "$ref": "#/components/schemas/EmailCategory" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "unread", "in": "query", "schema": { "type": "boolean" } }, { "name": "include_spam", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A page of emails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailPage" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{id}/emails/{emailId}": { "parameters": [ { "$ref": "#/components/parameters/InboxId" }, { "name": "emailId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getEmail", "tags": [ "Emails" ], "summary": "Get a single email", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "email:read" ] } ], "responses": { "200": { "description": "The email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{id}/wait": { "parameters": [ { "$ref": "#/components/parameters/InboxId" } ], "get": { "operationId": "waitForEmail", "tags": [ "OTP" ], "summary": "Long-poll until an email arrives", "description": "Blocks the connection until a new email arrives or `timeout` seconds elapse. Safe to retry.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "email:read" ] } ], "parameters": [ { "name": "timeout", "in": "query", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 120 }, "description": "Seconds to block before returning." } ], "responses": { "200": { "description": "The email that arrived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } }, "204": { "description": "Timed out with no new email." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{id}/otp": { "parameters": [ { "$ref": "#/components/parameters/InboxId" } ], "get": { "operationId": "waitForOtp", "tags": [ "OTP" ], "summary": "Long-poll until an OTP code arrives", "description": "Blocks until an email containing an OTP/verification code arrives, then returns just the parsed code. No polling loop required.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "email:read" ] } ], "parameters": [ { "name": "timeout", "in": "query", "schema": { "type": "integer", "default": 60, "minimum": 1, "maximum": 120 } } ], "responses": { "200": { "description": "Parsed OTP", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpResult" }, "example": { "code": "847291", "from": "noreply@github.com" } } } }, "204": { "description": "Timed out with no OTP." }, "default": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{id}/send": { "parameters": [ { "$ref": "#/components/parameters/InboxId" } ], "post": { "operationId": "sendEmail", "tags": [ "Sending" ], "summary": "Send an email", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "email:send" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendRequest" } } } }, "responses": { "200": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{id}/reply": { "parameters": [ { "$ref": "#/components/parameters/InboxId" } ], "post": { "operationId": "replyToEmail", "tags": [ "Sending" ], "summary": "Reply to an email with threading headers", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "email:send" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyRequest" } } } }, "responses": { "200": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{id}/forward": { "parameters": [ { "$ref": "#/components/parameters/InboxId" } ], "post": { "operationId": "forwardEmail", "tags": [ "Sending" ], "summary": "Forward an email", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "email:send" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardRequest" } } } }, "responses": { "200": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResult" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/send/bulk": { "post": { "operationId": "sendBulk", "tags": [ "Sending" ], "summary": "Bulk-send up to 100 emails", "description": "Batch endpoint: submit up to 100 messages in a single request.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "email:send" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSendRequest" } } } }, "responses": { "200": { "description": "Per-message results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSendResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/threads": { "get": { "operationId": "listThreads", "tags": [ "Threads" ], "summary": "List email threads", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "email:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A page of threads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadPage" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/domains": { "post": { "operationId": "addDomain", "tags": [ "Domains" ], "summary": "Add a custom domain", "description": "Adds a sending domain and returns the DKIM/SPF/DMARC DNS records to create.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "domain:manage" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddDomainRequest" } } } }, "responses": { "201": { "description": "Domain added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "get": { "operationId": "listDomains", "tags": [ "Domains" ], "summary": "List domains", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "domain:manage" ] } ], "responses": { "200": { "description": "Domains", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/domains/{id}/verify": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "verifyDomain", "tags": [ "Domains" ], "summary": "Verify a domain's DNS records", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "domain:manage" ] } ], "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Webhooks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createWebhook", "tags": [ "Webhooks" ], "summary": "Create a webhook endpoint", "description": "Registers a URL to receive events. The response includes a `secret` (shown once) used to verify the `X-Lumbox-Signature` HMAC-SHA256 header on each delivery.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithSecret" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/webhooks/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint", "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "Deleted" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/agent-tasks": { "post": { "operationId": "createAgentTask", "tags": [ "Agent Tasks" ], "summary": "Start an asynchronous agent task", "description": "Async job pattern: returns immediately with a task `id` and `status` of `pending`. Poll `GET /agent-tasks/{id}` until `status` is `completed` or `failed`.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentTaskRequest" } } } }, "responses": { "202": { "description": "Task accepted. Poll the URL in the Location header until status is completed or failed.", "headers": { "Location": { "description": "Absolute URL of the created job to poll with GET.", "schema": { "type": "string", "format": "uri" }, "example": "https://api.lumbox.co/v1/agent-tasks/at_8hvo0m3" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTask" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "get": { "operationId": "listAgentTasks", "tags": [ "Agent Tasks" ], "summary": "List agent tasks", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Tasks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTaskPage" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/agent-tasks/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "getAgentTask", "tags": [ "Agent Tasks" ], "summary": "Poll an agent task", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Current task state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTask" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/ask": { "post": { "operationId": "askInboxes", "tags": [ "Q&A" ], "summary": "Ask a question over your inboxes (RAG)", "description": "Retrieval-augmented Q&A across the organization's emails. Requires a configured BYOK LLM and embeddings provider.", "security": [ { "ApiKeyAuth": [] }, { "OAuth2": [ "email:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskRequest" } } } }, "responses": { "200": { "description": "Answer with citations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "default": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Lumbox API key." }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key or OAuth access token as a bearer credential." }, "OAuth2": { "type": "oauth2", "description": "OAuth 2.1 with PKCE.", "flows": { "authorizationCode": { "authorizationUrl": "https://api.lumbox.co/oauth/authorize", "tokenUrl": "https://api.lumbox.co/oauth/token", "refreshUrl": "https://api.lumbox.co/oauth/token", "scopes": { "inbox:read": "Read inbox metadata", "inbox:write": "Create, update, and delete inboxes", "email:read": "Read received email and parsed data", "email:send": "Send, reply, and forward email", "domain:manage": "Add and verify custom domains" } }, "clientCredentials": { "tokenUrl": "https://api.lumbox.co/oauth/token", "scopes": { "inbox:read": "Read inbox metadata", "inbox:write": "Create, update, and delete inboxes", "email:read": "Read received email and parsed data", "email:send": "Send, reply, and forward email", "domain:manage": "Add and verify custom domains" } } } } }, "parameters": { "InboxId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Inbox id (e.g. `inb_...`)." }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Max items to return." }, "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque pagination cursor from the previous page." } }, "headers": { "RateLimitLimit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Unix seconds when the window resets.", "schema": { "type": "integer" } } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key.", "headers": { "WWW-Authenticate": { "description": "Points at the protected-resource metadata.", "schema": { "type": "string" }, "example": "Bearer resource_metadata=\"https://lumbox.co/.well-known/oauth-protected-resource\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid API key" } } } }, "BadRequest": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Missing required fields: to, subject" } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Inbox not found" } } } }, "RateLimited": { "description": "Rate limit exceeded.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "example": { "error": "Rate limit exceeded. Try again later.", "retry_after_seconds": 42 } } } }, "Error": { "description": "Unexpected error. All errors share the typed Error schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "description": "Standard error envelope returned for every non-2xx response.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable error message." } } }, "RateLimitError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "retry_after_seconds": { "type": "integer" } } } ] }, "EmailCategory": { "type": "string", "enum": [ "verification", "security", "transactional", "notification", "newsletter", "conversation", "calendar" ] }, "CreateInboxRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Friendly handle; becomes the local-part of the address." }, "domain": { "type": "string", "description": "Optional custom domain to create the address on." } } }, "UpdateInboxRequest": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED" ] } } }, "Inbox": { "type": "object", "properties": { "id": { "type": "string", "example": "inb_8hvo0m3PpDY1" }, "address": { "type": "string", "format": "email", "example": "github-bot@lumbox.co" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED" ] }, "imap_host": { "type": "string", "example": "imap.lumbox.co" }, "imap_password": { "type": "string", "description": "Returned only on creation." }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "address" ] }, "InboxPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Inbox" } }, "cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "has_more" ] }, "Email": { "type": "object", "properties": { "id": { "type": "string", "example": "eml_5f2a9c" }, "from": { "type": "string", "format": "email" }, "to": { "type": "string", "format": "email" }, "subject": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string" }, "category": { "$ref": "#/components/schemas/EmailCategory" }, "parsed": { "$ref": "#/components/schemas/ParsedData" }, "is_read": { "type": "boolean" }, "received_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "from", "received_at" ] }, "ParsedData": { "type": "object", "description": "Structured data extracted from the email by Lumbox.", "properties": { "otp": { "type": [ "string", "null" ], "example": "847291" }, "verification_link": { "type": [ "string", "null" ], "format": "uri" }, "magic_link": { "type": [ "string", "null" ], "format": "uri" }, "backup_codes": { "type": "array", "items": { "type": "string" } }, "code_expiry": { "type": [ "string", "null" ], "format": "date-time" } } }, "EmailPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } }, "cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "has_more" ] }, "OtpResult": { "type": "object", "properties": { "code": { "type": "string", "example": "847291" }, "from": { "type": "string", "format": "email" }, "email_id": { "type": "string" } }, "required": [ "code" ] }, "SendRequest": { "type": "object", "required": [ "to", "subject" ], "properties": { "to": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" } } ] }, "subject": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string" }, "cc": { "type": "array", "items": { "type": "string", "format": "email" } }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" } } } }, "ReplyRequest": { "type": "object", "required": [ "email_id" ], "properties": { "email_id": { "type": "string", "description": "Id of the email being replied to (sets In-Reply-To/References)." }, "text": { "type": "string" }, "html": { "type": "string" } } }, "ForwardRequest": { "type": "object", "required": [ "email_id", "to" ], "properties": { "email_id": { "type": "string" }, "to": { "type": "string", "format": "email" }, "text": { "type": "string" } } }, "SendResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Message id, usable as `email_id` in a later reply." }, "status": { "type": "string", "enum": [ "sent", "queued" ] } } }, "BulkSendRequest": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "maxItems": 100, "items": { "allOf": [ { "$ref": "#/components/schemas/SendRequest" }, { "type": "object", "properties": { "from_inbox_id": { "type": "string" } }, "required": [ "from_inbox_id" ] } ] } } } }, "BulkSendResult": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "sent", "queued", "failed" ] }, "error": { "type": "string" } } } } } }, "Thread": { "type": "object", "properties": { "id": { "type": "string" }, "subject": { "type": "string" }, "participants": { "type": "array", "items": { "type": "string", "format": "email" } }, "message_count": { "type": "integer" }, "last_message_at": { "type": "string", "format": "date-time" } } }, "ThreadPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Thread" } }, "cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "AddDomainRequest": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "mail.acme.com" } } }, "Domain": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "verified": { "type": "boolean" }, "dns_records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TXT", "MX", "CNAME" ] }, "name": { "type": "string" }, "value": { "type": "string" } } } } } }, "CreateWebhookRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "email.received", "email.sent", "otp.extracted" ] } } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } } } }, "WebhookWithSecret": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "HMAC signing secret; shown once. Verify X-Lumbox-Signature with it." } } } ] }, "CreateAgentTaskRequest": { "type": "object", "required": [ "instruction" ], "properties": { "instruction": { "type": "string", "description": "Natural-language task for the agent to perform against an inbox." }, "inbox_id": { "type": "string" } } }, "AgentTask": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "result": { "type": [ "object", "null" ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "status" ] }, "AgentTaskPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTask" } }, "cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "AskRequest": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string" }, "inbox_id": { "type": "string", "description": "Optional: restrict retrieval to one inbox." }, "k": { "type": "integer", "description": "Number of emails to retrieve.", "default": 8 } } }, "AskResponse": { "type": "object", "properties": { "answer": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "email_id": { "type": "string" }, "subject": { "type": "string" }, "from": { "type": "string" } } } } } } } } }