Mail, Calendar & Contacts API
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).
- Address
https://<your-org>.brambleit.cloud/mail- Sign-in
- Signed-in browser session (the
sso_session/session_idcookies from Bramble sign-in). - Address
https://<your-org>.brambleit.cloud/api- Sign-in
- Signed-in session,
X-API-Key, or a Bramble app access token (Authorization: Bearer). - Endpoints
- 66
- OpenAPI
- mail.json
- Guides
- How Mail & Calendar works
Mailboxes. Most mail endpoints take mb, the mailbox to work in (your
own, or a shared mailbox you have access to — see GET /api/me), and
folder, the folder's path (e.g. INBOX, Sent). Messages are identified
by their IMAP uid within that folder.
From your own systems, use the standard protocols rather than these
endpoints: IMAP and SMTP for mail, CalDAV at /mail/dav/ for calendars and
CardDAV at /mail/dav/addressbooks/ for contacts, with your email address and
an app password.
Calendar sharing levels: freebusy (only when you're busy), read and
write.
Resources
Mailboxes
Your mailboxes and addresses, and the Android app download.
| Method | Path | Summary |
|---|---|---|
| GET | /api/app/version | Latest Android app version |
| GET | /api/app/bramble-mail.apk | Download the Android app |
| GET | /api/me | Your mailboxes and addresses |
Messages
Listing and reading messages, attachments, flags, moving, deleting, and answering meeting invitations in mail.
| Method | Path | Summary |
|---|---|---|
| GET | /api/messages | List messages in a folder |
| GET | /api/message | Read a message |
| GET | /api/invite | A meeting invitation in a message |
| POST | /api/invite | Answer a meeting invitation |
| GET | /api/attachment | Download an attachment |
| POST | /api/flags | Mark messages read, unread or flagged |
| POST | /api/move | Move messages |
| POST | /api/delete | Delete messages |
Sending
Sending new messages, replies and forwards with attachments.
| Method | Path | Summary |
|---|---|---|
| POST | /api/send | Send a message |
Folders & rules
Creating, renaming, moving and ordering folders, and mail rules (filters run on the server).
| Method | Path | Summary |
|---|---|---|
| GET | /api/folders | List a mailbox's folders |
| POST | /api/folders | Create a folder |
| PATCH | /api/folders | Rename or move a folder |
| DELETE | /api/folders | Delete a folder |
| PUT | /api/folders/order | Save the folder order |
| GET | /api/rules | List mail rules |
| PUT | /api/rules | Save mail rules |
Live updates
Server-sent events when a mailbox changes, and keeping the connection alive.
| Method | Path | Summary |
|---|---|---|
| GET | /api/events | Live mailbox changes (server-sent events) |
| GET | /api/push | Keep the live connection alive |
Calendar
Calendars and events (with recurrence, attendees and replies), sharing, free/busy for people and rooms, categories, preferences, import and export, and private .ics links.
| Method | Path | Summary |
|---|---|---|
| GET | /api/cal/bootstrap | Everything the calendar page needs to start |
| PATCH | /api/cal/prefs | Save calendar preferences |
| POST | /api/cal/calendars | Create a calendar |
| PATCH | /api/cal/calendars/:id | Update a calendar |
| DELETE | /api/cal/calendars/:id | Delete a calendar |
| POST | /api/cal/calendars/:id/subscription | Make a private .ics link |
| DELETE | /api/cal/calendars/:id/subscription | Stop a calendar's .ics link |
| GET | /api/cal/calendars/:id/shares | Who a calendar is shared with |
| POST | /api/cal/calendars/:id/shares | Share a calendar |
| DELETE | /api/cal/calendars/:id/shares/:share | Stop sharing a calendar with someone |
| GET | /api/cal/people | People (and groups) in your organisation, plus your own contacts |
| GET | /api/cal/rooms | List meeting rooms |
| POST | /api/cal/freebusy | Busy times for people in your organisation and rooms |
| POST | /api/cal/calendars/:id/import | Import an .ics file into a calendar (each event becomes its own entry) |
| GET | /api/cal/calendars/:id/export.ics | Export a calendar as .ics |
| GET | /api/cal/events | Events in a time range |
| POST | /api/cal/calendars/:id/events | Create an event |
| PATCH | /api/cal/calendars/:id/events/:uri | Change an event |
| DELETE | /api/cal/calendars/:id/events/:uri | Delete an event |
| GET | /api/cal/categories | List categories |
| POST | /api/cal/categories | Create a category |
| PATCH | /api/cal/categories/:id | Update a category |
| DELETE | /api/cal/categories/:id | Delete a category |
Contacts
Personal address books and contacts, the organisation directory, and vCard import and export.
| Method | Path | Summary |
|---|---|---|
| GET | /api/contacts/bootstrap | Everything the contacts page needs to start |
| GET | /api/contacts/directory | The organisation directory |
| POST | /api/contacts/books | Create a book |
| PATCH | /api/contacts/books/:id | Rename an address book |
| DELETE | /api/contacts/books/:id | Delete an address book |
| GET | /api/contacts/books/:id/contacts | List contacts of a book |
| POST | /api/contacts/books/:id/contacts | Add a contact |
| PATCH | /api/contacts/books/:id/contacts/:uri | Update a contact |
| DELETE | /api/contacts/books/:id/contacts/:uri | Delete a contact |
| POST | /api/contacts/books/:id/import | Import a .vcf file (one or many cards) |
| GET | /api/contacts/books/:id/export.vcf | Export an address book (.vcf) |
Rooms (admin)
Meeting rooms and their bookings. Rooms accept bookings automatically when they're free. Needs Global Administrator.
| Method | Path | Summary |
|---|---|---|
| GET | /api/admin/rooms | List rooms |
| POST | /api/admin/rooms | Create a room |
| PATCH | /api/admin/rooms/:id | Update a room |
| DELETE | /api/admin/rooms/:id | Deleting a room drops its bookings; meetings keep it on their list |
| GET | /api/admin/rooms/:id/bookings | A room's bookings (next 60 days) for the admin page |
CalDAV & CardDAV
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).
| Method | Path | Summary |
|---|---|---|
/dav/* | CalDAV/CardDAV capabilities | |
| ALL | /dav/* | CalDAV and CardDAV |
| GET | /ics/:file | Read a calendar from its .ics link |
| ALL | /.well-known/caldav | CalDAV discovery |
| ALL | /.well-known/carddav | CardDAV discovery |
New-mail push (BRM-API)
The mail server tells BRM-API about new mail so it can send push notifications. Needs X-Mail-Hook-Key.
| Method | Path | Summary |
|---|---|---|
| POST | /v1/maildelivery/new | Tell Bramble about new mail (mail server only) |
Web pages
These return pages for the browser rather than data.
GET /calendarGET /contactsGET /GET /sw.js