API와 MCP로 TrekMail 연락처 관리하기

메일함의 주소록은 완전히 프로그래밍할 수 있습니다. 메시지 API와 MCP 도구로 연락처를 생성, 수정, 삭제하고 CSV 또는 vCard로 대량 가져오기와 내보내기를 수행하며, 대규모 주소록을 검색하고 사람들을 그룹으로 정리할 수 있습니다. 웹메일과 CardDAV 클라이언트에서 보는 데이터와 동일하므로 AI 에이전트가 추가한 연락처가 휴대전화에 표시되고, 휴대전화에서 추가한 연락처도 API에 표시됩니다.

시작하기 전에

• 연락처에는 대시보드 API 토큰이 아니라 메시지 토큰 영역(/api/v1/messages/...)과 해당 범위를 사용합니다.
• 모든 호출은 토큰 자체 메일함으로 제한됩니다. 토큰은 자신의 연락처와 그룹만 보고 관리할 수 있으며 다른 메일함에는 접근할 수 없습니다.
• 연락처는 메일함 안에서 이메일 주소로 식별됩니다. 가져오기는 일치하는 연락처를 업데이트합니다. 기존 이메일로 연락처를 만들면 중복 항목 대신 기존 연락처가 변경 없이 반환됩니다.
• 목록 응답은 이름, 이메일, 회사, 직함, 전화번호, 주소, 생일, 메모처럼 깔끔하고 읽기 쉬운 필드를 반환합니다. 동기화된 연락처의 원시 CardDAV 카드는 반환되지 않으며 항상 정리된 버전을 받습니다.
• 가져오기는 최대 10 MB의 CSV와 vCard (.vcf) 파일을 지원하며 Google Contacts, Outlook, Apple, Roundcube의 내보내기 형식과 UTF-8, UTF-16, BOM 차이를 처리합니다.

범위

연락처 관리

기본 경로: /api/v1/messages/contacts

목록 및 검색

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를, 다른 메일 클라이언트에서 불러올 .vcf 파일에는 format=vcard를 사용하세요.

연락처 그룹

그룹은 주소록 안의 배포 목록입니다. 기본 경로: /api/v1/messages/contact-groups

그룹 구성원 목록

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개의 연락처 ID를 받습니다. 더 큰 배치는 여러 요청으로 나눠야 합니다.

MCP 도구

같은 주소록을 MCP를 통해 AI 에이전트에서 사용할 수 있습니다(비공개 stdio 서버와 공개 MCP 서버 모두 지원).

쓰기 도구에는 여전히 메시지 토큰의 쓰기 범위가 필요합니다. 로컬 호스팅 MCP 관리자는 쓰기 작업에 명시적인 승인을 요구할 수도 있으므로 에이전트가 연락처를 탐색하되 변경하지 못하도록 할 수 있습니다.