API
Contacts
Address books, contacts, photos and vCard import and export for the mailboxes you belong to.
These routes act only on mailboxes the signed-in person is a member of; keys get no mailboxes. See Contacts.
Every route below, with its parameters, request and response, errors and samples, is in the API reference.
| Route | What it does |
|---|---|
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books | The mailbox's address books, default first. The default address book is created on first use. |
POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books | Creates an address book (at most 20 per mailbox). |
PATCH /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId | Renames an address book. |
DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId | Deletes an address book and its contacts. The default address book can't be deleted. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/contacts | Contacts by name across the mailbox's address books, or one. q matches names, emails, phone numbers and organizations; every word must match. Pages with cursor. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/contacts/summary | The mailbox's contacts at a glance: how many, their labels with counts, and birthdays in the next days days from today (the reader's date). |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/contacts/duplicates | Contacts that look like the same person (a shared email, phone number or full name), fullest first in each group. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/contacts/frequent | The people the mailbox writes to most (its recent sent mail), with their contacts. Needs mail:read as well. |
POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/contacts/merge | Merges contacts into one (keep): blank fields filled, every distinct email, phone, address and label kept; the others are deleted. |
POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/contacts/bulk | One change to many contacts: add or remove labels, move to another address book, or delete. |
PATCH /v1/orgs/:orgId/mail/mailboxes/:mailboxId/contacts/labels/:label | Renames a label on every contact that has it. |
DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/contacts/labels/:label | Removes a label from every contact (the contacts stay). |
GET /v1/orgs/:orgId/mail/contacts/lookup | Contacts with an email address across the person's mailboxes in the org (or one, mailboxId): Mail's sender cards and Customers' "In Contacts". Mailboxes they aren't a member of are never read. |
POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts | Creates a contact. It needs a name, organization, email or phone number. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId | A contact. |
PUT /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId | Changes a contact. Fields left out keep their value; an empty birthday or anniversary clears it. |
DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId | Deletes a contact and its photo. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId/photo | A short-lived link to the contact's photo. |
PUT /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId/photo | Sets the contact's photo: a JPEG, PNG, GIF or WebP image of at most 1 MB, base64-encoded. |
DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId/photo | Removes the contact's photo. |
POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/import | Adds the contacts in a vCard file (3.0 or 4.0), photos included; contacts whose UID is already in the address book are replaced. |
GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/export | The address book as a vCard file, version 4.0 or 3.0. |