Managing Contacts via API and MCP

Your mailbox's address book is fully programmable. The message API and the MCP tools expose everything the webmail Contacts panel can do — create, edit, and delete contacts, import and export in bulk (CSV or vCard), search, page through a large address book, and organize people into groups. This is the same data your webmail and CardDAV clients see, so a contact added by an AI agent shows up on your phone, and one you added on your phone is visible to the API.

Before you start

• Contacts use the message token surface (/api/v1/messages/...), authorized by a message token with the scopes below — not a dashboard API token.
• Every call is scoped to the token's own mailbox. A token can only see and manage its own contacts and groups — never another mailbox's.
• Contacts are keyed by email address within a mailbox. Importing or creating a contact whose email already exists updates that contact rather than making a duplicate.
• List responses return a clean, human-readable set of fields (name, email, company, job title, phone, address, birthday, notes). The raw CardDAV card behind a synced contact is never returned — you always get the tidy version.
• Import accepts CSV and vCard (.vcf) files up to 10 MB, and understands the export formats of Google Contacts, Outlook, Apple, and Roundcube (including UTF-8/UTF-16 and BOM quirks).

Scopes

Managing contacts

Base path: /api/v1/messages/contacts

List and search

GET /api/v1/messages/contacts?q=alice&per_page=50&page=1
Scope: messages:read

q matches on name or email. Results come back paged (per_page 1–100, default 50) with a pagination block (total, per_page, current_page, last_page) so you can walk a large address book to the end instead of stopping at the first page.

Create a contact

POST /api/v1/messages/contacts
Scope: messages:write
{
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "company": "Analytical Engines",
  "job_title": "Mathematician",
  "phone": "+1 555 0100",
  "address": "London",
  "birthday": "1815-12-10",
  "notes": "Met at the conference"
}

Only email is required. If a contact with that email already exists, the existing one is returned unchanged — creation never makes a duplicate.

Import in bulk

POST /api/v1/messages/contacts/import
Scope: messages:write
{
  "content_base64": "<base64 of your .csv or .vcf file>",
  "format": "csv"
}

Send the file base64-encoded with format set to csv or vcf (max 10 MB decoded). The response tells you how many rows were applied and how many were skipped for lacking a usable email:

{ "imported": 128, "skipped": 3 }

Column headers from Google, Outlook, Apple, and Roundcube exports are recognized automatically, so most exports import without any editing.

Export

GET /api/v1/messages/contacts/export?format=vcard
Scope: messages:read

Returns the whole address book as a single file, base64-encoded:

{ "format": "vcard", "content_base64": "..." }

Use format=csv for a spreadsheet-friendly file or format=vcard for a .vcf you can load into another mail client.

Contact groups

Groups are distribution lists inside the address book. Base path: /api/v1/messages/contact-groups

List who is in a group

GET /api/v1/messages/contact-groups/42/members?per_page=50&page=1
Scope: messages:read

Returns the group's contacts (same tidy fields as the contacts list) plus a pagination block and the group's total contact_count, so you can read a group's membership, not just change it blindly.

Add or remove members

POST /api/v1/messages/contact-groups/42/members
Scope: messages:write
{ "contact_ids": [11, 12, 13] }

Adding is idempotent — a contact already in the group is left as-is. Only contacts that belong to the same mailbox can be added.

MCP tools

The same address book is available to AI agents over MCP (both the private stdio server and the public MCP server):

Write tools follow the same safety posture as the rest of the MCP server: they run only when destructive operations are enabled on the server, so an agent can browse your contacts freely but can't change them unless you've allowed it.