{
    "openapi": "3.1.0",
    "info": {
        "title": "email.singles API",
        "version": "1.0.0",
        "description": "Email inboxes for AI agents: create an address instantly, receive mail as JSON with extracted codes and links, send mail. 25 MB storage per inbox. Human/LLM guide: https://email.singles/llms.txt"
    },
    "servers": [
        {
            "url": "https://email.singles"
        }
    ],
    "security": [
        {
            "bearer": []
        }
    ],
    "paths": {
        "/v1/signup": {
            "post": {
                "operationId": "signup",
                "summary": "Create an account and get an API key",
                "security": [],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "contact_email": {
                                        "type": "string",
                                        "format": "email"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "API key (shown once)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean"
                                        },
                                        "api_key": {
                                            "type": "string"
                                        },
                                        "limits": {
                                            "type": "object"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/me": {
            "get": {
                "operationId": "getAccount",
                "summary": "Account usage and limits",
                "responses": {
                    "200": {
                        "description": "Account",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean"
                                        },
                                        "account": {
                                            "type": "object"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/inboxes": {
            "post": {
                "operationId": "createInbox",
                "summary": "Create an inbox (email address)",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "username": {
                                        "type": "string",
                                        "description": "Desired local part; omit for a random one"
                                    },
                                    "name": {
                                        "type": "string",
                                        "description": "Display name used when sending"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean"
                                        },
                                        "inbox": {
                                            "$ref": "#/components/schemas/Inbox"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "get": {
                "operationId": "listInboxes",
                "summary": "List inboxes",
                "responses": {
                    "200": {
                        "description": "Inboxes",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean"
                                        },
                                        "inboxes": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Inbox"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/inboxes/{address}": {
            "get": {
                "operationId": "getInbox",
                "summary": "Get inbox and storage usage",
                "parameters": [
                    {
                        "name": "address",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Full address (bob@email.singles) or just the local part (bob)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Inbox",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean"
                                        },
                                        "inbox": {
                                            "$ref": "#/components/schemas/Inbox"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "operationId": "deleteInbox",
                "summary": "Delete inbox and all messages",
                "parameters": [
                    {
                        "name": "address",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Full address (bob@email.singles) or just the local part (bob)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Deleted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/inboxes/{address}/wait": {
            "get": {
                "operationId": "waitForEmail",
                "summary": "Long-poll until the next email arrives; returns the full message (null on timeout)",
                "parameters": [
                    {
                        "name": "address",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Full address (bob@email.singles) or just the local part (bob)."
                    },
                    {
                        "name": "timeout",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 50,
                            "default": 30
                        }
                    },
                    {
                        "name": "after",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Return first received message newer than this id; default = oldest unread"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Message or null",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "oneOf": [
                                                {
                                                    "$ref": "#/components/schemas/Message"
                                                },
                                                {
                                                    "type": "null"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/inboxes/{address}/messages": {
            "get": {
                "operationId": "listMessages",
                "summary": "List messages (newest first)",
                "parameters": [
                    {
                        "name": "address",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Full address (bob@email.singles) or just the local part (bob)."
                    },
                    {
                        "name": "direction",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "received",
                                "sent"
                            ]
                        }
                    },
                    {
                        "name": "unread",
                        "in": "query",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "after",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 20
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Messages",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean"
                                        },
                                        "messages": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/MessageSummary"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/inboxes/{address}/messages/{id}": {
            "get": {
                "operationId": "getMessage",
                "summary": "Get full message (marks read)",
                "parameters": [
                    {
                        "name": "address",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Full address (bob@email.singles) or just the local part (bob)."
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Message id (msg_...)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Message",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "$ref": "#/components/schemas/Message"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "operationId": "deleteMessage",
                "summary": "Delete message",
                "parameters": [
                    {
                        "name": "address",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Full address (bob@email.singles) or just the local part (bob)."
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Message id (msg_...)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Deleted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/inboxes/{address}/messages/{id}/raw": {
            "get": {
                "operationId": "getRawMessage",
                "summary": "Original .eml source",
                "parameters": [
                    {
                        "name": "address",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Full address (bob@email.singles) or just the local part (bob)."
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Message id (msg_...)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "message/rfc822"
                    }
                }
            }
        },
        "/v1/inboxes/{address}/messages/{id}/attachments/{index}": {
            "get": {
                "operationId": "getAttachment",
                "summary": "Download attachment",
                "parameters": [
                    {
                        "name": "address",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Full address (bob@email.singles) or just the local part (bob)."
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Message id (msg_...)."
                    },
                    {
                        "name": "index",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Binary file"
                    }
                }
            }
        },
        "/v1/inboxes/{address}/send": {
            "post": {
                "operationId": "sendEmail",
                "summary": "Send an email from this inbox",
                "parameters": [
                    {
                        "name": "address",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Full address (bob@email.singles) or just the local part (bob)."
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "to": {
                                        "oneOf": [
                                            {
                                                "type": "string"
                                            },
                                            {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                }
                                            }
                                        ]
                                    },
                                    "cc": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "bcc": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "subject": {
                                        "type": "string"
                                    },
                                    "text": {
                                        "type": "string"
                                    },
                                    "html": {
                                        "type": "string"
                                    },
                                    "from_name": {
                                        "type": "string"
                                    },
                                    "reply_to": {
                                        "type": "string"
                                    },
                                    "reply_to_message_id": {
                                        "type": "string",
                                        "description": "Reply to this received message (fills to/subject/threading)"
                                    },
                                    "attachments": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "filename",
                                                "content_base64"
                                            ],
                                            "properties": {
                                                "filename": {
                                                    "type": "string"
                                                },
                                                "content_type": {
                                                    "type": "string"
                                                },
                                                "content_base64": {
                                                    "type": "string"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Sent",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ok": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "$ref": "#/components/schemas/MessageSummary"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearer": {
                "type": "http",
                "scheme": "bearer"
            }
        },
        "schemas": {
            "Inbox": {
                "type": "object",
                "properties": {
                    "address": {
                        "type": "string"
                    },
                    "name": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "created_at": {
                        "type": "string"
                    },
                    "message_count": {
                        "type": "integer"
                    },
                    "unread_count": {
                        "type": "integer"
                    },
                    "storage_used": {
                        "type": "integer"
                    },
                    "storage_limit": {
                        "type": "integer"
                    },
                    "storage_free": {
                        "type": "integer"
                    },
                    "rejected_over_quota": {
                        "type": "integer"
                    }
                }
            },
            "MessageSummary": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "inbox": {
                        "type": "string"
                    },
                    "direction": {
                        "type": "string",
                        "enum": [
                            "received",
                            "sent"
                        ]
                    },
                    "from": {
                        "type": "object",
                        "properties": {
                            "address": {
                                "type": "string"
                            },
                            "name": {
                                "type": "string"
                            }
                        }
                    },
                    "to": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "subject": {
                        "type": "string"
                    },
                    "snippet": {
                        "type": "string"
                    },
                    "codes": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Detected verification codes, best first"
                    },
                    "attachment_count": {
                        "type": "integer"
                    },
                    "size": {
                        "type": "integer"
                    },
                    "seen": {
                        "type": "boolean"
                    },
                    "date": {
                        "type": "string"
                    },
                    "url": {
                        "type": "string"
                    }
                }
            },
            "Message": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/MessageSummary"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "cc": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "reply_to": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "message_id": {
                                "type": "string"
                            },
                            "text": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "html": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "links": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "attachments": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "index": {
                                            "type": "integer"
                                        },
                                        "filename": {
                                            "type": "string"
                                        },
                                        "content_type": {
                                            "type": "string"
                                        },
                                        "size": {
                                            "type": "integer"
                                        },
                                        "url": {
                                            "type": "string"
                                        }
                                    }
                                }
                            },
                            "headers": {
                                "type": "object"
                            },
                            "raw_url": {
                                "type": "string"
                            }
                        }
                    }
                ]
            }
        }
    }
}