عناوين الإرسال باسم عبر API وMCP

يفصل TrekMail بين مهمتين تستخدمان بيانات اعتماد وأذونات مختلفة:

1. تدير واجهة لوحة التحكم/Ops ملفات SMTP القابلة لإعادة الاستخدام وتوجيه النطاقات. تستخدم رمز tm_live_ مع smtp:read أو smtp:write.
2. تدير واجهة بريد الويب/الرسائل عناوين المرسل المتاحة لصندوق بريد واحد وصندوق وارد متصل واحد. تستخدم رمز tm_msg_ مع messages:read أو messages:write أو messages:send.

هذا الفصل مقصود. يستطيع رمز صندوق البريد اختيار مسار إرسال مصرح به مسبقا، لكنه لا يستطيع كشف بيانات اعتماد SMTP أو إدارة البنية الأساسية لحساب آخر.

الخلاصة

• إذا أرسلت باستخدام external_account_id وحده، يرى المستلمون عنوان الحساب المتصل نفسه ويتم استخدام خادم SMTP الخاص به.
• إذا أرسلت أيضا identity_id مرتبطا بالمصدر، يرى المستلمون عنوان العمل الخاص بالهوية. يستخدم TrekMail مسار النطاق أو ملف SMTP المحفوظ المعين لتلك الهوية، ثم يحفظ نسخة الرسالة المرسلة في صندوق الوارد المتصل.
• تتيح Starter إعداد ذلك واستخدامه في بريد الويب. تتيح Pro وAgency أيضا أتمتته عبر API أو MCP. لا توفر Nano أماكن لحسابات متصلة.

تتطور أدوات API وMCP المتاحة مع المنتج. تستخدم ميزة الإرسال باسم مجموعتي SMTP والرسائل، ولا يرى كل اتصال إلا المجموعة الفرعية التي تسمح بها خطته ونطاقاته والأذونات المعتمدة.

نموذج التوجيه

عند إرسال external_account_id من دون identity_id، يرسل TrekMail عبر خادم SMTP الخاص بذلك الحساب الخارجي ويستخدم عنوانه.

عند إرسال القيمتين، يعامل TrekMail الحساب الخارجي على أنه وجهة صندوق الوارد/المرسل والهوية على أنها عنوان المرسل الظاهر + مسار SMTP:

connected Gmail inbox
  + Send As identity sales@example.com
  + identity route: domain or saved SMTP profile
  = recipients see sales@example.com
    mail is delivered through the identity route
    the Sent copy is appended to that Gmail account

يجب ربط الهوية والحساب الخارجي ببعضهما. يؤدي حذف المصدر أو تقديم هوية من صندوق بريد آخر إلى إرجاع 422 identity_unavailable.

1. فحص SMTP أو إعداده في API لوحة التحكم

استخدم رمز Ops.

لا تعيد قراءة الملف كلمة المرور أبدا. يمثل endpoint الاستخدام الطريقة الآمنة التي تتيح للوكيل شرح التأثير قبل تعديل ملف مشترك أو حذفه.

أدوات MCP: get_domain_smtp وset_domain_smtp وlist_domain_smtp_profiles وget_domain_smtp_profile_usage وcreate_domain_smtp_profile وupdate_domain_smtp_profile وdelete_domain_smtp_profile وtest_domain_smtp وget_domain_smtp_test_status وget_account_smtp_default وset_account_smtp_default.

2. عرض العناوين لصندوق الوارد المحدد

استخدم رمز الرسائل:

GET /api/v1/messages/identities?external_account_id=42
Authorization: Bearer tm_msg_...

تتضمن الاستجابة identities الخاصة بالمصدر، وكل external_identities المعدة، وsending_addresses، وsend_as_domains المؤهلة، وreply_from_policy لصندوق البريد، وكذلك smtp_profiles المحفوظة التي يمكن اختيارها مباشرة، لصندوق بريد مالك الحساب فقط.

MCP: استدع list_identities مع external_account_id.

MCP المستضاف مقابل stdio المحلي

هناك اختلاف مهم واحد في النقل بين أدوات الرسائل:

• MCP HTTP المستضاف (OAuth): مرر أيضا mailbox_id في كل استدعاء لأداة رسائل. يستخدمه الخادم المستضاف لإنشاء رمز رسائل قصير الأجل لصندوق البريد المحدد. على سبيل المثال، استدع list_identities مع { "mailbox_id": 7, "external_account_id": 42 }.
• MCP stdio المستضاف ذاتيا (tm_msg_): لا تمرر mailbox_id. رمز الرسائل الثابت مرتبط مسبقا بصندوق بريد واحد، لذلك لا يحتاج مخطط الأداة إلا إلى external_account_id.

لا يستبدل external_account_id قيمة mailbox_id أبدا: فهو يحدد صندوق وارد متصلا داخل صندوق البريد المصرح به مسبقا. تظل أدوات SMTP للوحة التحكم محدودة بالحساب ولا تقبل mailbox_id في أي من طريقتي النقل.

3. إنشاء هوية إرسال باسم

POST /api/v1/messages/identities
Authorization: Bearer tm_msg_...
Idempotency-Key: send-as-sales-v1
Content-Type: application/json

{
  "kind": "send_as",
  "external_account_id": 42,
  "email": "sales@example.com",
  "name": "Example Sales",
  "reply_to": "sales@example.com",
  "smtp_mode": "domain"
}

يجب أن تكون email مسبقا العنوان الأساسي لصندوق البريد هذا أو اسما مستعارا نشطا مسموحا له بالإرسال. يجب أن يكون نطاقه نشطا ومملوكا للحساب نفسه. يتبع smtp_mode: domain مسار النطاق المعد في لوحة التحكم. يثبت smtp_mode: profile الهوية على smtp_connection_id؛ ويقتصر الاختيار المباشر للملف على صندوق بريد مالك الحساب.

قيمة external_account_id اختيارية، ومن المهم توضيح معناها بدقة:

• ضمنها عندما تقرأ بريد ذلك العنوان عبر صندوق وارد متصل من Gmail أو Outlook أو IMAP. ترتبط الهوية عندئذ بذلك الصندوق ولا يمكن استخدامها إلا معه.
• احذفها عندما تتم إعادة توجيه البريد إلى صندوق TrekMail بدلا من ذلك. هذا هو سير عمل صندوق الوارد المشترك، حيث يحتفظ العميل ببريده لدى مزوده ويرسل نسخا إلى صندوق بريد الفريق. تنتمي الهوية إلى صندوق البريد نفسه ويمكن لكل عضو لديه إذن إرسال استخدامها.

لا يمكن أبدا إرفاق صندوق وارد شخصي متصل بصندوق بريد مشترك: فهو خاص بالشخص الذي ربطه. احذف external_account_id هناك.

MCP: استخدم create_identity مع kind=send_as. في MCP المستضاف، ضمن قيمة mailbox_id الأصلية كما هو موضح أعلاه.

4. الإرسال أو إنشاء مسودة أو الجدولة أو الرد أو إعادة التوجيه

تقبل عمليات الرسائل العادية زوج المصدر نفسه:

{
  "external_account_id": 42,
  "identity_id": 91,
  "to": ["customer@example.net"],
  "subject": "Hello",
  "body": { "text": "Hello from Example Sales" }
}

تدعم identity_id الإرسال الفوري وحفظ/تحديث المسودة والإرسال المجدول. يقبل إعداد الرد/إعادة التوجيه external_account_id ويحدد الهوية المطابقة من ترويسات التسليم. يعاد تفويض الهوية المحددة عندما تعمل الرسالة الموضوعة في قائمة الانتظار فعليا؛ ويؤدي تعطيل اسمها المستعار أو نطاقها أو ملفها أو حسابها المتصل إلى إيقاف التسليم بدلا من الرجوع بصمت إلى عنوان مرسل آخر.

أدوات MCP: send_message وsave_draft وupdate_draft وschedule_message وprepare_reply وprepare_reply_all وprepare_forward.

سياسة الرد

PATCH /api/v1/messages/identities/reply-policy
Authorization: Bearer tm_msg_...
Idempotency-Key: reply-policy-v1

{ "reply_from_policy": "recipient" }

يرد recipient من العنوان الذي تلقى الرسالة عندما يكون ذلك ممكنا. يبدأ default دائما من القيمة الافتراضية لصندوق البريد في البريد العادي. يستخدم MCP الأداة set_reply_from_policy.

قواعد الأمان والعزل

• لا تنتقل بيانات اعتماد SMTP أبدا إلى استجابة API الرسائل أو MCP.
• يقتصر كل حساب خارجي وكل هوية على صندوق البريد الخاص برمز الرسائل.
• لا يمكن استخدام هوية إرسال باسم متصلة إلا مع قيمة external_account_id المحددة لها؛ ولا يمكن استخدام الهوية المملوكة لصندوق البريد إلا من دونها.
• يجب أن يكون عنوان المرسل مصرحا به مسبقا كعنوان صندوق بريد أو اسم مستعار مسموح له بالإرسال؛ ولا تستطيع API إنشاء عناوين مرسل عشوائية.
• يلزم وجود مسار عامل قبل الإنشاء ويعاد التحقق منه وقت التسليم.
• لا يمكن أن تتعارض ترويسات Reply-To المخصصة مع Reply-To المحفوظ للهوية.
• تتطلب تغييرات الهوية والملف عبر MCP إذن الكتابة المناسب. يمكن لمسؤول MCP مستضاف محليا أن يطلب موافقة صريحة على إجراءات الكتابة؛ ويتطلب الإرسال أيضا تأكيدا لكل رسالة.

لا يلزم إنشاء سلاسل نطاق جديدة للرموز. تستمر رموز smtp:* وmessages:* الحالية في العمل وفقا لأذوناتها الحالية.

ما حد الإرسال المطبق؟

تحتفظ استدعاءات API أيضا بإجراءات الحماية من إساءة الاستخدام: افتراضيا، 60 طلب إرسال في الدقيقة لكل رمز رسائل و100 عملية إرسال عبر API يوميا في صندوق البريد بأكمله. تنطبق هذه الحدود بغض النظر عن الخادم الذي يسلم البريد الإلكتروني في النهاية.