ReferenceMail, Calendar & Contacts API

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

#List a mailbox's folders

GET/api/folders

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

Query parameters

Name	Type	Description
`mb`	any	The mailbox.

Response 200

Field	Type	Description
`folders`	array of any
`order`	any
`canManage`	boolean

Example response

JSON

{
  "folders": [],
  "order": null,
  "canManage": false
}

Example request

JavaScript

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

#Create a folder

POST/api/folders

A new folder (parent '' = top level).

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

Request body JSON

Name	Type	Description
`mb`	any	The mailbox.
`parent`	any	The parent folder's path (`''` for the top level).
`name`	string	The new folder's name.

Response 200

Field	Type	Description
`ok`	boolean
`path`	string

Example response

JSON

{
  "ok": true,
  "path": "string"
}

Errors

Status	Message
404	That folder has gone
409	There is already a folder with that name there
400	The mail server didn't create it: …

Example request

JavaScript

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

#Rename or move a folder

PATCH/api/folders

Rename and/or move.

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

Request body JSON

Name	Type	Description
`mb`	any
`path`	string
`parent`	any
`name`	string

Response 200

Field	Type	Description
`ok`	boolean
`path`	string

Example response

JSON

{
  "ok": true,
  "path": "string"
}

Errors

Status	Message
404	That folder has gone
400	Inbox, Drafts, Sent, Junk and Trash can't be renamed or moved
404	The folder to move it into has gone
400	A folder can't go inside itself
409	There is already a folder with that name there
400	The mail server didn't rename it: …

Example request

JavaScript

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

#Delete a folder

DELETE/api/folders

Its messages go to Trash first.

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

Request body JSON

Name	Type	Description
`mb`	any
`path`	string

Response 200

Field	Type	Description
`ok`	boolean
`movedToTrash`	any

Example response

JSON

{
  "ok": true,
  "movedToTrash": null
}

Errors

Status	Message
404	That folder has gone
400	Inbox, Drafts, Sent, Junk and Trash can't be deleted
400	Move or delete the folders inside it first
400	The mail server didn't delete it: …

Example request

JavaScript

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

#Save the folder order

PUT/api/folders/order

How you arranged them.

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

Request body JSON

Name	Type	Description
`mb`	any
`order`	array of any

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/folders/order', {
  method: 'PUT',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"mb":"…","order":[]}),
});
const data = await res.json();

#List mail rules

GET/api/rules

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

Query parameters

Name	Type	Description
`mb`	any

Response 200

Errors

Status	Message
422	These rules were written in a way Bramble can't read. Ask Bramble IT to look at them.

Example request

JavaScript

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

#Save mail rules

PUT/api/rules

Replaces the whole list, in order.

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

Request body JSON

Name	Type	Description
`mb`	any
`rules`	array of any

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Errors

Status	Message
400	Send the list of rules

Example request

JavaScript

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

Was this page helpful?