ניהול אנשי קשר דרך API ו-MCP ב-TrekMail
צרו, יבאו, יצאו, חפשו וארגנו אנשי קשר וקבוצות ב-TrekMail דרך API להודעות וכלי MCP, כולל נקודות קצה, היקפים ועימוד.
פרטי המאמר
סוג, רמת קושי, תוכניות ומידע על עדכון אחרון.
▼
פרטי המאמר
סוג, רמת קושי, תוכניות ומידע על עדכון אחרון.
- סוג
- חומר עזר
- רמת קושי
- בינוני
- תוכניות
- Starter · Pro · Agency
- עודכן לאחרונה
- 10 בספט׳ 2026
ספר הכתובות של תיבת הדואר ניתן לתכנות מלא. ה-API להודעות וכלי MCP יכולים ליצור, לערוך ולמחוק אנשי קשר, לייבא ולייצא בכמות גדולה (CSV או vCard), לחפש בספר כתובות גדול ולארגן אנשים בקבוצות. אלה אותם נתונים שמופיעים בדואר האינטרנט ובלקוחות CardDAV, כך שאיש קשר שסוכן AI מוסיף מופיע בטלפון, ואיש קשר שהוספתם בטלפון גלוי ל-API.
לפני שמתחילים
- אנשי קשר משתמשים בממשק אסימון ההודעות (
/api/v1/messages/...) ובהיקפים שלו, ולא באסימון API של לוח הבקרה. - כל קריאה מוגבלת לתיבת הדואר של האסימון. אסימון יכול לראות ולנהל רק את אנשי הקשר והקבוצות שלו, ולעולם לא תיבת דואר אחרת.
- אנשי קשר מזוהים לפי כתובת הדואר האלקטרוני בתוך תיבה. ייבוא מעדכן איש קשר תואם. יצירת איש קשר עם כתובת קיימת מחזירה אותו ללא שינוי במקום ליצור כפילות.
- תשובות רשימה מחזירות שדות ברורים ונוחים לקריאה: שם, דואר אלקטרוני, חברה, תפקיד, טלפון, כתובת, יום הולדת והערות. כרטיס CardDAV הגולמי שמאחורי איש קשר מסונכרן אינו מוחזר; תמיד מתקבלת הגרסה המסודרת.
- הייבוא מקבל קובצי CSV ו-vCard (
.vcf) בגודל של עד 10 MB, ומבין את פורמטי הייצוא של Google Contacts, 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
אותו ספר כתובות זמין לסוכני AI דרך 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 באחסון מקומי יכול גם לדרוש אישור מפורש לפעולות כתיבה, כך שסוכן יוכל לעיין באנשי קשר בלי לשנות אותם.
מאמרים קשורים
קפצו למדריכים הסמוכים שממשיכים את זרימת העבודה.