Управление контактами через API и MCP
Создавайте, импортируйте, экспортируйте, ищите и упорядочивайте контакты и группы TrekMail через API сообщений и MCP: эндпоинты, области и пагинация.
Сведения о статье
Тип, сложность, тарифы и дата последнего обновления.
▼
Сведения о статье
Тип, сложность, тарифы и дата последнего обновления.
- Тип
- Справочная статья
- Сложность
- Средний уровень
- Тарифы
- Starter · Pro · Agency
- Обновлено
- 10 сен 2026 г.
Адресная книга вашего почтового ящика полностью программируема. API сообщений и инструменты MCP позволяют создавать, изменять и удалять контакты, массово импортировать и экспортировать данные (CSV или vCard), выполнять поиск в большой адресной книге и объединять людей в группы. Эти же данные отображаются в веб-почте и клиентах CardDAV, поэтому добавленный ИИ-агентом контакт появляется на телефоне, а добавленный с телефона контакт становится доступен через API.
Перед началом работы
- Для контактов используется интерфейс токена сообщений (
/api/v1/messages/...) и его области, а не токен API панели управления. - Каждый вызов ограничен почтовым ящиком самого токена. Токен может просматривать и изменять только собственные контакты и группы, но не данные другого ящика.
- Контакты внутри почтового ящика определяются по адресу электронной почты. При импорте совпавший контакт обновляется. Если создать контакт с уже существующим адресом, система вернет его без изменений, а не создаст дубликат.
- Ответы со списками содержат понятный набор полей (имя, адрес электронной почты, компания, должность, телефон, адрес, день рождения и заметки). Необработанная карточка CardDAV, связанная с синхронизированным контактом, никогда не возвращается; вы всегда получаете упорядоченную версию.
- Для импорта принимаются файлы CSV и vCard (
.vcf) размером до 10 MB. Поддерживаются форматы экспорта Google Контактов, Outlook, Apple и Roundcube, включая особенности UTF-8, UTF-16 и BOM.
Области доступа
| Область | Возможности |
|---|---|
messages:read |
Просмотр и поиск контактов, просмотр групп и их участников, экспорт |
messages:write |
Создание, обновление, удаление и импорт контактов; создание групп и управление ими |
Управление контактами
Базовый путь: /api/v1/messages/contacts
| Метод | Путь | Область | Назначение |
|---|---|---|---|
GET |
/contacts |
messages:read |
Получить список контактов с поиском и пагинацией |
POST |
/contacts |
messages:write |
Создать контакт |
PATCH |
/contacts/{id} |
messages:write |
Обновить контакт |
DELETE |
/contacts/{id} |
messages:write |
Удалить контакт |
POST |
/contacts/import |
messages:write |
Массово импортировать файл CSV или vCard |
GET |
/contacts/export |
messages:read |
Экспортировать все контакты как CSV или vCard |
Просмотр и поиск
GET /api/v1/messages/contacts?q=alice&per_page=50&page=1
Scope: messages:read
q ищет совпадения по имени или адресу электронной почты. Результаты возвращаются постранично (per_page от 1 до 100, по умолчанию 50) с блоком pagination (total, per_page, current_page, last_page), поэтому большую адресную книгу можно просмотреть до конца, не останавливаясь на первой странице.
Создание контакта
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"
}
Обязательно только поле email. Если контакт с таким адресом уже существует, он будет возвращен без изменений. При создании система не создает дубликат и не перезаписывает сохраненные сведения.
Массовый импорт
POST /api/v1/messages/contacts/import
Scope: messages:write
{
"content_base64": "<base64 of your .csv or .vcf file>",
"format": "csv"
}
Отправьте файл в кодировке base64, задав для format значение csv или vcf (не более 10 MB после декодирования). В ответе будет указано, сколько строк применено и сколько пропущено из-за отсутствия подходящего адреса электронной почты:
{ "imported": 128, "skipped": 3 }
Заголовки столбцов из файлов экспорта Google, Outlook, Apple и Roundcube распознаются автоматически, поэтому большинство экспортированных файлов можно импортировать без редактирования.
Экспорт
GET /api/v1/messages/contacts/export?format=vcard
Scope: messages:read
Возвращает всю адресную книгу в виде одного файла, закодированного в base64:
{ "format": "vcard", "content_base64": "..." }
Используйте format=csv, чтобы получить файл для электронных таблиц, или format=vcard, чтобы получить файл .vcf для загрузки в другой почтовый клиент.
Группы контактов
Группы представляют собой списки рассылки внутри адресной книги. Базовый путь: /api/v1/messages/contact-groups
| Метод | Путь | Область | Назначение |
|---|---|---|---|
GET |
/contact-groups |
messages:read |
Получить список групп с contact_count для каждой |
POST |
/contact-groups |
messages:write |
Создать группу |
PATCH |
/contact-groups/{id} |
messages:write |
Переименовать группу |
DELETE |
/contact-groups/{id} |
messages:write |
Удалить группу |
GET |
/contact-groups/{id}/members |
messages:read |
Получить список контактов группы |
POST |
/contact-groups/{id}/members |
messages:write |
Добавить контакты в группу |
DELETE |
/contact-groups/{id}/members |
messages:write |
Удалить контакты из группы |
Просмотр участников группы
GET /api/v1/messages/contact-groups/42/members?per_page=50&page=1
Scope: messages:read
Возвращает контакты группы с теми же упорядоченными полями, что и в списке контактов, а также блок pagination и общее значение contact_count группы. Так можно просмотреть состав группы, а не изменять его вслепую.
Добавление и удаление участников
POST /api/v1/messages/contact-groups/42/members
Scope: messages:write
{ "contact_ids": [11, 12, 13] }
Добавление идемпотентно: если контакт уже состоит в группе, он остается без изменений. Можно добавлять только контакты из того же почтового ящика. Каждый запрос на добавление или удаление принимает от 1 до 200 идентификаторов контактов; более крупные наборы необходимо разделить на несколько запросов.
Инструменты MCP
Эта же адресная книга доступна ИИ-агентам через MCP, как на частном сервере stdio, так и на общедоступном сервере MCP:
| Инструмент | Область | Назначение |
|---|---|---|
list_contacts |
read | Просмотр и поиск контактов с пагинацией |
create_contact |
write | Создать контакт |
update_contact |
write | Обновить контакт |
delete_contact |
write | Удалить контакт |
import_contacts |
write | Импортировать файл CSV/vCard в base64 |
export_contacts |
read | Экспортировать все контакты как CSV/vCard |
list_contact_groups |
read | Получить список групп с количеством участников |
list_contact_group_members |
read | Получить список контактов группы |
create_contact_group |
write | Создать группу |
update_contact_group |
write | Переименовать группу |
delete_contact_group |
write | Удалить группу |
add_contact_group_members |
write | Добавить контакты в группу |
remove_contact_group_members |
write | Удалить контакты из группы |
Инструментам записи по-прежнему требуется область записи токена сообщений. Администратор локального сервера MCP также может потребовать явного подтверждения операций записи, чтобы агент мог просматривать контакты без возможности их изменять.
Связанные статьи
Похожие статьи
Перейдите к близким руководствам, которые продолжают рабочий процесс.