ReferenceMail, Calendar & Contacts API

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)

#Everything the contacts page needs to start

GET/api/contacts/bootstrap

Address: https://<your-org>.brambleit.cloud/mail/api/contacts/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
`books`	array of any
`dav`	object
`dav.url`	string
`dav.username`	string

Example response

JSON

{
  "me": {
    "name": "Example name",
    "email": "alex@example.com"
  },
  "books": [],
  "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/contacts/bootstrap', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#The organisation directory

GET/api/contacts/directory

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

Response 200

Field	Type	Description
`id`	integer
`name`	string
`given`	string
`family`	string
`email`	string
`title`	string
`department`	string
`location`	string

Example response

JSON

[
  {
    "id": 42,
    "name": "Example name",
    "given": "string",
    "family": "string",
    "email": "alex@example.com",
    "title": "Example title",
    "department": "string",
    "location": "string"
  }
]

Example request

JavaScript

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

#Create a book

POST/api/contacts/books

Address: https://<your-org>.brambleit.cloud/mail/api/contacts/books
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
`uri`	any

Response 200

Example request

JavaScript

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

#Rename an address book

PATCH/api/contacts/books/:id

Address: https://<your-org>.brambleit.cloud/mail/api/contacts/books/: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

Example request

JavaScript

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

#Delete an address book

DELETE/api/contacts/books/:id

Address: https://<your-org>.brambleit.cloud/mail/api/contacts/books/: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/contacts/books/42', {
  method: 'DELETE',
  credentials: 'include',
});
const data = await res.json();

#List contacts of a book

GET/api/contacts/books/:id/contacts

Address: https://<your-org>.brambleit.cloud/mail/api/contacts/books/:id/contacts
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/contacts/books/42/contacts', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Add a contact

POST/api/contacts/books/:id/contacts

Address: https://<your-org>.brambleit.cloud/mail/api/contacts/books/:id/contacts
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
`uri`	any
`etag`	any

Example response

JSON

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

Example request

JavaScript

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

#Update a contact

PATCH/api/contacts/books/:id/contacts/:uri

Address: https://<your-org>.brambleit.cloud/mail/api/contacts/books/:id/contacts/: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
`moveTo`	number

Response 200

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

Example response

JSON

{
  "book": 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/contacts/books/42/contacts/string', {
  method: 'PATCH',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"etag":"…","moveTo":12.5}),
});
const data = await res.json();

#Delete a contact

DELETE/api/contacts/books/:id/contacts/:uri

Address: https://<your-org>.brambleit.cloud/mail/api/contacts/books/:id/contacts/: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

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/contacts/books/42/contacts/string', {
  method: 'DELETE',
  credentials: 'include',
});
const data = await res.json();

#Import a .vcf file (one or many cards)

POST/api/contacts/books/:id/import

Import a .vcf file (one or many cards). Cards with a UID already in the book replace it.

Address: https://<your-org>.brambleit.cloud/mail/api/contacts/books/: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/contacts/books/42/import', {
  method: 'POST',
  credentials: 'include',
});
const data = await res.json();

#Export an address book (.vcf)

GET/api/contacts/books/:id/export.vcf

Address: https://<your-org>.brambleit.cloud/mail/api/contacts/books/:id/export.vcf
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/contacts/books/42/export.vcf', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

Was this page helpful?