{
    "openapi": "3.0.3",
    "info": {
        "title": "SMTP Gateway API",
        "description": "Manage the email tokens that your services send email with, the rate limits, and the statistics, and send\nemail.\n\n**Authentication.** Every endpoint takes a bearer token (`Authorization: Bearer <token>`). Each is one\nstring, created in the web interface, whose first 19 characters are its ID (e.g. `ak_8af651aadbe3ff25`),\nand only works from the IP addresses it was given.\n - Every endpoint except `POST /send` needs an **API key** (starting `ak_`), created under \"API keys\".\n - `POST /send` needs an **email token** (starting `et_`), created under \"Email tokens\": the same token a\n   service uses as its SMTP password.\n\n**Errors** are returned with a suitable HTTP status code, and a body of\n`{\"error\": {\"message\": \"...\", \"code\": 1}}`, where `code` is an application-specific code that tells apart\nerrors with the same status: -1 unknown, 1 invalid JSON, 2 invalid input, 3 not found, 4 message too\nlarge, 5 changed by someone else in the meantime, 6 version (If-Match) missing, 10 missing credentials,\n11 invalid credentials, 12 revoked credentials, 13 IP address not allowed, 14 two-factor authentication\nmust be set up first, 15 the password must be changed first, 20 sender not allowed, 21 reply-to not\nallowed, 22 recipient not allowed, 23 more recipients than a rate limit allows, 24 no provider the email\ntoken can use takes the sender, 30 rejected by the provider, 31 no providers have been set up yet, 40 the\naccount isn't archived (archive it before deleting it), 41 the account is archived, 42 the last account\nthat can log in can't be blocked or archived.\n\n**SMTP.** Services can also send email through the SMTP server: port 465 (implicit TLS) or 587\n(STARTTLS), logging in with an email token's ID as the username, and the whole token as the password. The\nreply to each email says\n`250 2.0.0 Ok: sent as <id>` or `250 2.0.0 Ok: queued as <id>`.",
        "license": {
            "name": "MIT",
            "url": "https://opensource.org/licenses/MIT"
        },
        "version": "1.0.0"
    },
    "servers": [
        {
            "url": "/api/v1",
            "description": "This server"
        }
    ],
    "paths": {
        "/email-tokens": {
            "get": {
                "tags": [
                    "Email tokens"
                ],
                "summary": "List the email tokens",
                "operationId": "listEmailTokens",
                "parameters": [
                    {
                        "name": "includeRevoked",
                        "in": "query",
                        "description": "Whether to include revoked email tokens.",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The email tokens, newest first.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "emailTokens": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "id": {
                                                        "type": "string",
                                                        "description": "The email token's ID: the first 19 characters of the token, and its SMTP username.",
                                                        "pattern": "^et_[0-9a-f]{16}$",
                                                        "example": "et_8af651aadbe3ff25"
                                                    },
                                                    "name": {
                                                        "type": "string"
                                                    },
                                                    "createdAt": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    },
                                                    "lastUsedAt": {
                                                        "type": "string",
                                                        "format": "date-time",
                                                        "nullable": true
                                                    },
                                                    "revokedAt": {
                                                        "type": "string",
                                                        "format": "date-time",
                                                        "nullable": true
                                                    },
                                                    "conditions": {
                                                        "type": "array",
                                                        "description": "What the email token is restricted to, one condition per field, each at most once. A field with no condition has no restriction, so leave out the whole list to allow anyone, from anywhere. An empty \"allowed\" list is refused, as it would allow nobody.",
                                                        "items": {
                                                            "oneOf": [
                                                                {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "field": {
                                                                            "type": "string",
                                                                            "description": "The IP address the email token is used from.",
                                                                            "enum": [
                                                                                "clientIp"
                                                                            ]
                                                                        },
                                                                        "allowed": {
                                                                            "type": "array",
                                                                            "description": "The IP addresses or CIDR ranges the email token may be used from, e.g. \"10.0.0.0/8\".",
                                                                            "items": {
                                                                                "type": "string"
                                                                            },
                                                                            "minItems": 1
                                                                        }
                                                                    },
                                                                    "required": [
                                                                        "field",
                                                                        "allowed"
                                                                    ]
                                                                },
                                                                {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "field": {
                                                                            "type": "string",
                                                                            "description": "\"sender\" for who emails may be from (the envelope sender, and the From and Sender headers), \"replyTo\" for what the Reply-To header may contain (an email without one is always fine), or \"recipient\" for who emails may be sent to (to, cc and bcc alike).",
                                                                            "enum": [
                                                                                "sender",
                                                                                "replyTo",
                                                                                "recipient"
                                                                            ]
                                                                        },
                                                                        "allowed": {
                                                                            "type": "array",
                                                                            "description": "The addresses allowed: an address is allowed if any of these rules allows it.",
                                                                            "items": {
                                                                                "type": "object",
                                                                                "properties": {
                                                                                    "type": {
                                                                                        "type": "string",
                                                                                        "description": "\"domain\" for anyone at exactly that domain (not its subdomains), or \"address\" for one address.",
                                                                                        "enum": [
                                                                                            "domain",
                                                                                            "address"
                                                                                        ]
                                                                                    },
                                                                                    "value": {
                                                                                        "type": "string",
                                                                                        "description": "The domain (e.g. \"example.org\") or address."
                                                                                    }
                                                                                },
                                                                                "required": [
                                                                                    "type",
                                                                                    "value"
                                                                                ]
                                                                            },
                                                                            "minItems": 1
                                                                        }
                                                                    },
                                                                    "required": [
                                                                        "field",
                                                                        "allowed"
                                                                    ]
                                                                },
                                                                {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "field": {
                                                                            "type": "string",
                                                                            "description": "The providers the email token's emails go through.",
                                                                            "enum": [
                                                                                "provider"
                                                                            ]
                                                                        },
                                                                        "allowed": {
                                                                            "type": "array",
                                                                            "description": "The ids of the providers the email token's emails may be sent through (GET /api/v1/providers lists them). The mode applies to those of them that are enabled, as if they were the only providers, and while none of them is enabled, its emails wait in the queue. Each must be a provider's id, enabled or not. An empty list is refused, but a token whose providers have all been removed since shows one, as it stays restricted (to none) rather than being allowed every provider.",
                                                                            "items": {
                                                                                "type": "string",
                                                                                "format": "uuid"
                                                                            }
                                                                        }
                                                                    },
                                                                    "required": [
                                                                        "field",
                                                                        "allowed"
                                                                    ]
                                                                }
                                                            ]
                                                        }
                                                    },
                                                    "rateLimits": {
                                                        "type": "array",
                                                        "description": "Rate limits that must all allow an email for it to be sent straight away, otherwise it's queued. Any mix of email and recipient limits can be given, but no two can have the same unit and period. Leave it empty (the default) for no limit. An email with more recipients than a recipient limit allows is refused (error code 23), as it could never be sent.",
                                                        "items": {
                                                            "type": "object",
                                                            "properties": {
                                                                "unit": {
                                                                    "type": "string",
                                                                    "description": "\"emails\" to limit the number of emails handed to the provider (each is one request, however many recipients it has), or \"recipients\" to limit the number of recipients (To, Cc and Bcc alike).",
                                                                    "enum": [
                                                                        "emails",
                                                                        "recipients"
                                                                    ]
                                                                },
                                                                "max": {
                                                                    "type": "integer",
                                                                    "description": "How many emails, or recipients, may be sent within the period.",
                                                                    "minimum": 1
                                                                },
                                                                "periodSeconds": {
                                                                    "type": "integer",
                                                                    "description": "The length of the sliding window, in seconds.",
                                                                    "minimum": 1,
                                                                    "maximum": 2678400
                                                                }
                                                            },
                                                            "required": [
                                                                "unit",
                                                                "max",
                                                                "periodSeconds"
                                                            ]
                                                        }
                                                    },
                                                    "priority": {
                                                        "type": "integer",
                                                        "description": "How important the email token's emails are in the queue: a higher priority's emails are sent before a lower one's, though rate limits still apply. 1 if left out. The service's own emails (password reset links) have priority 9999, so always go first.",
                                                        "minimum": 1,
                                                        "maximum": 9998,
                                                        "default": 1
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "tags": [
                    "Email tokens"
                ],
                "summary": "Create an email token",
                "description": "Creates an email token with a new secret. Its `conditions` are optional: only the fields given are restricted, so leave one out to allow anyone (or, for `clientIp`, anywhere, and for `provider`, every provider). Fields it doesn't have (e.g. a misspelt `conditons`, which would leave it unrestricted), or that the service sets (such as `id`), are refused.",
                "operationId": "createEmailToken",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "description": "A name to recognise the email token by, e.g. the service that will use it.",
                                        "maxLength": 255
                                    },
                                    "conditions": {
                                        "type": "array",
                                        "description": "What the email token is restricted to, one condition per field, each at most once. A field with no condition has no restriction, so leave out the whole list to allow anyone, from anywhere. An empty \"allowed\" list is refused, as it would allow nobody.",
                                        "items": {
                                            "oneOf": [
                                                {
                                                    "type": "object",
                                                    "properties": {
                                                        "field": {
                                                            "type": "string",
                                                            "description": "The IP address the email token is used from.",
                                                            "enum": [
                                                                "clientIp"
                                                            ]
                                                        },
                                                        "allowed": {
                                                            "type": "array",
                                                            "description": "The IP addresses or CIDR ranges the email token may be used from, e.g. \"10.0.0.0/8\".",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "minItems": 1
                                                        }
                                                    },
                                                    "required": [
                                                        "field",
                                                        "allowed"
                                                    ]
                                                },
                                                {
                                                    "type": "object",
                                                    "properties": {
                                                        "field": {
                                                            "type": "string",
                                                            "description": "\"sender\" for who emails may be from (the envelope sender, and the From and Sender headers), \"replyTo\" for what the Reply-To header may contain (an email without one is always fine), or \"recipient\" for who emails may be sent to (to, cc and bcc alike).",
                                                            "enum": [
                                                                "sender",
                                                                "replyTo",
                                                                "recipient"
                                                            ]
                                                        },
                                                        "allowed": {
                                                            "type": "array",
                                                            "description": "The addresses allowed: an address is allowed if any of these rules allows it.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "type": {
                                                                        "type": "string",
                                                                        "description": "\"domain\" for anyone at exactly that domain (not its subdomains), or \"address\" for one address.",
                                                                        "enum": [
                                                                            "domain",
                                                                            "address"
                                                                        ]
                                                                    },
                                                                    "value": {
                                                                        "type": "string",
                                                                        "description": "The domain (e.g. \"example.org\") or address."
                                                                    }
                                                                },
                                                                "required": [
                                                                    "type",
                                                                    "value"
                                                                ]
                                                            },
                                                            "minItems": 1
                                                        }
                                                    },
                                                    "required": [
                                                        "field",
                                                        "allowed"
                                                    ]
                                                },
                                                {
                                                    "type": "object",
                                                    "properties": {
                                                        "field": {
                                                            "type": "string",
                                                            "description": "The providers the email token's emails go through.",
                                                            "enum": [
                                                                "provider"
                                                            ]
                                                        },
                                                        "allowed": {
                                                            "type": "array",
                                                            "description": "The ids of the providers the email token's emails may be sent through (GET /api/v1/providers lists them). The mode applies to those of them that are enabled, as if they were the only providers, and while none of them is enabled, its emails wait in the queue. Each must be a provider's id, enabled or not. An empty list is refused, but a token whose providers have all been removed since shows one, as it stays restricted (to none) rather than being allowed every provider.",
                                                            "items": {
                                                                "type": "string",
                                                                "format": "uuid"
                                                            }
                                                        }
                                                    },
                                                    "required": [
                                                        "field",
                                                        "allowed"
                                                    ]
                                                }
                                            ]
                                        }
                                    },
                                    "rateLimits": {
                                        "type": "array",
                                        "description": "Rate limits that must all allow an email for it to be sent straight away, otherwise it's queued. Any mix of email and recipient limits can be given, but no two can have the same unit and period. Leave it empty (the default) for no limit. An email with more recipients than a recipient limit allows is refused (error code 23), as it could never be sent.",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "unit": {
                                                    "type": "string",
                                                    "description": "\"emails\" to limit the number of emails handed to the provider (each is one request, however many recipients it has), or \"recipients\" to limit the number of recipients (To, Cc and Bcc alike).",
                                                    "enum": [
                                                        "emails",
                                                        "recipients"
                                                    ]
                                                },
                                                "max": {
                                                    "type": "integer",
                                                    "description": "How many emails, or recipients, may be sent within the period.",
                                                    "minimum": 1
                                                },
                                                "periodSeconds": {
                                                    "type": "integer",
                                                    "description": "The length of the sliding window, in seconds.",
                                                    "minimum": 1,
                                                    "maximum": 2678400
                                                }
                                            },
                                            "required": [
                                                "unit",
                                                "max",
                                                "periodSeconds"
                                            ]
                                        }
                                    },
                                    "priority": {
                                        "type": "integer",
                                        "description": "How important the email token's emails are in the queue: a higher priority's emails are sent before a lower one's, though rate limits still apply. 1 if left out. The service's own emails (password reset links) have priority 9999, so always go first.",
                                        "minimum": 1,
                                        "maximum": 9998,
                                        "default": 1
                                    }
                                },
                                "required": [
                                    "name"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "The email token was created.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "emailToken": {
                                            "type": "object",
                                            "properties": {
                                                "id": {
                                                    "type": "string",
                                                    "description": "The email token's ID: the first 19 characters of the token, and its SMTP username.",
                                                    "pattern": "^et_[0-9a-f]{16}$",
                                                    "example": "et_8af651aadbe3ff25"
                                                },
                                                "name": {
                                                    "type": "string"
                                                },
                                                "createdAt": {
                                                    "type": "string",
                                                    "format": "date-time"
                                                },
                                                "lastUsedAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "revokedAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "conditions": {
                                                    "type": "array",
                                                    "description": "What the email token is restricted to, one condition per field, each at most once. A field with no condition has no restriction, so leave out the whole list to allow anyone, from anywhere. An empty \"allowed\" list is refused, as it would allow nobody.",
                                                    "items": {
                                                        "oneOf": [
                                                            {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "The IP address the email token is used from.",
                                                                        "enum": [
                                                                            "clientIp"
                                                                        ]
                                                                    },
                                                                    "allowed": {
                                                                        "type": "array",
                                                                        "description": "The IP addresses or CIDR ranges the email token may be used from, e.g. \"10.0.0.0/8\".",
                                                                        "items": {
                                                                            "type": "string"
                                                                        },
                                                                        "minItems": 1
                                                                    }
                                                                },
                                                                "required": [
                                                                    "field",
                                                                    "allowed"
                                                                ]
                                                            },
                                                            {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "\"sender\" for who emails may be from (the envelope sender, and the From and Sender headers), \"replyTo\" for what the Reply-To header may contain (an email without one is always fine), or \"recipient\" for who emails may be sent to (to, cc and bcc alike).",
                                                                        "enum": [
                                                                            "sender",
                                                                            "replyTo",
                                                                            "recipient"
                                                                        ]
                                                                    },
                                                                    "allowed": {
                                                                        "type": "array",
                                                                        "description": "The addresses allowed: an address is allowed if any of these rules allows it.",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "type": {
                                                                                    "type": "string",
                                                                                    "description": "\"domain\" for anyone at exactly that domain (not its subdomains), or \"address\" for one address.",
                                                                                    "enum": [
                                                                                        "domain",
                                                                                        "address"
                                                                                    ]
                                                                                },
                                                                                "value": {
                                                                                    "type": "string",
                                                                                    "description": "The domain (e.g. \"example.org\") or address."
                                                                                }
                                                                            },
                                                                            "required": [
                                                                                "type",
                                                                                "value"
                                                                            ]
                                                                        },
                                                                        "minItems": 1
                                                                    }
                                                                },
                                                                "required": [
                                                                    "field",
                                                                    "allowed"
                                                                ]
                                                            },
                                                            {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "The providers the email token's emails go through.",
                                                                        "enum": [
                                                                            "provider"
                                                                        ]
                                                                    },
                                                                    "allowed": {
                                                                        "type": "array",
                                                                        "description": "The ids of the providers the email token's emails may be sent through (GET /api/v1/providers lists them). The mode applies to those of them that are enabled, as if they were the only providers, and while none of them is enabled, its emails wait in the queue. Each must be a provider's id, enabled or not. An empty list is refused, but a token whose providers have all been removed since shows one, as it stays restricted (to none) rather than being allowed every provider.",
                                                                        "items": {
                                                                            "type": "string",
                                                                            "format": "uuid"
                                                                        }
                                                                    }
                                                                },
                                                                "required": [
                                                                    "field",
                                                                    "allowed"
                                                                ]
                                                            }
                                                        ]
                                                    }
                                                },
                                                "rateLimits": {
                                                    "type": "array",
                                                    "description": "Rate limits that must all allow an email for it to be sent straight away, otherwise it's queued. Any mix of email and recipient limits can be given, but no two can have the same unit and period. Leave it empty (the default) for no limit. An email with more recipients than a recipient limit allows is refused (error code 23), as it could never be sent.",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "unit": {
                                                                "type": "string",
                                                                "description": "\"emails\" to limit the number of emails handed to the provider (each is one request, however many recipients it has), or \"recipients\" to limit the number of recipients (To, Cc and Bcc alike).",
                                                                "enum": [
                                                                    "emails",
                                                                    "recipients"
                                                                ]
                                                            },
                                                            "max": {
                                                                "type": "integer",
                                                                "description": "How many emails, or recipients, may be sent within the period.",
                                                                "minimum": 1
                                                            },
                                                            "periodSeconds": {
                                                                "type": "integer",
                                                                "description": "The length of the sliding window, in seconds.",
                                                                "minimum": 1,
                                                                "maximum": 2678400
                                                            }
                                                        },
                                                        "required": [
                                                            "unit",
                                                            "max",
                                                            "periodSeconds"
                                                        ]
                                                    }
                                                },
                                                "priority": {
                                                    "type": "integer",
                                                    "description": "How important the email token's emails are in the queue: a higher priority's emails are sent before a lower one's, though rate limits still apply. 1 if left out. The service's own emails (password reset links) have priority 9999, so always go first.",
                                                    "minimum": 1,
                                                    "maximum": 9998,
                                                    "default": 1
                                                }
                                            }
                                        },
                                        "token": {
                                            "type": "string",
                                            "description": "The email token: its ID, then its secret. It's the bearer token for POST /send, and the SMTP password. This is the only time it is ever returned."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "The request was invalid.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/email-tokens/{id}": {
            "get": {
                "tags": [
                    "Email tokens"
                ],
                "summary": "Get an email token",
                "operationId": "getEmailToken",
                "responses": {
                    "200": {
                        "description": "The email token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "emailToken": {
                                            "type": "object",
                                            "properties": {
                                                "id": {
                                                    "type": "string",
                                                    "description": "The email token's ID: the first 19 characters of the token, and its SMTP username.",
                                                    "pattern": "^et_[0-9a-f]{16}$",
                                                    "example": "et_8af651aadbe3ff25"
                                                },
                                                "name": {
                                                    "type": "string"
                                                },
                                                "createdAt": {
                                                    "type": "string",
                                                    "format": "date-time"
                                                },
                                                "lastUsedAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "revokedAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "conditions": {
                                                    "type": "array",
                                                    "description": "What the email token is restricted to, one condition per field, each at most once. A field with no condition has no restriction, so leave out the whole list to allow anyone, from anywhere. An empty \"allowed\" list is refused, as it would allow nobody.",
                                                    "items": {
                                                        "oneOf": [
                                                            {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "The IP address the email token is used from.",
                                                                        "enum": [
                                                                            "clientIp"
                                                                        ]
                                                                    },
                                                                    "allowed": {
                                                                        "type": "array",
                                                                        "description": "The IP addresses or CIDR ranges the email token may be used from, e.g. \"10.0.0.0/8\".",
                                                                        "items": {
                                                                            "type": "string"
                                                                        },
                                                                        "minItems": 1
                                                                    }
                                                                },
                                                                "required": [
                                                                    "field",
                                                                    "allowed"
                                                                ]
                                                            },
                                                            {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "\"sender\" for who emails may be from (the envelope sender, and the From and Sender headers), \"replyTo\" for what the Reply-To header may contain (an email without one is always fine), or \"recipient\" for who emails may be sent to (to, cc and bcc alike).",
                                                                        "enum": [
                                                                            "sender",
                                                                            "replyTo",
                                                                            "recipient"
                                                                        ]
                                                                    },
                                                                    "allowed": {
                                                                        "type": "array",
                                                                        "description": "The addresses allowed: an address is allowed if any of these rules allows it.",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "type": {
                                                                                    "type": "string",
                                                                                    "description": "\"domain\" for anyone at exactly that domain (not its subdomains), or \"address\" for one address.",
                                                                                    "enum": [
                                                                                        "domain",
                                                                                        "address"
                                                                                    ]
                                                                                },
                                                                                "value": {
                                                                                    "type": "string",
                                                                                    "description": "The domain (e.g. \"example.org\") or address."
                                                                                }
                                                                            },
                                                                            "required": [
                                                                                "type",
                                                                                "value"
                                                                            ]
                                                                        },
                                                                        "minItems": 1
                                                                    }
                                                                },
                                                                "required": [
                                                                    "field",
                                                                    "allowed"
                                                                ]
                                                            },
                                                            {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "The providers the email token's emails go through.",
                                                                        "enum": [
                                                                            "provider"
                                                                        ]
                                                                    },
                                                                    "allowed": {
                                                                        "type": "array",
                                                                        "description": "The ids of the providers the email token's emails may be sent through (GET /api/v1/providers lists them). The mode applies to those of them that are enabled, as if they were the only providers, and while none of them is enabled, its emails wait in the queue. Each must be a provider's id, enabled or not. An empty list is refused, but a token whose providers have all been removed since shows one, as it stays restricted (to none) rather than being allowed every provider.",
                                                                        "items": {
                                                                            "type": "string",
                                                                            "format": "uuid"
                                                                        }
                                                                    }
                                                                },
                                                                "required": [
                                                                    "field",
                                                                    "allowed"
                                                                ]
                                                            }
                                                        ]
                                                    }
                                                },
                                                "rateLimits": {
                                                    "type": "array",
                                                    "description": "Rate limits that must all allow an email for it to be sent straight away, otherwise it's queued. Any mix of email and recipient limits can be given, but no two can have the same unit and period. Leave it empty (the default) for no limit. An email with more recipients than a recipient limit allows is refused (error code 23), as it could never be sent.",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "unit": {
                                                                "type": "string",
                                                                "description": "\"emails\" to limit the number of emails handed to the provider (each is one request, however many recipients it has), or \"recipients\" to limit the number of recipients (To, Cc and Bcc alike).",
                                                                "enum": [
                                                                    "emails",
                                                                    "recipients"
                                                                ]
                                                            },
                                                            "max": {
                                                                "type": "integer",
                                                                "description": "How many emails, or recipients, may be sent within the period.",
                                                                "minimum": 1
                                                            },
                                                            "periodSeconds": {
                                                                "type": "integer",
                                                                "description": "The length of the sliding window, in seconds.",
                                                                "minimum": 1,
                                                                "maximum": 2678400
                                                            }
                                                        },
                                                        "required": [
                                                            "unit",
                                                            "max",
                                                            "periodSeconds"
                                                        ]
                                                    }
                                                },
                                                "priority": {
                                                    "type": "integer",
                                                    "description": "How important the email token's emails are in the queue: a higher priority's emails are sent before a lower one's, though rate limits still apply. 1 if left out. The service's own emails (password reset links) have priority 9999, so always go first.",
                                                    "minimum": 1,
                                                    "maximum": 9998,
                                                    "default": 1
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "There is no such record.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "put": {
                "tags": [
                    "Email tokens"
                ],
                "summary": "Replace an email token's restrictions",
                "description": "Replaces the email token's name, conditions, rate limits and priority. Every one of them must be given (an empty list for no conditions, or no rate limits), so leaving one out can't remove its restriction by mistake. Fields it doesn't have, or that can't be changed (such as `id`), are refused. To change only some of them, use PATCH. Its ID and secret stay the same, so whatever uses it carries on working, with its new restrictions from its next request, or its next SMTP login (a connection that's already logged in keeps the ones it logged in with). New rate limits apply to its emails already in the queue too, but a new priority only applies to emails queued from then on. A revoked email token can't be changed (409).",
                "operationId": "replaceEmailToken",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "description": "A name to recognise the email token by, e.g. the service that will use it.",
                                        "maxLength": 255
                                    },
                                    "conditions": {
                                        "type": "array",
                                        "description": "What the email token is restricted to from now on, one condition per field, each at most once. A field with no condition has no restriction, so an empty list allows anyone, from anywhere.",
                                        "items": {
                                            "oneOf": [
                                                {
                                                    "type": "object",
                                                    "properties": {
                                                        "field": {
                                                            "type": "string",
                                                            "description": "The IP address the email token is used from.",
                                                            "enum": [
                                                                "clientIp"
                                                            ]
                                                        },
                                                        "allowed": {
                                                            "type": "array",
                                                            "description": "The IP addresses or CIDR ranges the email token may be used from, e.g. \"10.0.0.0/8\".",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "minItems": 1
                                                        }
                                                    },
                                                    "required": [
                                                        "field",
                                                        "allowed"
                                                    ]
                                                },
                                                {
                                                    "type": "object",
                                                    "properties": {
                                                        "field": {
                                                            "type": "string",
                                                            "description": "\"sender\" for who emails may be from (the envelope sender, and the From and Sender headers), \"replyTo\" for what the Reply-To header may contain (an email without one is always fine), or \"recipient\" for who emails may be sent to (to, cc and bcc alike).",
                                                            "enum": [
                                                                "sender",
                                                                "replyTo",
                                                                "recipient"
                                                            ]
                                                        },
                                                        "allowed": {
                                                            "type": "array",
                                                            "description": "The addresses allowed: an address is allowed if any of these rules allows it.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "type": {
                                                                        "type": "string",
                                                                        "description": "\"domain\" for anyone at exactly that domain (not its subdomains), or \"address\" for one address.",
                                                                        "enum": [
                                                                            "domain",
                                                                            "address"
                                                                        ]
                                                                    },
                                                                    "value": {
                                                                        "type": "string",
                                                                        "description": "The domain (e.g. \"example.org\") or address."
                                                                    }
                                                                },
                                                                "required": [
                                                                    "type",
                                                                    "value"
                                                                ]
                                                            },
                                                            "minItems": 1
                                                        }
                                                    },
                                                    "required": [
                                                        "field",
                                                        "allowed"
                                                    ]
                                                },
                                                {
                                                    "type": "object",
                                                    "properties": {
                                                        "field": {
                                                            "type": "string",
                                                            "description": "The providers the email token's emails go through.",
                                                            "enum": [
                                                                "provider"
                                                            ]
                                                        },
                                                        "allowed": {
                                                            "type": "array",
                                                            "description": "The ids of the providers the email token's emails may be sent through (GET /api/v1/providers lists them). The mode applies to those of them that are enabled, as if they were the only providers, and while none of them is enabled, its emails wait in the queue. Each must be a provider's id, enabled or not. An empty list is refused, but a token whose providers have all been removed since shows one, as it stays restricted (to none) rather than being allowed every provider.",
                                                            "items": {
                                                                "type": "string",
                                                                "format": "uuid"
                                                            }
                                                        }
                                                    },
                                                    "required": [
                                                        "field",
                                                        "allowed"
                                                    ]
                                                }
                                            ]
                                        }
                                    },
                                    "rateLimits": {
                                        "type": "array",
                                        "description": "Rate limits that must all allow an email for it to be sent straight away, otherwise it's queued. Any mix of email and recipient limits can be given, but no two can have the same unit and period. Leave it empty (the default) for no limit. An email with more recipients than a recipient limit allows is refused (error code 23), as it could never be sent.",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "unit": {
                                                    "type": "string",
                                                    "description": "\"emails\" to limit the number of emails handed to the provider (each is one request, however many recipients it has), or \"recipients\" to limit the number of recipients (To, Cc and Bcc alike).",
                                                    "enum": [
                                                        "emails",
                                                        "recipients"
                                                    ]
                                                },
                                                "max": {
                                                    "type": "integer",
                                                    "description": "How many emails, or recipients, may be sent within the period.",
                                                    "minimum": 1
                                                },
                                                "periodSeconds": {
                                                    "type": "integer",
                                                    "description": "The length of the sliding window, in seconds.",
                                                    "minimum": 1,
                                                    "maximum": 2678400
                                                }
                                            },
                                            "required": [
                                                "unit",
                                                "max",
                                                "periodSeconds"
                                            ]
                                        }
                                    },
                                    "priority": {
                                        "type": "integer",
                                        "description": "How important the email token's emails are in the queue: a higher priority's emails are sent before a lower one's, though rate limits still apply. The service's own emails (password reset links) have priority 9999, so always go first.",
                                        "minimum": 1,
                                        "maximum": 9998,
                                        "default": 1
                                    }
                                },
                                "required": [
                                    "name",
                                    "conditions",
                                    "rateLimits",
                                    "priority"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "The email token, as it is now.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "emailToken": {
                                            "type": "object",
                                            "properties": {
                                                "id": {
                                                    "type": "string",
                                                    "description": "The email token's ID: the first 19 characters of the token, and its SMTP username.",
                                                    "pattern": "^et_[0-9a-f]{16}$",
                                                    "example": "et_8af651aadbe3ff25"
                                                },
                                                "name": {
                                                    "type": "string"
                                                },
                                                "createdAt": {
                                                    "type": "string",
                                                    "format": "date-time"
                                                },
                                                "lastUsedAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "revokedAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "conditions": {
                                                    "type": "array",
                                                    "description": "What the email token is restricted to, one condition per field, each at most once. A field with no condition has no restriction, so leave out the whole list to allow anyone, from anywhere. An empty \"allowed\" list is refused, as it would allow nobody.",
                                                    "items": {
                                                        "oneOf": [
                                                            {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "The IP address the email token is used from.",
                                                                        "enum": [
                                                                            "clientIp"
                                                                        ]
                                                                    },
                                                                    "allowed": {
                                                                        "type": "array",
                                                                        "description": "The IP addresses or CIDR ranges the email token may be used from, e.g. \"10.0.0.0/8\".",
                                                                        "items": {
                                                                            "type": "string"
                                                                        },
                                                                        "minItems": 1
                                                                    }
                                                                },
                                                                "required": [
                                                                    "field",
                                                                    "allowed"
                                                                ]
                                                            },
                                                            {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "\"sender\" for who emails may be from (the envelope sender, and the From and Sender headers), \"replyTo\" for what the Reply-To header may contain (an email without one is always fine), or \"recipient\" for who emails may be sent to (to, cc and bcc alike).",
                                                                        "enum": [
                                                                            "sender",
                                                                            "replyTo",
                                                                            "recipient"
                                                                        ]
                                                                    },
                                                                    "allowed": {
                                                                        "type": "array",
                                                                        "description": "The addresses allowed: an address is allowed if any of these rules allows it.",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "type": {
                                                                                    "type": "string",
                                                                                    "description": "\"domain\" for anyone at exactly that domain (not its subdomains), or \"address\" for one address.",
                                                                                    "enum": [
                                                                                        "domain",
                                                                                        "address"
                                                                                    ]
                                                                                },
                                                                                "value": {
                                                                                    "type": "string",
                                                                                    "description": "The domain (e.g. \"example.org\") or address."
                                                                                }
                                                                            },
                                                                            "required": [
                                                                                "type",
                                                                                "value"
                                                                            ]
                                                                        },
                                                                        "minItems": 1
                                                                    }
                                                                },
                                                                "required": [
                                                                    "field",
                                                                    "allowed"
                                                                ]
                                                            },
                                                            {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "The providers the email token's emails go through.",
                                                                        "enum": [
                                                                            "provider"
                                                                        ]
                                                                    },
                                                                    "allowed": {
                                                                        "type": "array",
                                                                        "description": "The ids of the providers the email token's emails may be sent through (GET /api/v1/providers lists them). The mode applies to those of them that are enabled, as if they were the only providers, and while none of them is enabled, its emails wait in the queue. Each must be a provider's id, enabled or not. An empty list is refused, but a token whose providers have all been removed since shows one, as it stays restricted (to none) rather than being allowed every provider.",
                                                                        "items": {
                                                                            "type": "string",
                                                                            "format": "uuid"
                                                                        }
                                                                    }
                                                                },
                                                                "required": [
                                                                    "field",
                                                                    "allowed"
                                                                ]
                                                            }
                                                        ]
                                                    }
                                                },
                                                "rateLimits": {
                                                    "type": "array",
                                                    "description": "Rate limits that must all allow an email for it to be sent straight away, otherwise it's queued. Any mix of email and recipient limits can be given, but no two can have the same unit and period. Leave it empty (the default) for no limit. An email with more recipients than a recipient limit allows is refused (error code 23), as it could never be sent.",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "unit": {
                                                                "type": "string",
                                                                "description": "\"emails\" to limit the number of emails handed to the provider (each is one request, however many recipients it has), or \"recipients\" to limit the number of recipients (To, Cc and Bcc alike).",
                                                                "enum": [
                                                                    "emails",
                                                                    "recipients"
                                                                ]
                                                            },
                                                            "max": {
                                                                "type": "integer",
                                                                "description": "How many emails, or recipients, may be sent within the period.",
                                                                "minimum": 1
                                                            },
                                                            "periodSeconds": {
                                                                "type": "integer",
                                                                "description": "The length of the sliding window, in seconds.",
                                                                "minimum": 1,
                                                                "maximum": 2678400
                                                            }
                                                        },
                                                        "required": [
                                                            "unit",
                                                            "max",
                                                            "periodSeconds"
                                                        ]
                                                    }
                                                },
                                                "priority": {
                                                    "type": "integer",
                                                    "description": "How important the email token's emails are in the queue: a higher priority's emails are sent before a lower one's, though rate limits still apply. 1 if left out. The service's own emails (password reset links) have priority 9999, so always go first.",
                                                    "minimum": 1,
                                                    "maximum": 9998,
                                                    "default": 1
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "The request was invalid.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "There is no such record.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "It can't be done to the account in the state it's in (see the code).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "patch": {
                "tags": [
                    "Email tokens"
                ],
                "summary": "Change some of an email token's restrictions",
                "description": "Changes only what's given, and keeps the rest: `name`, `rateLimits` and `priority` replace the email token's, and each condition in `conditions` replaces its condition on that field, so changing the allowed senders keeps the allowed IP addresses, for example. Fields it doesn't have, or that can't be changed (such as `id`), are refused. Its ID and secret stay the same, so whatever uses it carries on working, with its new restrictions from its next request, or its next SMTP login (a connection that's already logged in keeps the ones it logged in with). New rate limits apply to its emails already in the queue too, but a new priority only applies to emails queued from then on. A revoked email token can't be changed (409).",
                "operationId": "patchEmailToken",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "description": "A name to recognise the email token by, e.g. the service that will use it.",
                                        "maxLength": 255
                                    },
                                    "conditions": {
                                        "type": "array",
                                        "description": "The conditions to change. Each one given replaces the email token's condition on that field, and the others are kept as they are. Give a condition \"allowed\": null to remove it, so that field has no restriction.",
                                        "items": {
                                            "oneOf": [
                                                {
                                                    "type": "object",
                                                    "properties": {
                                                        "field": {
                                                            "type": "string",
                                                            "description": "The IP address the email token is used from.",
                                                            "enum": [
                                                                "clientIp"
                                                            ]
                                                        },
                                                        "allowed": {
                                                            "type": "array",
                                                            "description": "The IP addresses or CIDR ranges the email token may be used from, e.g. \"10.0.0.0/8\". Or null, to remove the condition, so the field has no restriction.",
                                                            "items": {
                                                                "type": "string"
                                                            },
                                                            "minItems": 1,
                                                            "nullable": true
                                                        }
                                                    },
                                                    "required": [
                                                        "field",
                                                        "allowed"
                                                    ]
                                                },
                                                {
                                                    "type": "object",
                                                    "properties": {
                                                        "field": {
                                                            "type": "string",
                                                            "description": "\"sender\" for who emails may be from (the envelope sender, and the From and Sender headers), \"replyTo\" for what the Reply-To header may contain (an email without one is always fine), or \"recipient\" for who emails may be sent to (to, cc and bcc alike).",
                                                            "enum": [
                                                                "sender",
                                                                "replyTo",
                                                                "recipient"
                                                            ]
                                                        },
                                                        "allowed": {
                                                            "type": "array",
                                                            "description": "The addresses allowed: an address is allowed if any of these rules allows it. Or null, to remove the condition, so the field has no restriction.",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "type": {
                                                                        "type": "string",
                                                                        "description": "\"domain\" for anyone at exactly that domain (not its subdomains), or \"address\" for one address.",
                                                                        "enum": [
                                                                            "domain",
                                                                            "address"
                                                                        ]
                                                                    },
                                                                    "value": {
                                                                        "type": "string",
                                                                        "description": "The domain (e.g. \"example.org\") or address."
                                                                    }
                                                                },
                                                                "required": [
                                                                    "type",
                                                                    "value"
                                                                ]
                                                            },
                                                            "minItems": 1,
                                                            "nullable": true
                                                        }
                                                    },
                                                    "required": [
                                                        "field",
                                                        "allowed"
                                                    ]
                                                },
                                                {
                                                    "type": "object",
                                                    "properties": {
                                                        "field": {
                                                            "type": "string",
                                                            "description": "The providers the email token's emails go through.",
                                                            "enum": [
                                                                "provider"
                                                            ]
                                                        },
                                                        "allowed": {
                                                            "type": "array",
                                                            "description": "The ids of the providers the email token's emails may be sent through (GET /api/v1/providers lists them). The mode applies to those of them that are enabled, as if they were the only providers, and while none of them is enabled, its emails wait in the queue. Each must be a provider's id, enabled or not. An empty list is refused, but a token whose providers have all been removed since shows one, as it stays restricted (to none) rather than being allowed every provider. Or null, to remove the condition, so the field has no restriction.",
                                                            "items": {
                                                                "type": "string",
                                                                "format": "uuid"
                                                            },
                                                            "nullable": true
                                                        }
                                                    },
                                                    "required": [
                                                        "field",
                                                        "allowed"
                                                    ]
                                                }
                                            ]
                                        }
                                    },
                                    "rateLimits": {
                                        "type": "array",
                                        "description": "Rate limits that must all allow an email for it to be sent straight away, otherwise it's queued. Any mix of email and recipient limits can be given, but no two can have the same unit and period. Leave it empty (the default) for no limit. An email with more recipients than a recipient limit allows is refused (error code 23), as it could never be sent.",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "unit": {
                                                    "type": "string",
                                                    "description": "\"emails\" to limit the number of emails handed to the provider (each is one request, however many recipients it has), or \"recipients\" to limit the number of recipients (To, Cc and Bcc alike).",
                                                    "enum": [
                                                        "emails",
                                                        "recipients"
                                                    ]
                                                },
                                                "max": {
                                                    "type": "integer",
                                                    "description": "How many emails, or recipients, may be sent within the period.",
                                                    "minimum": 1
                                                },
                                                "periodSeconds": {
                                                    "type": "integer",
                                                    "description": "The length of the sliding window, in seconds.",
                                                    "minimum": 1,
                                                    "maximum": 2678400
                                                }
                                            },
                                            "required": [
                                                "unit",
                                                "max",
                                                "periodSeconds"
                                            ]
                                        }
                                    },
                                    "priority": {
                                        "type": "integer",
                                        "description": "How important the email token's emails are in the queue: a higher priority's emails are sent before a lower one's, though rate limits still apply. The service's own emails (password reset links) have priority 9999, so always go first.",
                                        "minimum": 1,
                                        "maximum": 9998,
                                        "default": 1
                                    }
                                }
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "The email token, as it is now.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "emailToken": {
                                            "type": "object",
                                            "properties": {
                                                "id": {
                                                    "type": "string",
                                                    "description": "The email token's ID: the first 19 characters of the token, and its SMTP username.",
                                                    "pattern": "^et_[0-9a-f]{16}$",
                                                    "example": "et_8af651aadbe3ff25"
                                                },
                                                "name": {
                                                    "type": "string"
                                                },
                                                "createdAt": {
                                                    "type": "string",
                                                    "format": "date-time"
                                                },
                                                "lastUsedAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "revokedAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "conditions": {
                                                    "type": "array",
                                                    "description": "What the email token is restricted to, one condition per field, each at most once. A field with no condition has no restriction, so leave out the whole list to allow anyone, from anywhere. An empty \"allowed\" list is refused, as it would allow nobody.",
                                                    "items": {
                                                        "oneOf": [
                                                            {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "The IP address the email token is used from.",
                                                                        "enum": [
                                                                            "clientIp"
                                                                        ]
                                                                    },
                                                                    "allowed": {
                                                                        "type": "array",
                                                                        "description": "The IP addresses or CIDR ranges the email token may be used from, e.g. \"10.0.0.0/8\".",
                                                                        "items": {
                                                                            "type": "string"
                                                                        },
                                                                        "minItems": 1
                                                                    }
                                                                },
                                                                "required": [
                                                                    "field",
                                                                    "allowed"
                                                                ]
                                                            },
                                                            {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "\"sender\" for who emails may be from (the envelope sender, and the From and Sender headers), \"replyTo\" for what the Reply-To header may contain (an email without one is always fine), or \"recipient\" for who emails may be sent to (to, cc and bcc alike).",
                                                                        "enum": [
                                                                            "sender",
                                                                            "replyTo",
                                                                            "recipient"
                                                                        ]
                                                                    },
                                                                    "allowed": {
                                                                        "type": "array",
                                                                        "description": "The addresses allowed: an address is allowed if any of these rules allows it.",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "type": {
                                                                                    "type": "string",
                                                                                    "description": "\"domain\" for anyone at exactly that domain (not its subdomains), or \"address\" for one address.",
                                                                                    "enum": [
                                                                                        "domain",
                                                                                        "address"
                                                                                    ]
                                                                                },
                                                                                "value": {
                                                                                    "type": "string",
                                                                                    "description": "The domain (e.g. \"example.org\") or address."
                                                                                }
                                                                            },
                                                                            "required": [
                                                                                "type",
                                                                                "value"
                                                                            ]
                                                                        },
                                                                        "minItems": 1
                                                                    }
                                                                },
                                                                "required": [
                                                                    "field",
                                                                    "allowed"
                                                                ]
                                                            },
                                                            {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "The providers the email token's emails go through.",
                                                                        "enum": [
                                                                            "provider"
                                                                        ]
                                                                    },
                                                                    "allowed": {
                                                                        "type": "array",
                                                                        "description": "The ids of the providers the email token's emails may be sent through (GET /api/v1/providers lists them). The mode applies to those of them that are enabled, as if they were the only providers, and while none of them is enabled, its emails wait in the queue. Each must be a provider's id, enabled or not. An empty list is refused, but a token whose providers have all been removed since shows one, as it stays restricted (to none) rather than being allowed every provider.",
                                                                        "items": {
                                                                            "type": "string",
                                                                            "format": "uuid"
                                                                        }
                                                                    }
                                                                },
                                                                "required": [
                                                                    "field",
                                                                    "allowed"
                                                                ]
                                                            }
                                                        ]
                                                    }
                                                },
                                                "rateLimits": {
                                                    "type": "array",
                                                    "description": "Rate limits that must all allow an email for it to be sent straight away, otherwise it's queued. Any mix of email and recipient limits can be given, but no two can have the same unit and period. Leave it empty (the default) for no limit. An email with more recipients than a recipient limit allows is refused (error code 23), as it could never be sent.",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "unit": {
                                                                "type": "string",
                                                                "description": "\"emails\" to limit the number of emails handed to the provider (each is one request, however many recipients it has), or \"recipients\" to limit the number of recipients (To, Cc and Bcc alike).",
                                                                "enum": [
                                                                    "emails",
                                                                    "recipients"
                                                                ]
                                                            },
                                                            "max": {
                                                                "type": "integer",
                                                                "description": "How many emails, or recipients, may be sent within the period.",
                                                                "minimum": 1
                                                            },
                                                            "periodSeconds": {
                                                                "type": "integer",
                                                                "description": "The length of the sliding window, in seconds.",
                                                                "minimum": 1,
                                                                "maximum": 2678400
                                                            }
                                                        },
                                                        "required": [
                                                            "unit",
                                                            "max",
                                                            "periodSeconds"
                                                        ]
                                                    }
                                                },
                                                "priority": {
                                                    "type": "integer",
                                                    "description": "How important the email token's emails are in the queue: a higher priority's emails are sent before a lower one's, though rate limits still apply. 1 if left out. The service's own emails (password reset links) have priority 9999, so always go first.",
                                                    "minimum": 1,
                                                    "maximum": 9998,
                                                    "default": 1
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "The request was invalid.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "There is no such record.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "It can't be done to the account in the state it's in (see the code).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Email tokens"
                ],
                "summary": "Revoke an email token",
                "description": "The email token stops working straight away, and any of its emails still in the queue are cancelled. Its history is kept, for the statistics. This can't be undone.",
                "operationId": "revokeEmailToken",
                "responses": {
                    "200": {
                        "description": "The email token was revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "emailToken": {
                                            "type": "object",
                                            "properties": {
                                                "id": {
                                                    "type": "string",
                                                    "description": "The email token's ID: the first 19 characters of the token, and its SMTP username.",
                                                    "pattern": "^et_[0-9a-f]{16}$",
                                                    "example": "et_8af651aadbe3ff25"
                                                },
                                                "name": {
                                                    "type": "string"
                                                },
                                                "createdAt": {
                                                    "type": "string",
                                                    "format": "date-time"
                                                },
                                                "lastUsedAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "revokedAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "conditions": {
                                                    "type": "array",
                                                    "description": "What the email token is restricted to, one condition per field, each at most once. A field with no condition has no restriction, so leave out the whole list to allow anyone, from anywhere. An empty \"allowed\" list is refused, as it would allow nobody.",
                                                    "items": {
                                                        "oneOf": [
                                                            {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "The IP address the email token is used from.",
                                                                        "enum": [
                                                                            "clientIp"
                                                                        ]
                                                                    },
                                                                    "allowed": {
                                                                        "type": "array",
                                                                        "description": "The IP addresses or CIDR ranges the email token may be used from, e.g. \"10.0.0.0/8\".",
                                                                        "items": {
                                                                            "type": "string"
                                                                        },
                                                                        "minItems": 1
                                                                    }
                                                                },
                                                                "required": [
                                                                    "field",
                                                                    "allowed"
                                                                ]
                                                            },
                                                            {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "\"sender\" for who emails may be from (the envelope sender, and the From and Sender headers), \"replyTo\" for what the Reply-To header may contain (an email without one is always fine), or \"recipient\" for who emails may be sent to (to, cc and bcc alike).",
                                                                        "enum": [
                                                                            "sender",
                                                                            "replyTo",
                                                                            "recipient"
                                                                        ]
                                                                    },
                                                                    "allowed": {
                                                                        "type": "array",
                                                                        "description": "The addresses allowed: an address is allowed if any of these rules allows it.",
                                                                        "items": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                                "type": {
                                                                                    "type": "string",
                                                                                    "description": "\"domain\" for anyone at exactly that domain (not its subdomains), or \"address\" for one address.",
                                                                                    "enum": [
                                                                                        "domain",
                                                                                        "address"
                                                                                    ]
                                                                                },
                                                                                "value": {
                                                                                    "type": "string",
                                                                                    "description": "The domain (e.g. \"example.org\") or address."
                                                                                }
                                                                            },
                                                                            "required": [
                                                                                "type",
                                                                                "value"
                                                                            ]
                                                                        },
                                                                        "minItems": 1
                                                                    }
                                                                },
                                                                "required": [
                                                                    "field",
                                                                    "allowed"
                                                                ]
                                                            },
                                                            {
                                                                "type": "object",
                                                                "properties": {
                                                                    "field": {
                                                                        "type": "string",
                                                                        "description": "The providers the email token's emails go through.",
                                                                        "enum": [
                                                                            "provider"
                                                                        ]
                                                                    },
                                                                    "allowed": {
                                                                        "type": "array",
                                                                        "description": "The ids of the providers the email token's emails may be sent through (GET /api/v1/providers lists them). The mode applies to those of them that are enabled, as if they were the only providers, and while none of them is enabled, its emails wait in the queue. Each must be a provider's id, enabled or not. An empty list is refused, but a token whose providers have all been removed since shows one, as it stays restricted (to none) rather than being allowed every provider.",
                                                                        "items": {
                                                                            "type": "string",
                                                                            "format": "uuid"
                                                                        }
                                                                    }
                                                                },
                                                                "required": [
                                                                    "field",
                                                                    "allowed"
                                                                ]
                                                            }
                                                        ]
                                                    }
                                                },
                                                "rateLimits": {
                                                    "type": "array",
                                                    "description": "Rate limits that must all allow an email for it to be sent straight away, otherwise it's queued. Any mix of email and recipient limits can be given, but no two can have the same unit and period. Leave it empty (the default) for no limit. An email with more recipients than a recipient limit allows is refused (error code 23), as it could never be sent.",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "unit": {
                                                                "type": "string",
                                                                "description": "\"emails\" to limit the number of emails handed to the provider (each is one request, however many recipients it has), or \"recipients\" to limit the number of recipients (To, Cc and Bcc alike).",
                                                                "enum": [
                                                                    "emails",
                                                                    "recipients"
                                                                ]
                                                            },
                                                            "max": {
                                                                "type": "integer",
                                                                "description": "How many emails, or recipients, may be sent within the period.",
                                                                "minimum": 1
                                                            },
                                                            "periodSeconds": {
                                                                "type": "integer",
                                                                "description": "The length of the sliding window, in seconds.",
                                                                "minimum": 1,
                                                                "maximum": 2678400
                                                            }
                                                        },
                                                        "required": [
                                                            "unit",
                                                            "max",
                                                            "periodSeconds"
                                                        ]
                                                    }
                                                },
                                                "priority": {
                                                    "type": "integer",
                                                    "description": "How important the email token's emails are in the queue: a higher priority's emails are sent before a lower one's, though rate limits still apply. 1 if left out. The service's own emails (password reset links) have priority 9999, so always go first.",
                                                    "minimum": 1,
                                                    "maximum": 9998,
                                                    "default": 1
                                                }
                                            }
                                        },
                                        "cancelledQueuedEmails": {
                                            "type": "integer",
                                            "description": "How many of the email token's emails were still queued, and were cancelled."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "There is no such record.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "description": "The email token's ID, e.g. et_8af651aadbe3ff25.",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "pattern": "^et_[0-9a-f]{16}$",
                        "example": "et_8af651aadbe3ff25"
                    }
                }
            ]
        },
        "/email-tokens/{id}/stats": {
            "get": {
                "tags": [
                    "Statistics"
                ],
                "summary": "Get an email token's statistics",
                "operationId": "getEmailTokenStats",
                "responses": {
                    "200": {
                        "description": "The email token's statistics.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "activity": {
                                            "type": "object",
                                            "properties": {
                                                "acceptedLastMinute": {
                                                    "type": "integer"
                                                },
                                                "acceptedLastHour": {
                                                    "type": "integer"
                                                },
                                                "acceptedLast24Hours": {
                                                    "type": "integer"
                                                },
                                                "acceptedLast7Days": {
                                                    "type": "integer"
                                                },
                                                "queuedNow": {
                                                    "type": "integer"
                                                },
                                                "failedLast24Hours": {
                                                    "type": "integer"
                                                },
                                                "rejectedLastHour": {
                                                    "type": "integer"
                                                },
                                                "rejectedLast24Hours": {
                                                    "type": "integer"
                                                },
                                                "rejectedLast7Days": {
                                                    "type": "integer"
                                                },
                                                "deliveredLast7Days": {
                                                    "type": "integer"
                                                },
                                                "bouncedLast7Days": {
                                                    "type": "integer"
                                                },
                                                "openedLast7Days": {
                                                    "type": "integer"
                                                },
                                                "clickedLast7Days": {
                                                    "type": "integer"
                                                },
                                                "spamReportsLast7Days": {
                                                    "type": "integer"
                                                },
                                                "rejectedByServiceLast24Hours": {
                                                    "type": "integer"
                                                },
                                                "refusedWhileWaitingLast24Hours": {
                                                    "type": "integer"
                                                },
                                                "failedAfterQueueingLast24Hours": {
                                                    "type": "integer"
                                                },
                                                "retryingNow": {
                                                    "type": "integer"
                                                }
                                            }
                                        },
                                        "hourly": {
                                            "type": "array",
                                            "description": "The last 24 hours, oldest first.",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "hourStart": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    },
                                                    "accepted": {
                                                        "type": "integer",
                                                        "description": "How many emails were accepted in the hour."
                                                    },
                                                    "queued": {
                                                        "type": "integer",
                                                        "description": "How many of those had to wait in the queue."
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "There is no such record.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "description": "The email token's ID, e.g. et_8af651aadbe3ff25.",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "pattern": "^et_[0-9a-f]{16}$",
                        "example": "et_8af651aadbe3ff25"
                    }
                }
            ]
        },
        "/rate-limits": {
            "get": {
                "tags": [
                    "Rate limits"
                ],
                "summary": "Get the global rate limits",
                "operationId": "getRateLimits",
                "responses": {
                    "200": {
                        "description": "The global rate limits.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "rateLimits": {
                                            "type": "array",
                                            "description": "Rate limits that must all allow an email for it to be sent straight away, otherwise it's queued. Any mix of email and recipient limits can be given, but no two can have the same unit and period. Leave it empty (the default) for no limit. An email with more recipients than a recipient limit allows is refused (error code 23), as it could never be sent.",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "unit": {
                                                        "type": "string",
                                                        "description": "\"emails\" to limit the number of emails handed to the provider (each is one request, however many recipients it has), or \"recipients\" to limit the number of recipients (To, Cc and Bcc alike).",
                                                        "enum": [
                                                            "emails",
                                                            "recipients"
                                                        ]
                                                    },
                                                    "max": {
                                                        "type": "integer",
                                                        "description": "How many emails, or recipients, may be sent within the period.",
                                                        "minimum": 1
                                                    },
                                                    "periodSeconds": {
                                                        "type": "integer",
                                                        "description": "The length of the sliding window, in seconds.",
                                                        "minimum": 1,
                                                        "maximum": 2678400
                                                    }
                                                },
                                                "required": [
                                                    "unit",
                                                    "max",
                                                    "periodSeconds"
                                                ]
                                            }
                                        }
                                    },
                                    "required": [
                                        "rateLimits"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "put": {
                "tags": [
                    "Rate limits"
                ],
                "summary": "Replace the global rate limits",
                "description": "Replaces every global rate limit. An empty array removes them all. An email that would go over a limit is queued, not refused.",
                "operationId": "replaceRateLimits",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "rateLimits": {
                                        "type": "array",
                                        "description": "Rate limits that must all allow an email for it to be sent straight away, otherwise it's queued. Any mix of email and recipient limits can be given, but no two can have the same unit and period. Leave it empty (the default) for no limit. An email with more recipients than a recipient limit allows is refused (error code 23), as it could never be sent.",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "unit": {
                                                    "type": "string",
                                                    "description": "\"emails\" to limit the number of emails handed to the provider (each is one request, however many recipients it has), or \"recipients\" to limit the number of recipients (To, Cc and Bcc alike).",
                                                    "enum": [
                                                        "emails",
                                                        "recipients"
                                                    ]
                                                },
                                                "max": {
                                                    "type": "integer",
                                                    "description": "How many emails, or recipients, may be sent within the period.",
                                                    "minimum": 1
                                                },
                                                "periodSeconds": {
                                                    "type": "integer",
                                                    "description": "The length of the sliding window, in seconds.",
                                                    "minimum": 1,
                                                    "maximum": 2678400
                                                }
                                            },
                                            "required": [
                                                "unit",
                                                "max",
                                                "periodSeconds"
                                            ]
                                        }
                                    }
                                },
                                "required": [
                                    "rateLimits"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "The new global rate limits.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "rateLimits": {
                                            "type": "array",
                                            "description": "Rate limits that must all allow an email for it to be sent straight away, otherwise it's queued. Any mix of email and recipient limits can be given, but no two can have the same unit and period. Leave it empty (the default) for no limit. An email with more recipients than a recipient limit allows is refused (error code 23), as it could never be sent.",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "unit": {
                                                        "type": "string",
                                                        "description": "\"emails\" to limit the number of emails handed to the provider (each is one request, however many recipients it has), or \"recipients\" to limit the number of recipients (To, Cc and Bcc alike).",
                                                        "enum": [
                                                            "emails",
                                                            "recipients"
                                                        ]
                                                    },
                                                    "max": {
                                                        "type": "integer",
                                                        "description": "How many emails, or recipients, may be sent within the period.",
                                                        "minimum": 1
                                                    },
                                                    "periodSeconds": {
                                                        "type": "integer",
                                                        "description": "The length of the sliding window, in seconds.",
                                                        "minimum": 1,
                                                        "maximum": 2678400
                                                    }
                                                },
                                                "required": [
                                                    "unit",
                                                    "max",
                                                    "periodSeconds"
                                                ]
                                            }
                                        }
                                    },
                                    "required": [
                                        "rateLimits"
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "The request was invalid.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/stats": {
            "get": {
                "tags": [
                    "Statistics"
                ],
                "summary": "Get the statistics",
                "operationId": "getStats",
                "responses": {
                    "200": {
                        "description": "The statistics, across every email token.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "activity": {
                                            "type": "object",
                                            "properties": {
                                                "acceptedLastMinute": {
                                                    "type": "integer"
                                                },
                                                "acceptedLastHour": {
                                                    "type": "integer"
                                                },
                                                "acceptedLast24Hours": {
                                                    "type": "integer"
                                                },
                                                "acceptedLast7Days": {
                                                    "type": "integer"
                                                },
                                                "queuedNow": {
                                                    "type": "integer"
                                                },
                                                "failedLast24Hours": {
                                                    "type": "integer"
                                                },
                                                "rejectedLastHour": {
                                                    "type": "integer"
                                                },
                                                "rejectedLast24Hours": {
                                                    "type": "integer"
                                                },
                                                "rejectedLast7Days": {
                                                    "type": "integer"
                                                },
                                                "deliveredLast7Days": {
                                                    "type": "integer"
                                                },
                                                "bouncedLast7Days": {
                                                    "type": "integer"
                                                },
                                                "openedLast7Days": {
                                                    "type": "integer"
                                                },
                                                "clickedLast7Days": {
                                                    "type": "integer"
                                                },
                                                "spamReportsLast7Days": {
                                                    "type": "integer"
                                                },
                                                "rejectedByServiceLast24Hours": {
                                                    "type": "integer"
                                                },
                                                "refusedWhileWaitingLast24Hours": {
                                                    "type": "integer"
                                                },
                                                "failedAfterQueueingLast24Hours": {
                                                    "type": "integer"
                                                },
                                                "retryingNow": {
                                                    "type": "integer"
                                                }
                                            }
                                        },
                                        "hourly": {
                                            "type": "array",
                                            "description": "The last 24 hours, oldest first.",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "hourStart": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    },
                                                    "accepted": {
                                                        "type": "integer",
                                                        "description": "How many emails were accepted in the hour."
                                                    },
                                                    "queued": {
                                                        "type": "integer",
                                                        "description": "How many of those had to wait in the queue."
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/messages": {
            "get": {
                "tags": [
                    "Statistics"
                ],
                "summary": "List the most recent emails",
                "operationId": "listMessages",
                "parameters": [
                    {
                        "name": "emailTokenId",
                        "in": "query",
                        "description": "Only emails sent with this email token.",
                        "schema": {
                            "type": "string",
                            "pattern": "^et_[0-9a-f]{16}$",
                            "example": "et_8af651aadbe3ff25"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "description": "Only emails with this status.",
                            "enum": [
                                "queued",
                                "sending",
                                "sent",
                                "failed",
                                "cancelled"
                            ]
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "The most to return.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 500,
                            "default": 100
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The emails, newest first.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "messages": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "id": {
                                                        "type": "string",
                                                        "format": "uuid"
                                                    },
                                                    "emailTokenId": {
                                                        "type": "string",
                                                        "description": "The email token it was sent with, or null for the service's own emails (e.g. password resets).",
                                                        "pattern": "^et_[0-9a-f]{16}$",
                                                        "nullable": true,
                                                        "example": "et_8af651aadbe3ff25"
                                                    },
                                                    "source": {
                                                        "type": "string",
                                                        "description": "How it was sent.",
                                                        "enum": [
                                                            "smtp",
                                                            "api",
                                                            "system"
                                                        ]
                                                    },
                                                    "clientIp": {
                                                        "type": "string"
                                                    },
                                                    "envelopeSender": {
                                                        "type": "string",
                                                        "format": "email"
                                                    },
                                                    "recipients": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "string",
                                                            "format": "email"
                                                        }
                                                    },
                                                    "subject": {
                                                        "type": "string"
                                                    },
                                                    "sizeBytes": {
                                                        "type": "integer"
                                                    },
                                                    "status": {
                                                        "type": "string",
                                                        "description": "Where the email is in its journey.",
                                                        "enum": [
                                                            "queued",
                                                            "sending",
                                                            "sent",
                                                            "failed",
                                                            "cancelled"
                                                        ]
                                                    },
                                                    "wasQueued": {
                                                        "type": "boolean",
                                                        "description": "Whether it had to wait in the queue."
                                                    },
                                                    "attempts": {
                                                        "type": "integer",
                                                        "description": "How many times it has been handed to the provider."
                                                    },
                                                    "createdAt": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    },
                                                    "sentAt": {
                                                        "type": "string",
                                                        "format": "date-time",
                                                        "nullable": true
                                                    },
                                                    "provider": {
                                                        "type": "string",
                                                        "nullable": true
                                                    },
                                                    "providerMessageId": {
                                                        "type": "string",
                                                        "nullable": true
                                                    },
                                                    "lastError": {
                                                        "type": "string",
                                                        "nullable": true
                                                    },
                                                    "hasContent": {
                                                        "type": "boolean",
                                                        "description": "Whether its content can be downloaded from /messages/{id}/raw (see the retention settings)."
                                                    },
                                                    "removedAttachments": {
                                                        "type": "integer",
                                                        "description": "How many attachments have been removed from its stored content (see the retention settings). They're listed in attachments-removed.txt, which takes their place."
                                                    },
                                                    "priority": {
                                                        "type": "integer",
                                                        "description": "The priority it was queued with: its email token's, or 9999 for the service's own emails."
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "The request was invalid.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/messages/{id}": {
            "get": {
                "tags": [
                    "Statistics"
                ],
                "summary": "Get an email",
                "operationId": "getMessage",
                "responses": {
                    "200": {
                        "description": "The email, and its tracking events.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "object",
                                            "properties": {
                                                "id": {
                                                    "type": "string",
                                                    "format": "uuid"
                                                },
                                                "emailTokenId": {
                                                    "type": "string",
                                                    "description": "The email token it was sent with, or null for the service's own emails (e.g. password resets).",
                                                    "pattern": "^et_[0-9a-f]{16}$",
                                                    "nullable": true,
                                                    "example": "et_8af651aadbe3ff25"
                                                },
                                                "source": {
                                                    "type": "string",
                                                    "description": "How it was sent.",
                                                    "enum": [
                                                        "smtp",
                                                        "api",
                                                        "system"
                                                    ]
                                                },
                                                "clientIp": {
                                                    "type": "string"
                                                },
                                                "envelopeSender": {
                                                    "type": "string",
                                                    "format": "email"
                                                },
                                                "recipients": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string",
                                                        "format": "email"
                                                    }
                                                },
                                                "subject": {
                                                    "type": "string"
                                                },
                                                "sizeBytes": {
                                                    "type": "integer"
                                                },
                                                "status": {
                                                    "type": "string",
                                                    "description": "Where the email is in its journey.",
                                                    "enum": [
                                                        "queued",
                                                        "sending",
                                                        "sent",
                                                        "failed",
                                                        "cancelled"
                                                    ]
                                                },
                                                "wasQueued": {
                                                    "type": "boolean",
                                                    "description": "Whether it had to wait in the queue."
                                                },
                                                "attempts": {
                                                    "type": "integer",
                                                    "description": "How many times it has been handed to the provider."
                                                },
                                                "createdAt": {
                                                    "type": "string",
                                                    "format": "date-time"
                                                },
                                                "sentAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "provider": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "providerMessageId": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "lastError": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "hasContent": {
                                                    "type": "boolean",
                                                    "description": "Whether its content can be downloaded from /messages/{id}/raw (see the retention settings)."
                                                },
                                                "removedAttachments": {
                                                    "type": "integer",
                                                    "description": "How many attachments have been removed from its stored content (see the retention settings). They're listed in attachments-removed.txt, which takes their place."
                                                },
                                                "priority": {
                                                    "type": "integer",
                                                    "description": "The priority it was queued with: its email token's, or 9999 for the service's own emails."
                                                }
                                            }
                                        },
                                        "deliveryAttempts": {
                                            "type": "array",
                                            "description": "Each time it was handed to a provider, oldest first. Each one counts towards that provider's rate limits, failed ones included.",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "provider": {
                                                        "type": "string",
                                                        "description": "The provider's name, from settings.yaml."
                                                    },
                                                    "outcome": {
                                                        "type": "string",
                                                        "description": "How it ended.",
                                                        "enum": [
                                                            "sending",
                                                            "sent",
                                                            "temporary_failure",
                                                            "refused",
                                                            "unavailable",
                                                            "rate_limited",
                                                            "interrupted"
                                                        ]
                                                    },
                                                    "dispatchedAt": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    },
                                                    "finishedAt": {
                                                        "type": "string",
                                                        "format": "date-time",
                                                        "nullable": true
                                                    },
                                                    "error": {
                                                        "type": "string",
                                                        "description": "Why it failed, if it did.",
                                                        "nullable": true
                                                    }
                                                }
                                            }
                                        },
                                        "events": {
                                            "type": "array",
                                            "description": "What the provider reported happening to the email, oldest first.",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "type": {
                                                        "type": "string",
                                                        "description": "What happened.",
                                                        "enum": [
                                                            "processed",
                                                            "delivered",
                                                            "deferred",
                                                            "bounced",
                                                            "dropped",
                                                            "opened",
                                                            "clicked",
                                                            "spam_report",
                                                            "unsubscribed",
                                                            "other"
                                                        ]
                                                    },
                                                    "recipient": {
                                                        "type": "string",
                                                        "description": "Which recipient it happened for.",
                                                        "nullable": true
                                                    },
                                                    "detail": {
                                                        "type": "string",
                                                        "description": "Any detail, such as a bounce reason or a clicked link.",
                                                        "nullable": true
                                                    },
                                                    "occurredAt": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "There is no such record.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "description": "The email's ID.",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/messages/{id}/raw": {
            "get": {
                "tags": [
                    "Statistics"
                ],
                "summary": "Download an email's content",
                "operationId": "downloadMessage",
                "responses": {
                    "200": {
                        "description": "The email, exactly as it was handed to the provider (message/rfc822). Only available while its content is kept, which is set on the Settings page: by default it's deleted once sent. Once its attachments have been removed (also set there), it's without them, and has an attachments-removed.txt listing them instead.",
                        "content": {
                            "text/plain": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "There is no such record.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "description": "The email's ID.",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/send": {
            "post": {
                "tags": [
                    "Sending"
                ],
                "summary": "Send an email",
                "description": "Authenticated with an email token, as a bearer token. The email must keep to the token's restrictions: its sender, reply-to and every recipient (to, cc and bcc) must be allowed, and the request must come from an allowed IP address. If the token is restricted to particular providers, it's only sent through those of them that are enabled, and is queued while none of them is. Only providers that take its sender (its envelope sender, and the From and Sender headers) are used, and if no provider the token can use takes it, it's refused (403, code 24).",
                "operationId": "send",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "from": {
                                        "type": "object",
                                        "properties": {
                                            "email": {
                                                "type": "string",
                                                "format": "email"
                                            },
                                            "name": {
                                                "type": "string",
                                                "description": "The display name. Optional."
                                            }
                                        },
                                        "required": [
                                            "email"
                                        ]
                                    },
                                    "replyTo": {
                                        "type": "object",
                                        "properties": {
                                            "email": {
                                                "type": "string",
                                                "format": "email"
                                            },
                                            "name": {
                                                "type": "string",
                                                "description": "The display name. Optional."
                                            }
                                        },
                                        "required": [
                                            "email"
                                        ]
                                    },
                                    "to": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "email": {
                                                    "type": "string",
                                                    "format": "email"
                                                },
                                                "name": {
                                                    "type": "string",
                                                    "description": "The display name. Optional."
                                                }
                                            },
                                            "required": [
                                                "email"
                                            ]
                                        },
                                        "minItems": 1
                                    },
                                    "cc": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "email": {
                                                    "type": "string",
                                                    "format": "email"
                                                },
                                                "name": {
                                                    "type": "string",
                                                    "description": "The display name. Optional."
                                                }
                                            },
                                            "required": [
                                                "email"
                                            ]
                                        }
                                    },
                                    "bcc": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "email": {
                                                    "type": "string",
                                                    "format": "email"
                                                },
                                                "name": {
                                                    "type": "string",
                                                    "description": "The display name. Optional."
                                                }
                                            },
                                            "required": [
                                                "email"
                                            ]
                                        }
                                    },
                                    "subject": {
                                        "type": "string",
                                        "minLength": 1
                                    },
                                    "text": {
                                        "type": "string",
                                        "description": "The plain text body. A text or html body (or both) is required."
                                    },
                                    "html": {
                                        "type": "string",
                                        "description": "The HTML body. The text body, if given, is its plain text alternative."
                                    },
                                    "attachments": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "filename": {
                                                    "type": "string"
                                                },
                                                "content": {
                                                    "type": "string",
                                                    "description": "The file's content, base64 encoded."
                                                },
                                                "contentType": {
                                                    "type": "string",
                                                    "description": "The MIME type. Defaults to application/octet-stream.",
                                                    "default": "application/octet-stream"
                                                }
                                            },
                                            "required": [
                                                "filename",
                                                "content"
                                            ]
                                        }
                                    }
                                },
                                "required": [
                                    "from",
                                    "to",
                                    "subject"
                                ]
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "The email was handed to the provider straight away.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "string",
                                            "description": "The email's ID.",
                                            "format": "uuid"
                                        },
                                        "status": {
                                            "type": "string",
                                            "description": "Whether the email was sent straight away, or queued.",
                                            "enum": [
                                                "sent",
                                                "queued"
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "202": {
                        "description": "The email was accepted, and queued, because a rate limit (or the provider being unavailable) meant it couldn't be sent straight away. It will be sent as soon as possible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "string",
                                            "description": "The email's ID.",
                                            "format": "uuid"
                                        },
                                        "status": {
                                            "type": "string",
                                            "description": "Whether the email was sent straight away, or queued.",
                                            "enum": [
                                                "sent",
                                                "queued"
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "The request was invalid.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "413": {
                        "description": "The email is larger than the limit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "The provider refused the email.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "emailToken": []
                    }
                ]
            }
        },
        "/providers": {
            "get": {
                "tags": [
                    "Providers"
                ],
                "summary": "Get the providers",
                "operationId": "getProviders",
                "responses": {
                    "200": {
                        "description": "The providers, and whether each is available.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "version": {
                                            "type": "string",
                                            "description": "The version of the providers, to send as If-Match when replacing them. Also the ETag."
                                        },
                                        "config": {
                                            "type": "object",
                                            "description": "The same structure as settings.yaml's providers section: a \"mode\" (round_robin, overflow or fallback), and a list of \"providers\", each with an \"id\" (a UUID, which email tokens' \"provider\" conditions refer to, made when it's left out, or kept from the provider of the same name), a \"name\", \"type\" (sendgrid, mailgun, postmark, brevo, mailjet, mailersend, mailtrap, custom), \"enabled\", an optional \"allowed_senders\" (\"domains\" and \"addresses\" lists: it only takes email from a sender at any of the domains, or with any of the addresses, and takes any sender when it's left out), \"rate_limits\" (each with a \"unit\", \"max\" and \"period_seconds\"), and the settings for its type (see \"Types of provider\" in the README, e.g. sendgrid: api_key and webhook_public_key). Secrets (passwords, keys and tokens) are returned as \"<unchanged>\", and kept as they are if sent back that way. Settings can't be read from environment variables, so a \"${NAME}\" reference to one is refused. Unknown settings are refused. Null before any providers have been set up (on a fresh install), when the version is the one to add the first ones with.",
                                            "nullable": true
                                        },
                                        "status": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "name": {
                                                        "type": "string"
                                                    },
                                                    "available": {
                                                        "type": "boolean",
                                                        "description": "False while it's skipped, as it couldn't be connected to."
                                                    },
                                                    "unavailableUntil": {
                                                        "type": "string",
                                                        "format": "date-time",
                                                        "nullable": true
                                                    },
                                                    "lastError": {
                                                        "type": "string",
                                                        "nullable": true
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "put": {
                "tags": [
                    "Providers"
                ],
                "summary": "Replace the providers",
                "description": "Replaces the providers (settings.yaml's providers section, leaving its other settings as they are), from JSON (the \"config\" structure) or YAML (with a Content-Type of application/yaml). They're checked before they're saved, and the queue workers use them from their next email, sending any emails that were queued while there were none. At least one provider must be enabled. A provider given without an \"id\" keeps the id of the current provider with the same name, so it stays linked to its email tokens. Removing a provider removes email tokens' links to it.",
                "operationId": "replaceProviders",
                "parameters": [
                    {
                        "name": "If-Match",
                        "in": "header",
                        "description": "The version from GET /providers. If the providers have changed since, the request is refused (412).",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "description": "The same structure as settings.yaml's providers section: a \"mode\" (round_robin, overflow or fallback), and a list of \"providers\", each with an \"id\" (a UUID, which email tokens' \"provider\" conditions refer to, made when it's left out, or kept from the provider of the same name), a \"name\", \"type\" (sendgrid, mailgun, postmark, brevo, mailjet, mailersend, mailtrap, custom), \"enabled\", an optional \"allowed_senders\" (\"domains\" and \"addresses\" lists: it only takes email from a sender at any of the domains, or with any of the addresses, and takes any sender when it's left out), \"rate_limits\" (each with a \"unit\", \"max\" and \"period_seconds\"), and the settings for its type (see \"Types of provider\" in the README, e.g. sendgrid: api_key and webhook_public_key). Secrets (passwords, keys and tokens) are returned as \"<unchanged>\", and kept as they are if sent back that way. Settings can't be read from environment variables, so a \"${NAME}\" reference to one is refused. Unknown settings are refused."
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "The providers were replaced.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "version": {
                                            "type": "string",
                                            "description": "The new version."
                                        },
                                        "config": {
                                            "type": "object",
                                            "description": "The same structure as settings.yaml's providers section: a \"mode\" (round_robin, overflow or fallback), and a list of \"providers\", each with an \"id\" (a UUID, which email tokens' \"provider\" conditions refer to, made when it's left out, or kept from the provider of the same name), a \"name\", \"type\" (sendgrid, mailgun, postmark, brevo, mailjet, mailersend, mailtrap, custom), \"enabled\", an optional \"allowed_senders\" (\"domains\" and \"addresses\" lists: it only takes email from a sender at any of the domains, or with any of the addresses, and takes any sender when it's left out), \"rate_limits\" (each with a \"unit\", \"max\" and \"period_seconds\"), and the settings for its type (see \"Types of provider\" in the README, e.g. sendgrid: api_key and webhook_public_key). Secrets (passwords, keys and tokens) are returned as \"<unchanged>\", and kept as they are if sent back that way. Settings can't be read from environment variables, so a \"${NAME}\" reference to one is refused. Unknown settings are refused."
                                        },
                                        "unlinkedEmailTokenIds": {
                                            "type": "array",
                                            "description": "The email tokens that were restricted to a provider that's no longer there (or now has another id), which have lost their link to it. Each stays restricted to its other providers, or to none, so its emails wait in the queue until it's given one.",
                                            "items": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "The request was invalid.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "412": {
                        "description": "It has been changed since the version given in If-Match.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "428": {
                        "description": "An If-Match header is required.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/providers/export": {
            "get": {
                "tags": [
                    "Providers"
                ],
                "summary": "Export the providers as YAML",
                "operationId": "exportProviders",
                "responses": {
                    "200": {
                        "description": "The providers (settings.yaml's providers section) as YAML, as a backup, with every secret (password, key and token) written out in full, so it mustn't be committed to version control or shared. 404, with the error code 31, before any providers have been set up.",
                        "content": {
                            "text/plain": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "There is no such record.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/users": {
            "get": {
                "tags": [
                    "Users"
                ],
                "summary": "List the accounts",
                "operationId": "listUsers",
                "parameters": [
                    {
                        "name": "archived",
                        "in": "query",
                        "description": "Whether to include archived accounts.",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The accounts: the active and blocked ones by email address, then any archived ones.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "users": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "id": {
                                                        "type": "string",
                                                        "format": "uuid"
                                                    },
                                                    "status": {
                                                        "type": "string",
                                                        "description": "\"active\", \"blocked\" (can't log in until it's unblocked), or \"archived\" (blocked, with its email address and sign-in details removed).",
                                                        "enum": [
                                                            "active",
                                                            "blocked",
                                                            "archived"
                                                        ]
                                                    },
                                                    "email": {
                                                        "type": "string",
                                                        "description": "What it logs in with. Null when it's archived.",
                                                        "nullable": true
                                                    },
                                                    "createdAt": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    },
                                                    "statusChangedAt": {
                                                        "type": "string",
                                                        "format": "date-time",
                                                        "nullable": true
                                                    },
                                                    "lastLoginAt": {
                                                        "type": "string",
                                                        "format": "date-time",
                                                        "nullable": true
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/users/{id}": {
            "get": {
                "tags": [
                    "Users"
                ],
                "summary": "Get an account",
                "operationId": "getUser",
                "responses": {
                    "200": {
                        "description": "The account.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "user": {
                                            "type": "object",
                                            "properties": {
                                                "id": {
                                                    "type": "string",
                                                    "format": "uuid"
                                                },
                                                "status": {
                                                    "type": "string",
                                                    "description": "\"active\", \"blocked\" (can't log in until it's unblocked), or \"archived\" (blocked, with its email address and sign-in details removed).",
                                                    "enum": [
                                                        "active",
                                                        "blocked",
                                                        "archived"
                                                    ]
                                                },
                                                "email": {
                                                    "type": "string",
                                                    "description": "What it logs in with. Null when it's archived.",
                                                    "nullable": true
                                                },
                                                "createdAt": {
                                                    "type": "string",
                                                    "format": "date-time"
                                                },
                                                "statusChangedAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "lastLoginAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "There is no such record.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Users"
                ],
                "summary": "Delete an archived account",
                "description": "Deletes an archived account for good, with everything linked to it. Only an archived account can be deleted: archive it first (409, code 40, otherwise). Log entries that name it keep its ID.",
                "operationId": "deleteUser",
                "responses": {
                    "204": {
                        "description": "The account was deleted."
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "There is no such record.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "It can't be done to the account in the state it's in (see the code).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "description": "The account's ID.",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/users/{id}/block": {
            "post": {
                "tags": [
                    "Users"
                ],
                "summary": "Block an account",
                "description": "The account can't log in until it's unblocked, and is logged out everywhere. The last account that can log in can't be blocked (409, code 42).",
                "operationId": "blockUser",
                "responses": {
                    "200": {
                        "description": "The account, as it now is.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "user": {
                                            "type": "object",
                                            "properties": {
                                                "id": {
                                                    "type": "string",
                                                    "format": "uuid"
                                                },
                                                "status": {
                                                    "type": "string",
                                                    "description": "\"active\", \"blocked\" (can't log in until it's unblocked), or \"archived\" (blocked, with its email address and sign-in details removed).",
                                                    "enum": [
                                                        "active",
                                                        "blocked",
                                                        "archived"
                                                    ]
                                                },
                                                "email": {
                                                    "type": "string",
                                                    "description": "What it logs in with. Null when it's archived.",
                                                    "nullable": true
                                                },
                                                "createdAt": {
                                                    "type": "string",
                                                    "format": "date-time"
                                                },
                                                "statusChangedAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "lastLoginAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "There is no such record.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "It can't be done to the account in the state it's in (see the code).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "description": "The account's ID.",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/users/{id}/unblock": {
            "post": {
                "tags": [
                    "Users"
                ],
                "summary": "Unblock an account",
                "description": "The account can log in again. An archived account can't be unblocked (409, code 41).",
                "operationId": "unblockUser",
                "responses": {
                    "200": {
                        "description": "The account, as it now is.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "user": {
                                            "type": "object",
                                            "properties": {
                                                "id": {
                                                    "type": "string",
                                                    "format": "uuid"
                                                },
                                                "status": {
                                                    "type": "string",
                                                    "description": "\"active\", \"blocked\" (can't log in until it's unblocked), or \"archived\" (blocked, with its email address and sign-in details removed).",
                                                    "enum": [
                                                        "active",
                                                        "blocked",
                                                        "archived"
                                                    ]
                                                },
                                                "email": {
                                                    "type": "string",
                                                    "description": "What it logs in with. Null when it's archived.",
                                                    "nullable": true
                                                },
                                                "createdAt": {
                                                    "type": "string",
                                                    "format": "date-time"
                                                },
                                                "statusChangedAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "lastLoginAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "There is no such record.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "It can't be done to the account in the state it's in (see the code).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "description": "The account's ID.",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/users/{id}/archive": {
            "post": {
                "tags": [
                    "Users"
                ],
                "summary": "Archive an account",
                "description": "Blocks the account, and removes its email address, password, authenticator app, security keys and backup codes, keeping only its ID, which is all the logs name it by: a delete that's good enough for a GDPR erasure request. It can then be restored in the web interface (with its email address entered again), or deleted. The last account that can log in can't be archived (409, code 42).",
                "operationId": "archiveUser",
                "responses": {
                    "200": {
                        "description": "The account, as it now is.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "user": {
                                            "type": "object",
                                            "properties": {
                                                "id": {
                                                    "type": "string",
                                                    "format": "uuid"
                                                },
                                                "status": {
                                                    "type": "string",
                                                    "description": "\"active\", \"blocked\" (can't log in until it's unblocked), or \"archived\" (blocked, with its email address and sign-in details removed).",
                                                    "enum": [
                                                        "active",
                                                        "blocked",
                                                        "archived"
                                                    ]
                                                },
                                                "email": {
                                                    "type": "string",
                                                    "description": "What it logs in with. Null when it's archived.",
                                                    "nullable": true
                                                },
                                                "createdAt": {
                                                    "type": "string",
                                                    "format": "date-time"
                                                },
                                                "statusChangedAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "lastLoginAt": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The credentials were missing, wrong or revoked.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The credentials can't be used from this IP address, or the email isn't allowed by the email token's restrictions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "There is no such record.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "It can't be done to the account in the state it's in (see the code).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "object",
                                            "properties": {
                                                "message": {
                                                    "type": "string",
                                                    "description": "What went wrong, for a person to read."
                                                },
                                                "code": {
                                                    "type": "integer",
                                                    "description": "The application's code for the error (see the top)."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "description": "The account's ID.",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        }
    },
    "components": {
        "securitySchemes": {
            "apiKey": {
                "type": "http",
                "description": "An API key (starting \"ak_\"), created in the web interface under \"API keys\".",
                "scheme": "bearer"
            },
            "emailToken": {
                "type": "http",
                "description": "An email token (starting \"et_\"), created in the web interface under \"Email tokens\".",
                "scheme": "bearer"
            }
        }
    },
    "security": [
        {
            "apiKey": []
        }
    ],
    "tags": [
        {
            "name": "Email tokens",
            "description": "The email tokens that services send email with."
        },
        {
            "name": "Rate limits",
            "description": "The global rate limits, across every email token."
        },
        {
            "name": "Statistics",
            "description": "How much email is coming through, and what happened to it."
        },
        {
            "name": "Sending",
            "description": "Sending email with an email token."
        },
        {
            "name": "Providers",
            "description": "The providers email is sent through (in settings.yaml), and how they share it."
        },
        {
            "name": "Users",
            "description": "The accounts that can log in to the web interface."
        }
    ]
}