{ "openapi": "3.1.0", "info": { "title": "ChatTempMail API", "version": "1.0.0", "description": "Temporary email with AI superpowers. Create disposable email addresses, receive mail, and process messages (summarize, translate, Q&A, code/link extraction) via a simple REST API.\n\n## Authentication\nAll endpoints require an API key. Create one on your Profile page (https://chat-tempmail.com/en/profile) and send it as `X-API-Key: ` or `Authorization: Bearer `. API keys carry the same permissions as your account.\n\n## When to use this API\nUse ChatTempMail when an agent or script needs a disposable inbox: signup verification codes, one-time downloads, testing email flows, or avoiding spam. Do not use it for long-term correspondence — addresses expire.", "contact": { "name": "ChatTempMail Support", "url": "https://chat-tempmail.com/en/contact", "email": "openminimax@gmail.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://chat-tempmail.com", "description": "Production" } ], "externalDocs": { "description": "API documentation & llms.txt", "url": "https://chat-tempmail.com/en/api-docs" }, "tags": [ { "name": "Domains", "description": "Available email domains" }, { "name": "Emails", "description": "Disposable email address lifecycle" }, { "name": "Messages", "description": "Messages received by an email address" }, { "name": "Webhooks", "description": "Push notifications for new messages" } ], "paths": { "/api/email/domains": { "get": { "operationId": "listEmailDomains", "tags": [ "Domains" ], "summary": "List available email domains", "description": "Returns the list of domains a temporary email address can be created on.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Domain list", "content": { "application/json": { "schema": { "type": "object", "required": [ "domains" ], "properties": { "domains": { "type": "array", "items": { "type": "string", "format": "hostname" }, "examples": [ "chat-tempmail.com" ] } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/emails/generate": { "post": { "operationId": "createEmail", "tags": [ "Emails" ], "summary": "Create a temporary email address", "description": "Creates a new disposable email address under the authenticated account. Permanent addresses (expiryTime 0) and quota limits depend on your account role.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmailRequest" }, "examples": { "basic": { "summary": "One-hour address", "value": { "name": "test", "expiryTime": 3600000, "domain": "chat-tempmail.com" } } } } } }, "responses": { "200": { "description": "Created email address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailCreated" } } } }, "400": { "description": "Invalid expiry time or domain (expiryTime must be one of 3600000, 86400000, 259200000, 0; domain must be from listEmailDomains)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Email quota reached for your account role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Address already taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/emails": { "get": { "operationId": "listEmails", "tags": [ "Emails" ], "summary": "List email addresses", "description": "Lists active email addresses owned by the account, most recent first. Paginated: 20 items per page; pass nextCursor to fetch the next page.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response nextCursor", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Filter addresses by substring (case-insensitive)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated email list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailList" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/emails/{emailId}": { "get": { "operationId": "listMessages", "tags": [ "Messages" ], "summary": "List messages received by an email address", "description": "Returns messages for the given email address, newest first, 20 per page. Poll this endpoint or configure a webhook to get pushed on arrival.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "emailId", "in": "path", "required": true, "description": "Email address ID (UUID) from createEmail/listEmails", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor from a previous response nextCursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated message list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Email address not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteEmail", "tags": [ "Emails" ], "summary": "Delete an email address", "description": "Permanently deletes the address and all messages received on it.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "emailId", "in": "path", "required": true, "description": "Email address ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deletion acknowledged", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Email address not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/emails/{emailId}/{messageId}": { "get": { "operationId": "getMessage", "tags": [ "Messages" ], "summary": "Get message details", "description": "Returns the full message: subject, sender, recipients, plain text, HTML, received time, and attachment metadata (if any).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "emailId", "in": "path", "required": true, "description": "Email address ID (UUID)", "schema": { "type": "string", "format": "uuid" } }, { "name": "messageId", "in": "path", "required": true, "description": "Message ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Message detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Email address not owned by this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/emails/{emailId}/{messageId}/...": { "description": "AI operations share the message detail path pattern: /summarize, /translate, /qa, /extract-code, /extract-links. See /en/api-docs for request bodies; they require a paid plan." }, "/api/webhook": { "get": { "operationId": "getWebhookConfig", "tags": [ "Webhooks" ], "summary": "Get webhook configuration", "description": "Returns the current webhook target for new-message push notifications.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Current webhook configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfig" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "updateWebhookConfig", "tags": [ "Webhooks" ], "summary": "Configure the webhook", "description": "Sets or updates the URL that receives new-message push notifications. The target must respond 2xx; failed deliveries are retried, keep the endpoint idempotent.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfig" }, "examples": { "basic": { "summary": "Enable a webhook", "value": { "url": "https://your-server.com/webhook", "enabled": true } } } } } }, "responses": { "200": { "description": "Configuration saved", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Invalid URL or missing enabled flag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key created on the Profile page. Equivalent: Authorization: Bearer ." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Stable error code, e.g. UNAUTHORIZED, EMAIL_INVALID_DOMAIN" }, "message": { "type": "string", "description": "Human-readable explanation (locale-dependent)" } } }, "CreateEmailRequest": { "type": "object", "required": [ "expiryTime", "domain" ], "properties": { "name": { "type": "string", "description": "Local part of the address. Omit or empty to get a random 8-char name.", "examples": [ "test" ] }, "expiryTime": { "type": "integer", "format": "int64", "description": "Lifetime in milliseconds. Allowed: 3600000 (1h), 86400000 (1d), 259200000 (3d), 0 (permanent, role-gated).", "enum": [ 3600000, 86400000, 259200000, 0 ] }, "domain": { "type": "string", "description": "Domain from listEmailDomains", "examples": [ "chat-tempmail.com" ] } } }, "EmailCreated": { "type": "object", "required": [ "id", "email" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Email address ID" }, "email": { "type": "string", "format": "email", "description": "Full email address" } } }, "Email": { "type": "object", "required": [ "id", "address", "userId", "createdAt", "expiresAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "address": { "type": "string", "format": "email" }, "userId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "description": "9999-01-01 for permanent addresses" } } }, "EmailList": { "type": "object", "required": [ "emails", "total" ], "properties": { "emails": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/Email" } }, "nextCursor": { "type": "string", "description": "Cursor for the next page; absent on the last page" }, "total": { "type": "integer", "description": "Total matching addresses" } } }, "MessageListItem": { "type": "object", "required": [ "id", "from_address", "subject", "received_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "from_address": { "type": "string", "description": "Sender address" }, "subject": { "type": "string" }, "received_at": { "type": "integer", "format": "int64", "description": "Received time, Unix epoch milliseconds" } } }, "MessageList": { "type": "object", "required": [ "messages", "total" ], "properties": { "messages": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/MessageListItem" } }, "nextCursor": { "type": "string", "description": "Cursor for the next page; absent on the last page" }, "total": { "type": "integer" } } }, "Attachment": { "type": "object", "required": [ "id", "filename", "size" ], "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer", "description": "Size in bytes" }, "contentType": { "type": "string" }, "url": { "type": "string", "description": "Download URL (may be a short-lived signed URL)" } } }, "Message": { "type": "object", "required": [ "id", "emailId", "from_address", "subject", "received_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "emailId": { "type": "string", "format": "uuid" }, "from_address": { "type": "string" }, "to_address": { "type": "string" }, "subject": { "type": "string" }, "content": { "type": "string", "description": "Plain text body" }, "html": { "type": "string", "description": "HTML body, may be empty" }, "received_at": { "type": "integer", "format": "int64", "description": "Unix epoch milliseconds" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } } } }, "WebhookConfig": { "type": "object", "required": [ "url", "enabled" ], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS URL that receives new-message POST notifications" }, "enabled": { "type": "boolean" } } }, "WebhookEvent": { "type": "object", "required": [ "emailId", "messageId", "fromAddress", "subject", "receivedAt", "toAddress" ], "properties": { "emailId": { "type": "string", "format": "uuid" }, "messageId": { "type": "string", "format": "uuid" }, "fromAddress": { "type": "string" }, "subject": { "type": "string" }, "content": { "type": "string" }, "html": { "type": "string" }, "receivedAt": { "type": "string", "format": "date-time" }, "toAddress": { "type": "string", "format": "email" } } } } } }