جهات الاتصال
`contacts.list` و`get` و`create` و`update` و`delete`.
كل الدوال
const page = await openemail.contacts.list({ limit: 100 }) const contact = await openemail.contacts.get('[email protected]') const saved = await openemail.contacts.create({ email: '[email protected]', name: 'Grace Hopper', notes: 'Met at the compiler workshop', }) await openemail.contacts.update(saved.email, { notes: null }) await openemail.contacts.delete(saved.email) console.log(page.items.length, page.hasMore, contact.source, contact.lastSeenAt)الأحدث ظهورًا أولًا، مع وضع جهات الاتصال التي لم تُراسَل قط في الآخر. وتكون source بالقيمة auto عندما كُتب السجل لأن عضوًا أرسل إلى ذلك العنوان رسالة من محرّر الرسائل في التطبيق، وهو ادعاء مختلف جوهريًا عن أن شخصًا حفظ العنوان بنفسه. ووصول بريد من عنوان لا يكتب شيئًا، وكذلك الإرسال عبر هذه الواجهة.
دفتر العناوين ملك لمساحة العمل لا لشخص واحد، فجهة الاتصال التي يحفظها أي عضو هي نفسها التي يراها كل عضو وكل مفتاح. ويكتب create قيمة source بالقيمة manual ويضع جهة الاتصال في الجمهور الافتراضي فور كتابتها. اذكر قوائمك الخاصة في audienceIds لضمّها في الاستدعاء نفسه، وهو ما يتطلب أيضًا audiences:write، أو أضف جهة الاتصال لاحقًا عبر openemail.audiences.addContact.
تُخزَّن العناوين بأحرف صغيرة ويرمّز العميل العنوان الذي تمرّره، فيصل [email protected] إلى السجل الصحيح. والعنوان هو الهوية، لذا لا يستطيع update تغييره: فنقل جهة اتصال يعني delete ثم create.
المعاملات: contacts.list
limitnumber- عدد جهات الاتصال المعادة في كل صفحة: عدد صحيح من 1 إلى 200، والافتراضي 50. وتُحوَّل القيمة تلقائيًا، فقيمة مثل `'100'` قادمة من سلسلة استعلام مقبولة، أما قيمة خارج المدى فترد 422 بدلًا من حصرها داخل المدى.
cursorstring- قيمة `nextCursor` من الصفحة السابقة. ولا تبنِ واحدة بنفسك أبدًا: فمؤشر يسمي جهة اتصال لم تعد موجودة يعطي 400 مع `invalid_cursor`، ما يعني أن حالة الترقيم لديك قديمة وأن عليك إعادة المرور من البداية دون cursor.
sourceContactSource- القيمة `'manual'` لجهات الاتصال التي حفظها شخص عن قصد، و`'auto'` لتلك التي سجّلها محرّر الرسائل في التطبيق. اتركها دون تحديد للحصول على الدفتر كاملًا.
الاستجابة: ContactResource
يعيد contacts.list كائن Page<ContactResource>، فتكون السجلات في page.items ويتبع المرور قيمة page.nextCursor ما دامت page.hasMore صحيحة. أما get وcreate وupdate فكل منها يعيد ContactDetailResource واحدًا، وهو السجل نفسه مضافًا إليه audiences. ودفتر العناوين غير محدود الحجم، ولهذا يعتمد هذا المسار الترقيم بدلًا من إعادة مصفوفة تتوقف عند 200 بصمت.
object'contact'- دائمًا السلسلة `contact`، في سجلات القائمة كما في `get`.
emailstring- العنوان، ويُحوَّل إلى أحرف صغيرة عند الكتابة فيصبح `[email protected]` و`[email protected]` جهة اتصال واحدة، وهو المفتاح الذي تأخذه كل دوال contacts، إذ لا يُكشف أي معرّف لجهة الاتصال. والسجلات ملك لمساحة العمل لا للعضو أو المفتاح الذي كتبها، فكل عضو وكل مفتاح في مساحة العمل يقرأ ويكتب في دفتر عناوين واحد.
namestring | null- الاسم المعروض. ويكون null عندما لا يكون قد سُجّل أي اسم لهذا العنوان قط. والكتابة التلقائية لا تحمل اسمًا إلا إذا وفّرت الترويسة شيئًا غير العنوان نفسه، ولا يمكنها أبدًا أن تطمس اسمًا كتبه المستخدم.
source'manual' | 'auto' | (string & {})- تعني `auto` أن السجل كُتب لأن المستخدم أرسل بريدًا إلى ذلك العنوان؛ وتعني `manual` أن شخصًا أدخله بنفسه، وهو ادعاء مختلف جوهريًا، ولا تُنزل عملية الإدراج والتحديث قيمة `manual` إلى `auto` أبدًا. ووصول بريد من عنوان لا يكتب أي سجل على الإطلاق، وهذا مقصود، فمن لم يفعل سوى مراسلتك ليس هنا؛ ويبقى الاتحاد مفتوحًا لأن العمود نص حر قيمته الافتراضية `manual`.
notesstring | null- نص حر كتبه شخص ما عن هذا الشخص، في التطبيق أو عبر `update`، ولا يُولَّد آليًا أبدًا. ويكون null عندما لا يكون أحد قد كتب شيئًا، وتمرير null صراحةً في `update` يمسحه.
lastSeenAtstring | null- بصيغة ISO-8601 بتوقيت UTC، ويُحدَّث في كل مرة يرسل فيها عضو إلى ذلك العنوان من محرّر الرسائل في التطبيق، لا عند وصول بريد منه، فذلك لا يكتب شيئًا. ويكون null لجهة اتصال حُفظت عبر `create` ولم تُراسَل قط، وتأتي هذه في الآخر في الترتيب التنازلي حسب `lastSeenAt` الذي يعيده هذا المسار.
audiencesArray<ContactAudienceResource>- يظهر في `get` و`create` و`update` فقط، ولا يظهر أبدًا في سجلات القائمة. ويضم كل جمهور تنتمي إليه جهة الاتصال بالشكل `{ id, name, builtin }`، بما في ذلك الجمهور الافتراضي. وتكون `builtin` بالقيمة `default` في الجمهور الذي تنتمي إليه كل جهة اتصال وnull في جمهور أنشأه شخص ما، لذا فرّع على هذا الحقل لا على الاسم الذي يستطيع أي أحد تغييره.