{
 "openapi": "3.0.3",
 "info": {
  "title": "Bramble Mail, Calendar & Contacts API",
  "version": "2026-11-13",
  "description": "Bramble Mail's web app API: mailboxes, folders, messages, sending, rules and live updates; Bramble Calendar (calendars, events, sharing, meetings, rooms, categories, `.ics` links and CalDAV); and Contacts (address books, the organisation directory and CardDAV).\n"
 },
 "servers": [
  {
   "url": "https://{org}.brambleit.cloud/mail",
   "variables": {
    "org": {
     "default": "your-org"
    }
   }
  },
  {
   "url": "https://{org}.brambleit.cloud/api",
   "variables": {
    "org": {
     "default": "your-org"
    }
   }
  }
 ],
 "components": {
  "securitySchemes": {
   "apiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key"
   },
   "session": {
    "type": "apiKey",
    "in": "cookie",
    "name": "sso_session"
   },
   "bearer": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT"
   }
  }
 },
 "tags": [
  {
   "name": "Mailboxes",
   "description": "Your mailboxes and addresses, and the Android app download."
  },
  {
   "name": "Messages",
   "description": "Listing and reading messages, attachments, flags, moving, deleting, and answering meeting invitations in mail."
  },
  {
   "name": "Sending",
   "description": "Sending new messages, replies and forwards with attachments."
  },
  {
   "name": "Folders & rules",
   "description": "Creating, renaming, moving and ordering folders, and mail rules (filters run on the server)."
  },
  {
   "name": "Live updates",
   "description": "Server-sent events when a mailbox changes, and keeping the connection alive."
  },
  {
   "name": "Calendar",
   "description": "Calendars and events (with recurrence, attendees and replies), sharing, free/busy for people and rooms, categories, preferences, import and export, and private `.ics` links.\n"
  },
  {
   "name": "Contacts",
   "description": "Personal address books and contacts, the organisation directory, and vCard import and export."
  },
  {
   "name": "Rooms (admin)",
   "description": "Meeting rooms and their bookings. Rooms accept bookings automatically when they're free. Needs Global Administrator."
  },
  {
   "name": "CalDAV & CardDAV",
   "description": "The standard protocols for phones and desktop apps (`/mail/dav/`, HTTP Basic with an app password) and the read-only `.ics` subscription links (`/mail/ics/<token>.ics`, the token is the key).\n"
  },
  {
   "name": "New-mail push (BRM-API)",
   "description": "The mail server tells BRM-API about new mail so it can send push notifications. Needs `X-Mail-Hook-Key`."
  }
 ],
 "paths": {
  "/api/app/version": {
   "get": {
    "tags": [
     "Mailboxes"
    ],
    "summary": "Latest Android app version",
    "operationId": "get-api-app-version",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "versionName": {
           "type": "string"
          },
          "versionCode": {},
          "bytes": {
           "type": "integer"
          },
          "sha256": {}
         }
        }
       }
      }
     },
     "404": {
      "description": "There is no Android app yet"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/app/bramble-mail.apk": {
   "get": {
    "tags": [
     "Mailboxes"
    ],
    "summary": "Download the Android app",
    "operationId": "get-api-app-bramble-mail-apk",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "File, page or redirect"
     },
     "404": {
      "description": "There is no Android app yet"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/dav/*": {
   "options": {
    "tags": [
     "CalDAV & CardDAV"
    ],
    "summary": "CalDAV/CardDAV capabilities",
    "operationId": "options-dav",
    "description": "Requires: None: public, or protected by a token in the address or body.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "File, page or redirect"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/ics/{file}": {
   "get": {
    "tags": [
     "CalDAV & CardDAV"
    ],
    "summary": "Read a calendar from its .ics link",
    "operationId": "get-ics-file",
    "description": "Requires: None: public, or protected by a token in the address or body.",
    "parameters": [
     {
      "name": "file",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "File, page or redirect"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/cal/bootstrap": {
   "get": {
    "tags": [
     "Calendar"
    ],
    "summary": "Everything the calendar page needs to start",
    "operationId": "get-api-cal-bootstrap",
    "description": "Everything the page needs to start.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "me": {
           "type": "object",
           "properties": {
            "name": {
             "type": "string"
            },
            "email": {
             "type": "string"
            },
            "addresses": {
             "type": "array",
             "items": {}
            }
           }
          },
          "calendars": {
           "type": "array",
           "items": {}
          },
          "shared": {
           "type": "array",
           "items": {}
          },
          "rooms": {
           "type": "array",
           "items": {}
          },
          "categories": {
           "type": "array",
           "items": {}
          },
          "prefs": {
           "type": "array",
           "items": {}
          },
          "timezone": {},
          "feeds": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "integer"
             },
             "on": {
              "type": "integer"
             },
             "color": {
              "type": "integer"
             }
            }
           }
          },
          "dav": {
           "type": "object",
           "properties": {
            "url": {
             "type": "string"
            },
            "username": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/cal/prefs": {
   "patch": {
    "tags": [
     "Calendar"
    ],
    "summary": "Save calendar preferences",
    "operationId": "patch-api-cal-prefs",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "view": {
          "type": "string",
          "enum": [
           "day",
           "week",
           "month",
           "agenda"
          ]
         },
         "weekStart": {
          "type": "number"
         },
         "dayStart": {
          "type": "number"
         },
         "timezone": {},
         "feeds": {
          "type": "object"
         },
         "feedColors": {
          "type": "object"
         },
         "hidden": {
          "type": "array",
          "items": {}
         },
         "rooms": {
          "type": "array",
          "items": {}
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/cal/calendars": {
   "post": {
    "tags": [
     "Calendar"
    ],
    "summary": "Create a calendar",
    "operationId": "post-api-cal-calendars",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "name": {
          "type": "string"
         },
         "color": {},
         "uri": {}
        }
       }
      }
     }
    }
   }
  },
  "/api/cal/calendars/{id}": {
   "patch": {
    "tags": [
     "Calendar"
    ],
    "summary": "Update a calendar",
    "operationId": "patch-api-cal-calendars-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "name": {
          "type": "string"
         },
         "color": {},
         "sort": {}
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Calendar"
    ],
    "summary": "Delete a calendar",
    "operationId": "delete-api-cal-calendars-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/cal/calendars/{id}/subscription": {
   "post": {
    "tags": [
     "Calendar"
    ],
    "summary": "Make a private .ics link",
    "operationId": "post-api-cal-calendars-id-subscription",
    "description": "The link is in the response once. Making a new one stops the old one working.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "url": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "delete": {
    "tags": [
     "Calendar"
    ],
    "summary": "Stop a calendar's .ics link",
    "operationId": "delete-api-cal-calendars-id-subscription",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/cal/calendars/{id}/shares": {
   "get": {
    "tags": [
     "Calendar"
    ],
    "summary": "Who a calendar is shared with",
    "operationId": "get-api-cal-calendars-id-shares",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "post": {
    "tags": [
     "Calendar"
    ],
    "summary": "Share a calendar",
    "operationId": "post-api-cal-calendars-id-shares",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "type": {
          "type": "string",
          "description": "`user` or `group`."
         },
         "id": {
          "type": "integer",
          "description": "The person's or group's id."
         },
         "level": {
          "description": "`freebusy`, `read` or `write`."
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/cal/calendars/{id}/shares/{share}": {
   "delete": {
    "tags": [
     "Calendar"
    ],
    "summary": "Stop sharing a calendar with someone",
    "operationId": "delete-api-cal-calendars-id-shares-share",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "share",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/cal/people": {
   "get": {
    "tags": [
     "Calendar"
    ],
    "summary": "People (and groups) in your organisation, plus your own contacts",
    "operationId": "get-api-cal-people",
    "description": "People (and groups) in your organisation, plus your own contacts. ?q=&groups=1&contacts=1\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": false,
      "schema": {}
     },
     {
      "name": "groups",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "contacts",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "rooms",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "array",
         "items": {}
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/cal/rooms": {
   "get": {
    "tags": [
     "Calendar"
    ],
    "summary": "List meeting rooms",
    "operationId": "get-api-cal-rooms",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "array",
         "items": {}
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/cal/freebusy": {
   "post": {
    "tags": [
     "Calendar"
    ],
    "summary": "Busy times for people in your organisation and rooms",
    "operationId": "post-api-cal-freebusy",
    "description": "Busy times for people in your organisation and rooms. body: { addresses: [], from: ISO, to: ISO }\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "from": {},
         "to": {},
         "addresses": {
          "type": "array",
          "items": {}
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/cal/calendars/{id}/import": {
   "post": {
    "tags": [
     "Calendar"
    ],
    "summary": "Import an .ics file into a calendar (each event becomes its own entry)",
    "operationId": "post-api-cal-calendars-id-import",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "added": {},
          "updated": {},
          "failed": {}
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/cal/calendars/{id}/export.ics": {
   "get": {
    "tags": [
     "Calendar"
    ],
    "summary": "Export a calendar as .ics",
    "operationId": "get-api-cal-calendars-id-export-ics",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "File, page or redirect"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/cal/events": {
   "get": {
    "tags": [
     "Calendar"
    ],
    "summary": "Events in a time range",
    "operationId": "get-api-cal-events",
    "description": "?from=ISO&to=ISO\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "from",
      "in": "query",
      "required": true,
      "schema": {},
      "description": "Start (ISO date-time)."
     },
     {
      "name": "to",
      "in": "query",
      "required": true,
      "schema": {},
      "description": "End (ISO date-time)."
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "events": {
           "type": "array",
           "items": {}
          },
          "feeds": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/cal/calendars/{id}/events": {
   "post": {
    "tags": [
     "Calendar"
    ],
    "summary": "Create an event",
    "operationId": "post-api-cal-calendars-id-events",
    "description": "With `attendees`, it's a meeting: colleagues get it on their calendar and an email, outside guests get an invitation email, and replies update the event.\n\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "uri": {},
          "etag": {}
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "attendees": {
          "type": "array",
          "items": {}
         },
         "tz": {}
        }
       }
      }
     }
    }
   }
  },
  "/api/cal/calendars/{id}/events/{uri}": {
   "patch": {
    "tags": [
     "Calendar"
    ],
    "summary": "Change an event",
    "operationId": "patch-api-cal-calendars-id-events-uri",
    "description": "Body: { ...fields, scope: 'all'|'this', recurrenceId, etag, moveTo, rsvp }\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "uri",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "calendar": {
           "type": "integer"
          },
          "uri": {},
          "etag": {}
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "etag": {
          "description": "The version you started from (refused if it changed)."
         },
         "attendees": {
          "type": "array",
          "items": {}
         },
         "rsvp": {
          "description": "Your answer, when you're an attendee."
         },
         "scope": {
          "type": "string",
          "description": "For a repeating event: `all` or `this` (one occurrence, with `recurrenceId`)."
         },
         "recurrenceId": {},
         "tz": {},
         "moveTo": {
          "type": "number",
          "description": "Move it to another calendar."
         }
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Calendar"
    ],
    "summary": "Delete an event",
    "operationId": "delete-api-cal-calendars-id-events-uri",
    "description": "?scope=this&recurrenceId=ms deletes one occurrence.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "uri",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "scope",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "`this` with `recurrenceId` deletes one occurrence."
     },
     {
      "name": "recurrenceId",
      "in": "query",
      "required": false,
      "schema": {}
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/cal/categories": {
   "get": {
    "tags": [
     "Calendar"
    ],
    "summary": "List categories",
    "operationId": "get-api-cal-categories",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "post": {
    "tags": [
     "Calendar"
    ],
    "summary": "Create a category",
    "operationId": "post-api-cal-categories",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "id": {
          "type": "integer"
         },
         "name": {
          "type": "string"
         },
         "color": {}
        }
       }
      }
     }
    }
   }
  },
  "/api/cal/categories/{id}": {
   "patch": {
    "tags": [
     "Calendar"
    ],
    "summary": "Update a category",
    "operationId": "patch-api-cal-categories-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "delete": {
    "tags": [
     "Calendar"
    ],
    "summary": "Delete a category",
    "operationId": "delete-api-cal-categories-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/contacts/bootstrap": {
   "get": {
    "tags": [
     "Contacts"
    ],
    "summary": "Everything the contacts page needs to start",
    "operationId": "get-api-contacts-bootstrap",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "me": {
           "type": "object",
           "properties": {
            "name": {
             "type": "string"
            },
            "email": {
             "type": "string"
            }
           }
          },
          "books": {
           "type": "array",
           "items": {}
          },
          "dav": {
           "type": "object",
           "properties": {
            "url": {
             "type": "string"
            },
            "username": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/contacts/directory": {
   "get": {
    "tags": [
     "Contacts"
    ],
    "summary": "The organisation directory",
    "operationId": "get-api-contacts-directory",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "array",
         "items": {
          "type": "object",
          "properties": {
           "id": {
            "type": "integer"
           },
           "name": {
            "type": "string"
           },
           "given": {
            "type": "string"
           },
           "family": {
            "type": "string"
           },
           "email": {
            "type": "string"
           },
           "title": {
            "type": "string"
           },
           "department": {
            "type": "string"
           },
           "location": {
            "type": "string"
           }
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/contacts/books": {
   "post": {
    "tags": [
     "Contacts"
    ],
    "summary": "Create a book",
    "operationId": "post-api-contacts-books",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "name": {
          "type": "string"
         },
         "uri": {}
        }
       }
      }
     }
    }
   }
  },
  "/api/contacts/books/{id}": {
   "patch": {
    "tags": [
     "Contacts"
    ],
    "summary": "Rename an address book",
    "operationId": "patch-api-contacts-books-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "delete": {
    "tags": [
     "Contacts"
    ],
    "summary": "Delete an address book",
    "operationId": "delete-api-contacts-books-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/contacts/books/{id}/contacts": {
   "get": {
    "tags": [
     "Contacts"
    ],
    "summary": "List contacts of a book",
    "operationId": "get-api-contacts-books-id-contacts",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "array",
         "items": {}
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "post": {
    "tags": [
     "Contacts"
    ],
    "summary": "Add a contact",
    "operationId": "post-api-contacts-books-id-contacts",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "uri": {},
          "etag": {}
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/contacts/books/{id}/contacts/{uri}": {
   "patch": {
    "tags": [
     "Contacts"
    ],
    "summary": "Update a contact",
    "operationId": "patch-api-contacts-books-id-contacts-uri",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "uri",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "book": {
           "type": "integer"
          },
          "uri": {},
          "etag": {}
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "etag": {},
         "moveTo": {
          "type": "number"
         }
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Contacts"
    ],
    "summary": "Delete a contact",
    "operationId": "delete-api-contacts-books-id-contacts-uri",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "uri",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/contacts/books/{id}/import": {
   "post": {
    "tags": [
     "Contacts"
    ],
    "summary": "Import a .vcf file (one or many cards)",
    "operationId": "post-api-contacts-books-id-import",
    "description": "Import a .vcf file (one or many cards). Cards with a UID already in the book replace it.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "added": {},
          "updated": {},
          "failed": {}
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/contacts/books/{id}/export.vcf": {
   "get": {
    "tags": [
     "Contacts"
    ],
    "summary": "Export an address book (.vcf)",
    "operationId": "get-api-contacts-books-id-export-vcf",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "File, page or redirect"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/admin/rooms": {
   "get": {
    "tags": [
     "Rooms (admin)"
    ],
    "summary": "List rooms",
    "operationId": "get-api-admin-rooms",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Admins only (Global Administrator or the app's admin role).",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "rooms": {
           "type": "array",
           "items": {}
          },
          "domains": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "post": {
    "tags": [
     "Rooms (admin)"
    ],
    "summary": "Create a room",
    "operationId": "post-api-admin-rooms",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Admins only (Global Administrator or the app's admin role).",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "rooms": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "name": {
          "type": "string",
          "description": "The room's name."
         },
         "email": {
          "type": "string",
          "description": "Its address (invitations go here)."
         },
         "capacity": {
          "type": "string",
          "description": "How many people it seats."
         },
         "location": {
          "description": "Where it is."
         },
         "notes": {
          "type": "array",
          "items": {}
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/admin/rooms/{id}": {
   "patch": {
    "tags": [
     "Rooms (admin)"
    ],
    "summary": "Update a room",
    "operationId": "patch-api-admin-rooms-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Admins only (Global Administrator or the app's admin role).",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "rooms": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Room not found"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "delete": {
    "tags": [
     "Rooms (admin)"
    ],
    "summary": "Deleting a room drops its bookings; meetings keep it on their list",
    "operationId": "delete-api-admin-rooms-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Admins only (Global Administrator or the app's admin role).",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "rooms": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Room not found"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/admin/rooms/{id}/bookings": {
   "get": {
    "tags": [
     "Rooms (admin)"
    ],
    "summary": "A room's bookings (next 60 days) for the admin page",
    "operationId": "get-api-admin-rooms-id-bookings",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Admins only (Global Administrator or the app's admin role).",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "array",
         "items": {
          "type": "object",
          "properties": {
           "title": {
            "type": "string"
           },
           "start": {},
           "end": {},
           "allDay": {},
           "organizer": {}
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Room not found"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/me": {
   "get": {
    "tags": [
     "Mailboxes"
    ],
    "summary": "Your mailboxes and addresses",
    "operationId": "get-api-me",
    "description": "Who you are, the mailboxes you can open, the addresses you can send from.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "user": {},
          "mailboxes": {
           "type": "array",
           "items": {}
          },
          "identities": {
           "type": "array",
           "items": {}
          },
          "features": {
           "type": "array",
           "items": {
            "type": "string"
           }
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/folders": {
   "get": {
    "tags": [
     "Folders & rules"
    ],
    "summary": "List a mailbox's folders",
    "operationId": "get-api-folders",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "mb",
      "in": "query",
      "required": false,
      "schema": {},
      "description": "The mailbox."
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "folders": {
           "type": "array",
           "items": {}
          },
          "order": {},
          "canManage": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "post": {
    "tags": [
     "Folders & rules"
    ],
    "summary": "Create a folder",
    "operationId": "post-api-folders",
    "description": "A new folder (parent '' = top level).\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "path": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "The mail server didn't create it: …"
     },
     "404": {
      "description": "That folder has gone"
     },
     "409": {
      "description": "There is already a folder with that name there"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "mb": {
          "description": "The mailbox."
         },
         "parent": {
          "description": "The parent folder's path (`''` for the top level)."
         },
         "name": {
          "type": "string",
          "description": "The new folder's name."
         }
        }
       }
      }
     }
    }
   },
   "patch": {
    "tags": [
     "Folders & rules"
    ],
    "summary": "Rename or move a folder",
    "operationId": "patch-api-folders",
    "description": "Rename and/or move.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "path": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Inbox, Drafts, Sent, Junk and Trash can't be renamed or moved"
     },
     "404": {
      "description": "That folder has gone"
     },
     "409": {
      "description": "There is already a folder with that name there"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "mb": {},
         "path": {
          "type": "string"
         },
         "parent": {},
         "name": {
          "type": "string"
         }
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Folders & rules"
    ],
    "summary": "Delete a folder",
    "operationId": "delete-api-folders",
    "description": "Its messages go to Trash first.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "movedToTrash": {}
         }
        }
       }
      }
     },
     "400": {
      "description": "Inbox, Drafts, Sent, Junk and Trash can't be deleted"
     },
     "404": {
      "description": "That folder has gone"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/folders/order": {
   "put": {
    "tags": [
     "Folders & rules"
    ],
    "summary": "Save the folder order",
    "operationId": "put-api-folders-order",
    "description": "How you arranged them.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "mb": {},
         "order": {
          "type": "array",
          "items": {}
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/rules": {
   "get": {
    "tags": [
     "Folders & rules"
    ],
    "summary": "List mail rules",
    "operationId": "get-api-rules",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "mb",
      "in": "query",
      "required": false,
      "schema": {}
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     },
     "422": {
      "description": "These rules were written in a way Bramble can't read. Ask Bramble IT to look at them."
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "put": {
    "tags": [
     "Folders & rules"
    ],
    "summary": "Save mail rules",
    "operationId": "put-api-rules",
    "description": "Replaces the whole list, in order.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Send the list of rules"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "mb": {},
         "rules": {
          "type": "array",
          "items": {}
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/messages": {
   "get": {
    "tags": [
     "Messages"
    ],
    "summary": "List messages in a folder",
    "operationId": "get-api-messages",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "mb",
      "in": "query",
      "required": false,
      "schema": {},
      "description": "The mailbox."
     },
     {
      "name": "folder",
      "in": "query",
      "required": false,
      "schema": {},
      "description": "The folder's path, e.g. `INBOX`."
     },
     {
      "name": "page",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "Page number."
     },
     {
      "name": "q",
      "in": "query",
      "required": false,
      "schema": {},
      "description": "Text to search for."
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "page": {
           "type": "integer"
          },
          "pageSize": {
           "type": "integer"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/message": {
   "get": {
    "tags": [
     "Messages"
    ],
    "summary": "Read a message",
    "operationId": "get-api-message",
    "description": "The message with its HTML cleaned for safe display. Remote images are blocked unless `remote=1`.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "mb",
      "in": "query",
      "required": false,
      "schema": {},
      "description": "The mailbox."
     },
     {
      "name": "folder",
      "in": "query",
      "required": false,
      "schema": {},
      "description": "The folder."
     },
     {
      "name": "uid",
      "in": "query",
      "required": false,
      "schema": {},
      "description": "The message's uid."
     },
     {
      "name": "remote",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "`1` to load remote images."
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "uid": {},
          "subject": {
           "type": "string"
          },
          "from": {},
          "to": {},
          "cc": {},
          "replyTo": {},
          "date": {
           "type": "string",
           "format": "date"
          },
          "messageId": {},
          "references": {
           "type": "array",
           "nullable": true,
           "items": {}
          },
          "html": {},
          "text": {
           "type": "string"
          },
          "blockedImages": {
           "type": "array",
           "items": {}
          },
          "flagged": {
           "type": "boolean"
          },
          "attachments": {
           "type": "array",
           "items": {}
          },
          "invite": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/invite": {
   "get": {
    "tags": [
     "Messages"
    ],
    "summary": "A meeting invitation in a message",
    "operationId": "get-api-invite",
    "description": "→ what the invitation is and where you stand.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "mb",
      "in": "query",
      "required": false,
      "schema": {}
     },
     {
      "name": "folder",
      "in": "query",
      "required": false,
      "schema": {}
     },
     {
      "name": "uid",
      "in": "query",
      "required": false,
      "schema": {}
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     },
     "400": {
      "description": "This invitation couldn't be read"
     },
     "404": {
      "description": "There's no invitation in this message"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "post": {
    "tags": [
     "Messages"
    ],
    "summary": "Answer a meeting invitation",
    "operationId": "post-api-invite",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     },
     "404": {
      "description": "There's no invitation in this message"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "mb": {},
         "folder": {},
         "uid": {},
         "action": {
          "description": "`accept`, `tentative` or `decline`."
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/attachment": {
   "get": {
    "tags": [
     "Messages"
    ],
    "summary": "Download an attachment",
    "operationId": "get-api-attachment",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "mb",
      "in": "query",
      "required": false,
      "schema": {}
     },
     {
      "name": "folder",
      "in": "query",
      "required": false,
      "schema": {}
     },
     {
      "name": "uid",
      "in": "query",
      "required": false,
      "schema": {}
     },
     {
      "name": "index",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "The attachment's position in the message."
     }
    ],
    "responses": {
     "200": {
      "description": "File, page or redirect"
     },
     "404": {
      "description": "That attachment has gone"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/flags": {
   "post": {
    "tags": [
     "Messages"
    ],
    "summary": "Mark messages read, unread or flagged",
    "operationId": "post-api-flags",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "mb": {},
         "folder": {},
         "uids": {
          "type": "array",
          "items": {},
          "description": "The messages."
         },
         "key": {
          "type": "string"
         },
         "seen": {
          "description": "`true` read, `false` unread."
         },
         "flagged": {
          "description": "`true` to flag, `false` to unflag."
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/move": {
   "post": {
    "tags": [
     "Messages"
    ],
    "summary": "Move messages",
    "operationId": "post-api-move",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "mb": {},
         "folder": {},
         "to": {
          "description": "The folder to move them to."
         },
         "uids": {
          "type": "array",
          "items": {},
          "description": "The messages."
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/delete": {
   "post": {
    "tags": [
     "Messages"
    ],
    "summary": "Delete messages",
    "operationId": "post-api-delete",
    "description": "To Trash, or for good if they're already in Trash.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "permanently": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "mb": {},
         "folder": {},
         "uids": {
          "type": "array",
          "items": {}
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/send": {
   "post": {
    "tags": [
     "Sending"
    ],
    "summary": "Send a message",
    "operationId": "post-api-send",
    "description": "`multipart/form-data`: the fields below plus any attachments as files.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "savedTo": {}
         }
        }
       }
      }
     },
     "400": {
      "description": "Add someone to send it to"
     },
     "403": {
      "description": "You can't send from that address"
     },
     "502": {
      "description": "The mail server didn't accept it: …"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "properties": {
         "from": {
          "description": "The address to send from (yours, or a shared mailbox's you may send as)."
         },
         "to": {
          "description": "Recipients."
         },
         "cc": {
          "description": "Copy recipients."
         },
         "bcc": {
          "description": "Blind copy recipients."
         },
         "html": {
          "description": "The message body (HTML)."
         },
         "subject": {
          "description": "The subject."
         },
         "inReplyTo": {
          "description": "The message being replied to (for threading)."
         },
         "references": {
          "type": "array",
          "items": {}
         },
         "answeredUid": {
          "type": "number"
         },
         "answeredFolder": {},
         "answeredMb": {}
        }
       }
      }
     }
    }
   }
  },
  "/api/events": {
   "get": {
    "tags": [
     "Live updates"
    ],
    "summary": "Live mailbox changes (server-sent events)",
    "operationId": "get-api-events",
    "description": "Server-Sent Events: \"changed\" when the INBOX changes (IMAP IDLE on a connection of its own), so new mail shows without polling.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "mb",
      "in": "query",
      "required": false,
      "schema": {}
     }
    ],
    "responses": {
     "200": {
      "description": "File, page or redirect"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/push": {
   "get": {
    "tags": [
     "Live updates"
    ],
    "summary": "Keep the live connection alive",
    "operationId": "get-api-push",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: Mail.",
    "parameters": [
     {
      "name": "mb",
      "in": "query",
      "required": false,
      "schema": {}
     },
     {
      "name": "ping",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "File, page or redirect"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/v1/maildelivery/new": {
   "post": {
    "tags": [
     "New-mail push (BRM-API)"
    ],
    "summary": "Tell Bramble about new mail (mail server only)",
    "operationId": "post-v1-maildelivery-new",
    "description": "Requires: None: public, or protected by a token in the address or body.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "sent": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "user is required"
     },
     "401": {
      "description": "Unauthorized"
     },
     "500": {
      "description": "Internal Server Error"
     }
    },
    "security": [
     {
      "apiKey": []
     },
     {
      "session": []
     },
     {
      "bearer": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "user": {},
         "messages": {
          "type": "array",
          "items": {}
         }
        }
       }
      }
     }
    }
   }
  }
 }
}