ReferenceMail, Calendar & Contacts API

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

#Everything the calendar page needs to start

GET/api/cal/bootstrap

Everything the page needs to start.

Address: https://<your-org>.brambleit.cloud/mail/api/cal/bootstrap
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Response 200

Field	Type	Description
`me`	object
`me.name`	string
`me.email`	string
`me.addresses`	array of any
`calendars`	array of any
`shared`	array of any
`rooms`	array of any
`categories`	array of any
`prefs`	array of any
`timezone`	any
`feeds`	array of object
`feeds[].id`	integer
`feeds[].on`	integer
`feeds[].color`	integer
`dav`	object
`dav.url`	string
`dav.username`	string

Example response

JSON

{
  "me": {
    "name": "Example name",
    "email": "alex@example.com",
    "addresses": []
  },
  "calendars": [],
  "shared": [],
  "rooms": [],
  "categories": [],
  "prefs": [],
  "timezone": null,
  "feeds": [
    {
      "id": 42,
      "…f": "…",
      "on": 1,
      "color": 1
    }
  ],
  "dav": {
    "url": "https://example.com/…",
    "username": "Example username"
  }
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/bootstrap', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Save calendar preferences

PATCH/api/cal/prefs

Address: https://<your-org>.brambleit.cloud/mail/api/cal/prefs
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Request body JSON

Name	Type	Description
`view`	string: "day" \| "week" \| "month" \| "agenda"
`weekStart`	number
`dayStart`	number
`timezone`	any
`feeds`	object
`feedColors`	object
`hidden`	array of any
`rooms`	array of any

Response 200

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/prefs', {
  method: 'PATCH',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"view":"day","weekStart":12.5,"dayStart":12.5,"timezone":"…","feeds":{},"feedColors":{},"hidden":[],"rooms":[]}),
});
const data = await res.json();

#Create a calendar

POST/api/cal/calendars

Address: https://<your-org>.brambleit.cloud/mail/api/cal/calendars
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Request body JSON

Name	Type	Description
`name`	string
`color`	any
`uri`	any

Response 200

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/calendars', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"name":"Example name","color":"…","uri":"…"}),
});
const data = await res.json();

#Update a calendar

PATCH/api/cal/calendars/:id

Address: https://<your-org>.brambleit.cloud/mail/api/cal/calendars/:id
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Path parameters

Name	Type	Description
`id`required	integer

Request body JSON

Name	Type	Description
`name`	string
`color`	any
`sort`	any

Response 200

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/calendars/42', {
  method: 'PATCH',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"name":"Example name","color":"…","sort":"…"}),
});
const data = await res.json();

#Delete a calendar

DELETE/api/cal/calendars/:id

Address: https://<your-org>.brambleit.cloud/mail/api/cal/calendars/:id
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Path parameters

Name	Type	Description
`id`required	integer

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/calendars/42', {
  method: 'DELETE',
  credentials: 'include',
});
const data = await res.json();

#Make a private .ics link

POST/api/cal/calendars/:id/subscription

The link is in the response once. Making a new one stops the old one working.

Address: https://<your-org>.brambleit.cloud/mail/api/cal/calendars/:id/subscription
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Path parameters

Name	Type	Description
`id`required	integer

Response 200

Field	Type	Description
`url`	string

Example response

JSON

{
  "url": "https://example.com/…"
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/calendars/42/subscription', {
  method: 'POST',
  credentials: 'include',
});
const data = await res.json();

#Stop a calendar's .ics link

DELETE/api/cal/calendars/:id/subscription

Address: https://<your-org>.brambleit.cloud/mail/api/cal/calendars/:id/subscription
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Path parameters

Name	Type	Description
`id`required	integer

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/calendars/42/subscription', {
  method: 'DELETE',
  credentials: 'include',
});
const data = await res.json();

#Who a calendar is shared with

GET/api/cal/calendars/:id/shares

Address: https://<your-org>.brambleit.cloud/mail/api/cal/calendars/:id/shares
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Path parameters

Name	Type	Description
`id`required	integer

Response 200

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/calendars/42/shares', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Share a calendar

POST/api/cal/calendars/:id/shares

Address: https://<your-org>.brambleit.cloud/mail/api/cal/calendars/:id/shares
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Path parameters

Name	Type	Description
`id`required	integer

Request body JSON

Name	Type	Description
`type`	string	`user` or `group`.
`id`	integer	The person's or group's id.
`level`	any	`freebusy`, `read` or `write`.

Response 200

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/calendars/42/shares', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"type":"string","id":42,"level":"…"}),
});
const data = await res.json();

#Stop sharing a calendar with someone

DELETE/api/cal/calendars/:id/shares/:share

Address: https://<your-org>.brambleit.cloud/mail/api/cal/calendars/:id/shares/:share
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Path parameters

Name	Type	Description
`id`required	integer
`share`required	number

Response 200

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/calendars/42/shares/12.5', {
  method: 'DELETE',
  credentials: 'include',
});
const data = await res.json();

#People (and groups) in your organisation, plus your own contacts

GET/api/cal/people

People (and groups) in your organisation, plus your own contacts. ?q=&groups=1&contacts=1

Address: https://<your-org>.brambleit.cloud/mail/api/cal/people
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Query parameters

Name	Type	Description
`q`	any
`groups`	string
`contacts`	string
`rooms`	string

Response 200

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/people', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#List meeting rooms

GET/api/cal/rooms

Address: https://<your-org>.brambleit.cloud/mail/api/cal/rooms
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Response 200

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/rooms', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Busy times for people in your organisation and rooms

POST/api/cal/freebusy

Busy times for people in your organisation and rooms. body: { addresses: [], from: ISO, to: ISO }

Address: https://<your-org>.brambleit.cloud/mail/api/cal/freebusy
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Request body JSON

Name	Type	Description
`from`	any
`to`	any
`addresses`	array of any

Response 200

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/freebusy', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"from":"…","to":"…","addresses":[]}),
});
const data = await res.json();

#Import an .ics file into a calendar (each event becomes its own entry)

POST/api/cal/calendars/:id/import

Address: https://<your-org>.brambleit.cloud/mail/api/cal/calendars/:id/import
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Path parameters

Name	Type	Description
`id`required	integer

Response 200

Field	Type	Description
`added`	any
`updated`	any
`failed`	any

Example response

JSON

{
  "added": null,
  "updated": null,
  "failed": null
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/calendars/42/import', {
  method: 'POST',
  credentials: 'include',
});
const data = await res.json();

#Export a calendar as .ics

GET/api/cal/calendars/:id/export.ics

Address: https://<your-org>.brambleit.cloud/mail/api/cal/calendars/:id/export.ics
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Path parameters

Name	Type	Description
`id`required	integer

Response

A body.

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/calendars/42/export.ics', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Events in a time range

GET/api/cal/events

?from=ISO&to=ISO

Address: https://<your-org>.brambleit.cloud/mail/api/cal/events
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Query parameters

Name	Type	Description
`from`required	any	Start (ISO date-time).
`to`required	any	End (ISO date-time).

Response 200

Field	Type	Description
`events`	array of any
`feeds`	array of any

Example response

JSON

{
  "events": [],
  "feeds": []
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/events?from=%E2%80%A6&to=%E2%80%A6', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Create an event

POST/api/cal/calendars/:id/events

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.

Address: https://<your-org>.brambleit.cloud/mail/api/cal/calendars/:id/events
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Path parameters

Name	Type	Description
`id`required	integer

Request body JSON

Name	Type	Description
`attendees`	array of any
`tz`	any

Response 200

Field	Type	Description
`uri`	any
`etag`	any

Example response

JSON

{
  "uri": null,
  "etag": null,
  "…report(sched)": "…"
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/calendars/42/events', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"attendees":[],"tz":"…"}),
});
const data = await res.json();

#Change an event

PATCH/api/cal/calendars/:id/events/:uri

Body: { ...fields, scope: 'all'|'this', recurrenceId, etag, moveTo, rsvp }

Address: https://<your-org>.brambleit.cloud/mail/api/cal/calendars/:id/events/:uri
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Path parameters

Name	Type	Description
`id`required	integer
`uri`required	string

Request body JSON

Name	Type	Description
`etag`	any	The version you started from (refused if it changed).
`attendees`	array of any
`rsvp`	any	Your answer, when you're an attendee.
`scope`	string	For a repeating event: `all` or `this` (one occurrence, with `recurrenceId`).
`recurrenceId`	any
`tz`	any
`moveTo`	number	Move it to another calendar.

Response 200

Field	Type	Description
`calendar`	integer
`uri`	any
`etag`	any

Example response

JSON

{
  "calendar": 1,
  "uri": null,
  "etag": null
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/calendars/42/events/string', {
  method: 'PATCH',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"etag":"…","attendees":[],"rsvp":"…","scope":"string","recurrenceId":"…","tz":"…","moveTo":12.5}),
});
const data = await res.json();

#Delete an event

DELETE/api/cal/calendars/:id/events/:uri

?scope=this&recurrenceId=ms deletes one occurrence.

Address: https://<your-org>.brambleit.cloud/mail/api/cal/calendars/:id/events/:uri
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Path parameters

Name	Type	Description
`id`required	integer
`uri`required	string

Query parameters

Name	Type	Description
`scope`	string	`this` with `recurrenceId` deletes one occurrence.
`recurrenceId`	any

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true,
  "…report(sched)": "…"
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/calendars/42/events/string', {
  method: 'DELETE',
  credentials: 'include',
});
const data = await res.json();

#List categories

GET/api/cal/categories

Address: https://<your-org>.brambleit.cloud/mail/api/cal/categories
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Response 200

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/categories', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Create a category

POST/api/cal/categories

Address: https://<your-org>.brambleit.cloud/mail/api/cal/categories
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Request body JSON

Name	Type	Description
`id`	integer
`name`	string
`color`	any

Response 200

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/categories', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"id":42,"name":"Example name","color":"…"}),
});
const data = await res.json();

#Update a category

PATCH/api/cal/categories/:id

Address: https://<your-org>.brambleit.cloud/mail/api/cal/categories/:id
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Path parameters

Name	Type	Description
`id`required	number

Response 200

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/categories/12.5', {
  method: 'PATCH',
  credentials: 'include',
});
const data = await res.json();

#Delete a category

DELETE/api/cal/categories/:id

Address: https://<your-org>.brambleit.cloud/mail/api/cal/categories/:id
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Mail.

Path parameters

Name	Type	Description
`id`required	number

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/mail/api/cal/categories/12.5', {
  method: 'DELETE',
  credentials: 'include',
});
const data = await res.json();

Was this page helpful?