التعامل مع صناديق البريد

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

لتطبيق الأمثلة، نحتاج للحصول على مفتاح الواجهة البرمجية لزيتون وتخزينه ضمن متغير باسم TOKEN$ واستخدامه في الطلبات المختلفة.

export TOKEN="YOUR_API_KEY"

طلب إنشاء صندوق بريد جديد

يتضمن مركز مساعدة زيتون افتراضيًا صندوقي بريد، الأول هو الصندوق الوارد الذي يستقبل الرسائل بشكل افتراضي وحالته default، والثاني هو الصندوق الذي تحول إليه كافة الرسائل التي تصنف كمزعجة وحالته spam، وأي صندوق آخر ننشؤه لاحقًا سيكون بالحالة normal.

يمكننا إنشاء صندوق بريد جديد وتخصيصه بشكل مبدئي من خلال إرسال طلب POST لنقطة الوصول Create an inbox، تسمح لنا هذه النقطة بضبط إعدادات الصندوق الأساسية كالاسم، والوصف، ورسالة الرد التلقائي ورسالة التقييم، لكننا سنحتاج بعدها لاستخدام نقاط وصول أخرى لضبط بقية إعدادات الصندوق الجديد مثل تحديد عناوين البريد المرتبطة بالصندوق، وفرق العمل التي تملك صلاحيات عليه وغيرها من الخيارات المتقدمة كما سنوضح لاحقًا في فقرة تعديل إعدادات صندوق البريد.

كما يمكننا إنشاء صندوق جديد وضبط كافة خياراته من خلال إرسال طلب POST لنقطة الوصول Update or create an inbox دون الحاجة لأي نقاط وصول أخرى، ويمكننا استخدام نقطة الوصول هذه لتعديل إعدادات صندوق بريد موجود باستخدام رقمه التعريفي كما سنشرح لاحقًا.

ملاحظة: سيأخذ كل صندوق بريد جديد ننشئه جميع حالات المحادثات المُعَرَّفة في مركز المساعدة دون الحاجة لأي إعدادات خاصة، علمًا أنه يتوفر في مراكز مساعدة زيتون حالتان افتراضيتان للمحادثات هما: مفتوحة open ومغلقة closed ويمكن إنشاء حالات إضافية مثل قيد المعالجة، أو بانتظار الرد وضبطها باستخدام نقطة الوصول Create a conversation status.

إنشاء صندوق جديد

لإنشاء صندوق بريد جديد في مركز مساعدة له النطاق example.com باستخدام نقطة الوصول Create an inbox نكتب الطلب على النحو التالي:

curl -X POST \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     --data '{
         "name": "your_inbox_name",
         "description": "your_inbox_description",
         "slug": "your-inbox-slug",
         "send_autoresponse": true,
         "autoresponse_text": "your_autoresponse_text",
         "send_rating_request": true,
         "rating_message": "your_rating_message"
     }' \
     'https://example.com/api/agent/v1/inboxes'

ولإنشاء صندوق بريد جديد باستخدام نقطة الوصول Update or create an inbox نكتب الطلب على النحو التالي:

curl -X POST \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     --data '{
         "name": "new_inbox_name",
         "description": "new_inbox_description",
         "slug": "new-inbox",
         "sort": 6,
         "send_autoresponse": true,
         "autoresponse_text": "your_autoresponse_text",
         "emails": [
             {"email": "support1@example.com", "status": "primary"},
             {"email": "support2@exampel.com", "status": "secondary"}
         ],
         "send_rating_request": true,
         "rating_message": "your_rating_message",
         "team_ids": [109, 1009],
         "agent_ids": [1008]
     }' \
     'https://example.com/api/agent/v1/inboxes/save'

طلب عرض صناديق البريد

يمكن الحصول على إعدادات كافة صناديق البريد العائدة لمركز مساعدة معين بإرسال طلب GET إلى نقطة الوصول List all inboxes.

عرض كافة الصناديق

لعرض كافة صناديق البريد العائدة لمركز مساعدة له النطاق example.com نكتب الطلب التالي:

curl --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/inboxes'

عرض صناديق بشروط محددة

لعرض صناديق البريد العائدة لمركز مساعدة له النطاق example.com، والمنشأة قبل تاريخ 2025/04/01، مع إظهارها بترتيب تنازلي تبعًا للقيمة sort نكتب الطلب التالي:

curl --header 'Authorization: Bearer @TOKEN' \
     --globoff \
     'https://example.com/api/agent/v1/inboxes?before[created_at]=2025-04-01T00%3A00%3A00&sort=sort.desc'

طلب تعديل الصندوق

يمكننا تعديل أي صندوق بريد وتخصيصه بالطريقة التي تناسبنا باستخدام أكثر من نقطة وصول في الواجهة البرمجية، حيث يمكن إرسال طلب PUT إلى نقطة الوصول Update an inbox لتعديل الخصائص الأساسية لصندوق البريد في مركز المساعدة عن طريق تمريرها كمعاملات في جسم الطلب.

كما يمكن إرسال طلب من نوع POST لنقطة الوصول Update or create an inbox لتحقيق وظيفتين الأولى إنشاء صندوق بريد جديد كما وضحنا في الفقرة السابقة، والثانية لتعديل كافة خصائص صندوق بريد موجود، وما يميز وظيفة عن أخرى هو استخدام المعامل id فعند تمريره في عنوان الطلب نشير لأننا نُعَدِّل الصندوق، وإلا فإننا ننشئ صندوق جديد.

تعديل الخصائص الأساسية للصندوق

لنفترض أن لدينا مثلًا صندوق بريد له الرقم التعريفي 1010 في مركز مساعدة على النطاق example.com، ونريد تعديل اسمه ليصبح new_inbox_name مع تعطيل ميزتي الرد التلقائي وطلب التقييم سنكتب الطلب كما يلي:

curl -X PUT \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     --data '{
         "name": "new_inbox_name",
         "slug": "new_inbox_slug",
         "sort": 6,
         "send_rating_request": false,
         "send_autoresponse": false
     }' \
     'https://example.com/api/agent/v1/inboxes/1010'

ينبغي أن يتضمن الطلب المعاملات الإجبارية لنقطة الوصول مع أي معاملات أخرى نريد تعديلها.

تعديل كافة خصائص الصندوق

فيما يلي طلب لتعديل بعض الخصائص المتقدمة لصندوق البريد رقم 1010 ضمن مركز مساعدة له النطاق example.com:

curl -X POST -header 'Content-Type: application/json' --header 'Authorization: Bearer @TOKEN'
--data '{"id": 1010,
"name": "new_inbox_name",
"slug" :"new_inbox_slug",
"send_autoresponse": true,
"autoresponse_text": "your_new_text",
"send_rating_request": false,
"team_ids": [19, 109, 1009]
}' 'https://example.com/api/agent/v1/inboxes/save'

طلب إضافة بريد للصندوق

لإضافة بريد إلكتروني لصندوق، نرسل طلب POST إلى نقطة الوصول Add an inbox email مع تمرير الرقم التعريفي لصندوق البريد المطلوب كمعامل ضمن عنوان الطلب.

إضافة بريد للصندوق

لإضافة بريد إلكتروني جديد للصندوق رقم 1010 ضمن مركز مساعدة له النطاق example.com نكتب الطلب التالي:

curl -X POST \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     --data '{
         "email": "new_email@example.com",
         "status": "secondary"
     }' \
     'https://example.com/api/agent/v1/inboxes/1010/emails'

طلب تعديل بريد الصندوق

لتعديل البريد الإلكتروني المرتبط بصندوق بريد معين، سواء تعديل عنوانه email أو حالته status، نرسل طلب PUT لنقطة الوصول Update an inbox email.

تعديل بريد الصندوق

لنفترض أننا ارتكبنا خطأ املائي بكتابة عنوان البريد الإلكتروني رقم 1017 الخاص بالصندوق رقم 1010 ضمن مركز مساعدة له النطاق example.com ونريد تعديله، سنكتب الطلب كما يلي:

curl -X PUT \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     --data '{
         "email": "updated_email@example.com"
     }' \
     'https://example.com/api/agent/v1/inboxes/1010/emails/1017'

طلب حذف بريد إلكتروني من صندوق

لحذف البريد الإلكتروني المرتبطة بصندوق بريد معين، نرسل طلب DELETE لنقطة الوصول Delete an inbox email مع تمرير رقم البريد ورقم الصندوق كمعاملات ضمن عنوان الطلب.

حذف بريد محدد من صندوق

لنحذف مثلًا عنوان البريد الإلكتروني رقم 1017 من صندوق البريد رقم 1010 ضمن مركز مساعدة له النطاق example.com نكتب الطلب التالي:

curl -X DELETE \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/inboxes/1010/emails/1017'

طلب إضافة فريق عمل للصندوق

لإضافة فريق عمل لصندوق بريد معين نرسل طلب POST لنقطة الوصول Add an inbox team مع تمرير رقم الصندوق المطلوب في عنوان الطلب، ورقم الفريق في جسم الطلب.

إضافة فريق عمل لصندوق

لإضافة فريق عمل رقم 1009 إلى صندوق بريد رقم 1010 ضمن مركز مساعدة له النطاق example.com نكتب الطلب التالي:

curl -X POST \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     --data '{
         "team_id": 1009
     }' \
     'https://example.com/api/agent/v1/inboxes/1010/teams'

طلب حذف فريق عمل من الصندوق

لحذف فريق العمل من إعدادات صندوق بريد، أو سحب الصلاحية منه نرسل طلب من نوع DELETE إلى نقطة الوصول Delete an inbox team مع تمرير كل من رقم الصندوق، ورقم فريق العمل كمعاملات في عنوان الطلب.

حذف فريق عمل محدد

لحذف فريق العمل رقم 1009 من صندوق البريد رقم 1010 ضمن مركز مساعدة له النطاق example.com نكتب الطلب التالي:

curl -X DELETE \
     --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/inboxes/1010/teams/1009' 

طلب إضافة وكيل للصندوق

يمكننا منح أحد الوكلاء صلاحيات الوصول لصندوق بريد معين من خلال إرسال طلب من نوع POST إلى نقطة الوصول Add an inbox agent ، مع تمرير الرقم التعريفي للصندوق كمعامل في عنوان الطلب، والرقم التعريفي للوكيل في جسم الطلب.

إضافة وكيل لصندوق

يضيف المثال التالي الوكيل رقم 1008 إلى صندوق البريد 1010 ضمن مركز مساعدة له النطاق example.com:

curl -X POST \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     --data '{
         "agent_id": "1008"
     }' \
     'https://example.com/api/agent/v1/inboxes/1010/agents'

طلب حذف وكيل من الصندوق

لحذف أحد الوكلاء من صندوق البريد نرسل طلب من نوع DELETE إلى نقطة الوصول Delete an inbox agent مع تمرير كل من رقم صندوق البريد، ورقم الوكيل كمعاملات مسار ضمن عنوان الطلب.

حذف وكيل من صندوق

يحذف المثال التالي الوكيل رقم 1008 من صندوق البريد رقم 1010 ضمن مركز مساعدة له النطاق example.com:

curl -X DELETE \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     'https://.example.com/api/agent/v1/inboxes/1010/agents/1008'

طلب تعديل ترتيب صندوق البريد

يمكننا التحكم بترتيب صندوق بريد معين ضمن قائمة صناديق البريد الخاصة بمركز المساعدة، وذلك بإرسال طلب من POST لنقطة الوصول Update an inbox sort مع تمرير الرقم التعريفي لصندوق البريد كمعامل ضمن عنوان الطلب، وتمرير قيمة جديدة لمعامل الفرز sort في جسم الطلب.

تعديل ترتيب صندوق

لنفترض مثلًا أننا نرغب بتغيير ترتيب صندوق البريد رقم 1010 ليصبح الصندوق الأول في قائمة صناديق بريد ضمن مركز مساعدة له النطاق example.com، كي يظهر دائمًا كأول عنصر في أي استعلام عن صناديق بريد المركز، فسنكتب عندها الأمر التالي:

curl -X POST \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     --data '{
         "sort": 0
     }' \
     'https://example.com/api/agent/v1/inboxes/1010/sort'

طلب إعادة ترتيب الصناديق

يمكننا إعادة ترتيب كافة صناديق البريد ضمن مركز المساعدة وفق قيمة معامل الفرز sort لكل صندوق، وذلك بإرسال طلب من نوع POST لنقطة الوصول Sort inboxes يتضمن معامل وحيد inboxes يمثل مصفوفة صناديق البريد المطلوب إعادة ترتيبها.

تحتوي المصفوفة inboxes على مجموعة عناصر objects، يمثل كل عنصر صندوق بريد معين، وتكتب وفق الصيغة التالية:

"inboxes": [
{"id": exampel_inbox_id, "sort": 0},
{"id": exampel_inbox_id, "sort": 1},
{"id": exampel_inbox_id, "sort": 2},
….
]

تكافئ هذه العملية إعادة ترتيب صناديق البريد التي نجريها في الواجهة الأمامية بطريقة السحب والإفلات.

ترتيب عدة صناديق

لإعادة ترتيب ثلاثة صناديق بريد ضمن مركز مساعدة له النطاق example.com نكتب الطلب التالي:

curl -X POST \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer @TOKEN' \
     --data '{
         "inboxes": [
             {"id": 10, "sort": 0},
             {"id": 110, "sort": 1},
             {"id": 1010, "sort": 2}
         ]
     }' \
     'https://example.com/api/agent/v1/inboxes/bulk-sort'

طلب الاشتراك بإشعارات البريد

يمكن للوكيل الحالي الذي سجل دخول لمركز المساعدة ويملك صلاحية الوصول لصندوق بريد معين أن يشترك بإشعارات هذا الصندوق حتى تصله رسائل بريدية بكل جديد يخصه من خلال إرسال طلب من نوع POST إلى نقطة الوصول Subscribe to an inbox مع تمرير الرقم التعريفي لصندوق البريد كمعامل في عنوان الطلب، وتمرير رمز الوصول access token الخاص بالوكيل ضمن ترويسة الطلب، ورمز الوصول هو الرمز الذي تعيده الواجهة البرمجية للوكيل عند نجاح عملية تسجيل الدخول login إلى مركز المساعدة.

اشتراك الوكيل بصندوق محدد

لجعل الوكيل الحالي مشتركًا بصندوق البريد رقم 1010ضمن مركز مساعدة له النطاق example.com نكتب الطلب التالي:

curl -X POST \
     --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/inboxes/1010/subscribe'

طلب إلغاء الاشتراك بالإشعارات

يستطيع الوكيل إلغاء اشتراكه بإشعارات صندوق البريد بإرسال طلب من نوع DELETE إلى نقطة الوصول Unsubscribe to an inbox مع تمرير الرقم التعريفي لصندوق البريد كمعامل مسار ضمن عنوان الطلب وتمرير رمز الوصول الخاص بالوكيل في ترويسة الطلب

إلغاء اشتراك الوكيل بصندوق محدد

لإلغاء اشتراك الوكيل الحالي بصندوق البريد رقم 1010ضمن مركز مساعدة له النطاق example.com نكتب الطلب التالي:

curl -X DELETE \
     --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/inboxes/1010/unsubscribe'

طلب حذف الصندوق

لحذف أي صندوق بريد من مركز المساعدة نرسل طلب من نوع DELETE إلى نقطة الوصول Delete an inbox مع تمرير الرقم التعريفي للصندوق المُراد حذفه كمعامل ضمن عنوان الطلب.

حذف صندوق محدد

لحذف صندوق البريد رقم 1010 مع جميع رسائله من مركز مساعدة له النطاق example.com نكتب الطلب التالي:

curl -X DELETE \
     --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/inboxes/1010'

عند حذف صندوق بريد، لا يلغى الوصول إلى المحادثات الخاصة بالصندوق. ويُحتَفظ بها لتوفير إمكانية تعديلها أو نقلها إلى صندوق آخر.