{
    "components": {
        "schemas": {
            "mailbox.MailboxMetadata": {
                "description": "Keys to add/update for a mailbox.",
                "properties": {
                    "encryption_key": {
                        "description": "The mailbox encryption key.\nThis is an HPKE public key\nin the X25519 format for use\nin a X25519-DHKEM (RFC 9180).\nBase32 crockford-encoded.",
                        "type": "string"
                    },
                    "encryption_key_type": {
                        "description": "Type of key.\nOptional, as currently only\nX25519 keys are supported.",
                        "type": "string"
                    },
                    "expiration": {
                        "$ref": "#/components/schemas/mailbox.Timestamp"
                    },
                    "info": {
                        "description": "Info field (e.g for Keyoxide claim proof)",
                        "type": "string"
                    },
                    "signing_key": {
                        "description": "The mailbox signing key.\nNote that $H_MAILBOX == H(singingKey).\nNote also how this key cannot be updated\nas it identifies the mailbox.",
                        "type": "string"
                    },
                    "signing_key_type": {
                        "description": "Type of key.\nOptional, as currently only\nEdDSA keys are supported.",
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "mailbox.MailboxRegistrationRequest": {
                "properties": {
                    "mailbox_metadata": {
                        "$ref": "#/components/schemas/mailbox.MailboxMetadata"
                    },
                    "signature": {
                        "description": "Signature by the mailbox's signing key affirming\nthe update of keys, of purpose\nTALER_SIGNATURE_WALLET_MAILBOX_KEYS_UPDATE.\nThe signature is created over the SHA-512 hash\nof (encryptionKeyType||encryptionKey||expiration)",
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "mailbox.RelativeTime": {
                "description": "How long will the service store a message\nbefore giving up",
                "properties": {
                    "d_us": {
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "mailbox.Timestamp": {
                "description": "Expiration of this mapping (UNIX Epoch seconds).",
                "properties": {
                    "t_s": {
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "mailbox.VersionResponse": {
                "properties": {
                    "delivery_period": {
                        "$ref": "#/components/schemas/mailbox.RelativeTime"
                    },
                    "free_message_quota": {
                        "description": "How many messages can be send and\nare stored by the service for free.\nAfter the quota is reached, the\nregular message_fee applies.\nMay be 0 for no free quota.",
                        "type": "string"
                    },
                    "message_body_bytes": {
                        "description": "Fixed size of message bodies",
                        "type": "integer"
                    },
                    "message_fee": {
                        "description": "How much is the cost to send a single\nmessage to a mailbox.\nMay be 0 for free message sending.",
                        "type": "string"
                    },
                    "message_response_limit": {
                        "description": "How many messages will a single response\ncontain at maximum.",
                        "type": "integer"
                    },
                    "monthly_fee": {
                        "description": "How much is the cost of a single\nregistration period (30 days) of a mailbox\nMay be 0 for a free registration.",
                        "type": "string"
                    },
                    "name": {
                        "description": "Name of the protocol.",
                        "type": "string"
                    },
                    "registration_update_fee": {
                        "description": "How much is the cost of a single\nregistration (update) of a mailbox\nMay be 0 for a free update/registration.",
                        "type": "string"
                    },
                    "version": {
                        "description": "libtool-style representation of the Mailbox protocol version, see\nhttps://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning\nThe format is \"current:revision:age\".",
                        "type": "string"
                    }
                },
                "type": "object"
            }
        }
    },
    "info": {
        "contact": {
            "url": "https://taler.net"
        },
        "description": "The Taler Mailbox service provides encrypted message delivery to wallets identified by their public key.",
        "license": {
            "name": "AGPL-3.0-or-later",
            "url": "https://www.gnu.org/licenses/agpl-3.0.html"
        },
        "title": "Taler Mailbox API",
        "version": ""
    },
    "externalDocs": {
        "description": "",
        "url": ""
    },
    "paths": {
        "/config": {
            "get": {
                "description": "Returns service metadata including fees, message size limits, and delivery period.",
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/mailbox.VersionResponse"
                                }
                            }
                        },
                        "description": "OK"
                    }
                },
                "summary": "Get service configuration",
                "tags": [
                    "config"
                ]
            }
        },
        "/info/{h_mailbox}": {
            "get": {
                "description": "Returns the signing and encryption key metadata for the given mailbox.",
                "parameters": [
                    {
                        "description": "SHA-512 hash of the mailbox signing key (Crockford base32)",
                        "in": "path",
                        "name": "h_mailbox",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/mailbox.MailboxMetadata"
                                }
                            }
                        },
                        "description": "OK"
                    },
                    "404": {
                        "description": "Mailbox not found or expired"
                    }
                },
                "summary": "Get mailbox info",
                "tags": [
                    "mailbox"
                ]
            }
        },
        "/register": {
            "post": {
                "description": "Registers a new mailbox or updates the keys/expiration of an existing one.\nA valid EdDSA signature over the key material must be provided.",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "oneOf": [
                                    {
                                        "type": "object"
                                    },
                                    {
                                        "$ref": "#/components/schemas/mailbox.MailboxRegistrationRequest",
                                        "summary": "body",
                                        "description": "Registration request"
                                    }
                                ]
                            }
                        }
                    },
                    "description": "Registration request",
                    "required": true
                },
                "responses": {
                    "204": {
                        "description": "Registration confirmed"
                    },
                    "304": {
                        "description": "Nothing changed"
                    },
                    "400": {
                        "description": "Invalid request body or signature"
                    },
                    "402": {
                        "description": "Payment required"
                    },
                    "500": {
                        "description": "Internal Server Error"
                    }
                },
                "summary": "Register or update mailbox",
                "tags": [
                    "mailbox"
                ]
            }
        },
        "/{h_mailbox}": {
            "get": {
                "description": "Returns up to MessageResponseLimit encrypted message bodies for the given mailbox.\nThe ETag response header contains the serial number of the first message.",
                "parameters": [
                    {
                        "description": "SHA-512 hash of the mailbox signing key (Crockford base32)",
                        "in": "path",
                        "name": "h_mailbox",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/octet-stream": {
                                "schema": {
                                    "format": "binary",
                                    "type": "string"
                                }
                            }
                        },
                        "description": "One or more message bodies concatenated"
                    },
                    "204": {
                        "description": "No messages available"
                    },
                    "404": {
                        "description": "Mailbox not found"
                    }
                },
                "summary": "Retrieve messages",
                "tags": [
                    "mailbox"
                ]
            },
            "post": {
                "description": "Stores an encrypted message body for the given mailbox. The body must be\nexactly MessageBodyBytes in size.",
                "parameters": [
                    {
                        "description": "SHA-512 hash of the mailbox signing key (Crockford base32)",
                        "in": "path",
                        "name": "h_mailbox",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/octet-stream": {
                            "schema": {
                                "format": "binary",
                                "type": "string"
                            }
                        },
                        "text/plain": {
                            "schema": {
                                "title": "body",
                                "type": "string"
                            }
                        }
                    },
                    "description": "Encrypted message body (fixed size)",
                    "required": true
                },
                "responses": {
                    "204": {
                        "description": "Message stored"
                    },
                    "304": {
                        "description": "Identical message already stored"
                    },
                    "400": {
                        "description": "Missing or wrong-size body"
                    },
                    "402": {
                        "description": "Payment required (free quota exceeded)"
                    },
                    "500": {
                        "description": "Internal Server Error"
                    }
                },
                "summary": "Send a message",
                "tags": [
                    "mailbox"
                ]
            }
        },
        "/{mailbox}": {
            "delete": {
                "description": "Deletes one or more messages starting from the serial given in the If-Match header.\nRequires a valid EdDSA signature in the Taler-Mailbox-Delete-Signature header.",
                "parameters": [
                    {
                        "description": "Crockford base32-encoded EdDSA public key of the mailbox",
                        "in": "path",
                        "name": "mailbox",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "description": "Number of messages to delete (default: 1)",
                        "in": "query",
                        "name": "count",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "description": "Serial number of the first message to delete",
                        "in": "header",
                        "name": "If-Match",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "description": "EdDSA signature authorising the deletion",
                        "in": "header",
                        "name": "Taler-Mailbox-Delete-Signature",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "204": {
                        "description": "Messages deleted"
                    },
                    "400": {
                        "description": "Missing or malformed headers/parameters"
                    },
                    "403": {
                        "description": "Signature invalid"
                    },
                    "404": {
                        "description": "Message with given serial not found"
                    },
                    "500": {
                        "description": "Internal Server Error"
                    }
                },
                "summary": "Delete messages",
                "tags": [
                    "mailbox"
                ]
            }
        }
    },
    "openapi": "3.1.0",
    "servers": [
        {
            "url": "/"
        }
    ]
}