تخطَّ إلى المستندات
SDK

إرسال رسالة

`emails.send`: رسالة واحدة، الآن أو لاحقًا.

emails.send

send-email.ts
const email = await openemail.emails.send({  from: { email: '[email protected]', name: 'Acme Billing' },  to: ['[email protected]', 'Grace <[email protected]>'],  cc: '[email protected]',  bcc: [{ email: '[email protected]' }],  replyTo: '[email protected]',  subject: 'Your September invoice',  html: '<p>Invoice attached.</p>',  text: 'Invoice attached.',  headers: { 'X-Campaign': 'invoices' },  attachments: [{ filename: 'invoice.pdf', content: pdfBytes }],  threadId: 'thread_…',  scheduledAt: 'PT1H',  tags: { order: '4021' },  tracking: { opens: true, clicks: true },})

تأخذ to وcc وbcc مستلمًا واحدًا أو عدة مستلمين، والمستلم المفرد يُلفّ لك. وقد يكون كل منهم عنوانًا مجردًا أو بالشكل Name <addr@host> أو { email, name }.

المعاملات

fromRecipientInputمطلوب
المُرسِل. عنوان مجرّد، أو `Name <addr@host>`، أو كائن. ويجب أن يكون أحد العناوين التي يجوز لهذا المفتاح الإرسال باسمها. ولا يوجد مُرسِل احتياطي، لأن الاحتياطي سيكون العنوان الافتراضي لمساحة العمل، وهو يتغيّر كلما جاءت عناوين وذهبت أخرى.
toRecipientInput | RecipientInput[]مطلوب
مستلم واحد أو عدة؛ والمفرد يُلفّ لك. وبحد أقصى 50 عبر to وcc وbcc مجتمعة.
ccRecipientInput | RecipientInput[]
تُحسب ضمن حد الخمسين مستلمًا.
bccRecipientInput | RecipientInput[]
لا يُسمّى أبدًا في البايتات التي يتلقاها أي شخص آخر، لأن مُغلَّفًا واحدًا يُبثّ لكل مستلم.
replyToRecipientInput
عنوان واحد، يُرسل كترويسة Reply-To.
subjectstring
بحد أقصى 998 حرفًا، وهو حد السطر في RFC 5322. والافتراضي فارغ.
htmlstring
يلزم واحد من html أو text أو draftId أو template. وHTML هو ما يراه المستلمون عندما يُعطى html وtext معًا.
textstring
جزء النص العادي.
template{ id, version?, props?, slots? }
اعرض قالبًا مخزَّنًا على الخادم. و`version` تثبّت المراجعة؛ احذفها لاستخدام ما يكون منشورًا عند قبول الطلب. وخاصية مجهولة أو ناقصة ترد 422 بدل فراغ في الرسالة.
draftIdstring
أرسل مسودة محفوظة تحت هذا المُغلَّف.
headersRecord<string, string>
`X-*` و`List-*` وReply-To وPrecedence وAuto-Submitted وImportance وPriority وFeedback-Id. وأي ترويسة يضبطها النقل بنفسه تُرفض بدل أن تُسقط بصمت.
attachmentsAttachmentInput[]
`{ filename, content, contentType? }`، أو `{ fileId }` يسمي ملفًا موجودًا بالفعل في مساحة العمل. مرّر بايتات في content وتُرمَّز لك بترميز base64. 20 ملفًا، بحد أقصى 5 ميغابايت للملفات المضمّنة مجتمعة بعد فك الترميز. والملف المخزَّن يجوز أن يكون أكبر ويسافر كرابط تنزيل.
attachmentDeliveryAttachmentDeliveryMode
`mime` أو `link` أو `auto`. تحمل `auto` الملفات كروابط تنزيل متى تجاوزت 2 ميغابايت على نطاق له نطاق ملفات نشط، وداخل الرسالة فيما عدا ذلك. وإذا تُركت، طُبّق إعداد صندوق البريد، وهو `auto` افتراضيًا.
threadIdstring
الرد داخل محادثة قائمة. ويكتب النقل ترويستي In-Reply-To وReferences.
scheduledAtDate | string
كائن Date أو لحظة بصيغة ISO-8601 أو مدة مثل `PT1H`. حتى سنة من الآن، ولا تكون في الماضي أبدًا. ولا يمكن الجمع بينها وبين cancellableForSeconds.
cancellableForSecondsnumber
من 0 إلى 900. نافذة تراجع على إرسال فوري: آلية التراجع في محرّر الرسائل، مكشوفة بدل أن تكون مثبتة في الشيفرة.
tagsRecord<string, string>
حتى 10 وسوم، تُعاد كما هي وقابلة للترشيح. ولا تُفسَّر أبدًا.
signatureboolean
ما إذا كانت هذه الرسالة تحمل توقيع العنوان المرسَلة منه، وهو توقيع ذلك العنوان نفسه أو التوقيع المضبوط لـ All addresses. الافتراضي true، لأن التوقيع يخص العنوان لا العميل الذي أرسل الرسالة أيًّا كان. اضبطها على `false` للبريد الذي يرسله برنامج نيابةً عن شخص، مثل إيصال أو إعادة تعيين كلمة مرور أو ملخص دوري، فلا شيء من ذلك يريد توقيع شخص تحته.
tracking{ opens?, clicks? }
ما إذا كان سيُضاف بكسل فتح وتُعاد كتابة الروابط لهذه الرسالة. مفعّل ما لم يكن مالك مساحة العمل قد أوقف التتبع للعنوان المرسَلة منه أو لـ All addresses، وأي من الحقلين المذكور هنا يحسم تلك الرسالة الواحدة أيًّا كان ضبط العنوان.
translate{ to, from?, subject?, includeOriginal? }
أرسلها بلغة المستلم. تأخذ `to` رمزًا أو اسمًا إنجليزيًا أو اسم اللغة بلغتها؛ و`subject` و`includeOriginal` كلاهما true افتراضيًا. ويُحل ذلك عند قبول الطلب، فالرسالة المجدولة تحمل الكلمات التي اعتُمدت. ويُرفض مع `draftId`.

الاستجابة

idstring
معرّف الإرسال، `msg_…`. استخدمه مع `get` و`cancel` و`reschedule` و`getTracking`.
statusEmailStatus
queued أو scheduled أو sending أو sent أو partial أو cancelled أو failed. اقرأ هذا بدل الاكتفاء بأن الوعد قد حُل. و`partial` حالة قائمة بذاتها: فبعض المستلمين لديهم الرسالة ولا يمكن سحبها منهم، ومن ثَم فإعادة المحاولة خطأ والإبلاغ عن فشل كذب.
mode'live' | 'test'
أي نوع من المفاتيح أرسلها. والإرسال في وضع الاختبار يُسجَّل ولا يُبثّ أبدًا.
fromstring
العنوان الذي أُذن به فعلًا ووُضع على الشبكة، وهو ليس دائمًا العنوان المطلوب.
subjectstring | null
كما أُرسل.
messageIdstring | null
ترويسة Message-ID بحسب RFC 5322. تكون null إلى أن توجد رسالة MIME. وتعيد خدمة الإرسال كتابة الترويسة عند الخروج، فلا يحمل أي ارتداد أو تقرير تسليم هذه القيمة. و`id` هو ما يعود به أي حدث.
threadIdstring | null
المحادثة التي حطّت فيها.
transportstring | null
كيف خرجت الرسالة. تكون null حتى الإرسال.
attemptsnumber
كم مرة جُرّب الإرسال.
lastErrorstring | null
لماذا فشلت المحاولة الأخيرة، حرفيًا.
scheduledAtstring | null
اللحظة بصيغة ISO التي يُتوقع أن تنطلق فيها.
cancellableUntilstring | null
ما دام الآن قبل هذه اللحظة، فالإلغاء ما زال يعمل.
sentAtstring | null
اللحظة بصيغة ISO التي انطلقت فيها.
tagsRecord<string, string>
ما أرسلته، معادًا كما هو.
sourceEmailSource
composer أو api أو mcp أو ai أو queue: أي واجهة طلبت الإرسال. و`api` هو هذا العميل.
createdAtstring
اللحظة بصيغة ISO التي كُتب فيها السجل.
replayedboolean
صحيحة عندما يطابق `Idempotency-Key` عملية إرسال موجودة أصلًا. فلا شيء جديد أُرسل، وهذه هي الرسالة الأصلية.
translationEmailTranslationResource | undefined
يظهر فقط على رسالة تُرجمت، وفقط حيث يُحمل الطلب المخزَّن كاملًا: أي هذه الاستجابة و`get`. وهو `{ language, languageName, detectedSourceLanguage, subject, includeOriginal }`، كلها رموز لا سجلات لغات. وسجل القائمة لا يحمله أبدًا، فغيابه هناك لا يقول شيئًا في أي اتجاه.

بلغة المستلم

يكتب translate الرسالة بلغة شخص آخر قبل أن تنطلق. فالجسم، والموضوع ما لم توقف ذلك، يُترجمان عند قبول واجهة API للطلب، وما خرج هو ما يُرسل: فترجمة تعذّر إنتاجها ترفض الإرسال بدل أن تنشره باللغة التي كتبته بها.

translate.ts
const email = await openemail.emails.send({  from: '[email protected]',  to: '[email protected]',  subject: 'Your September invoice',  html: '<p>Invoice attached. Payment is due on the 14th.</p>',  translate: { to: 'de' },}) console.log(email.translation)// { language: 'de', languageName: 'German', detectedSourceLanguage: 'en', subject: true, includeOriginal: true }

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

preview-translation.ts
const preview = await openemail.emails.translate({  subject: 'Your September invoice',  html: '<p>Invoice attached. Payment is due on the 14th.</p>',  to: 'de',}) console.log(preview.language.native, preview.detectedSourceLanguage) const approved = await showToSomebody(preview) await openemail.emails.send({  from: '[email protected]',  to: '[email protected]',  subject: approved.subject,  html: approved.html,})
render-picker.ts
import { LANGUAGES, isRtlLanguage, languageByCode, openemail, resolveLanguage } from '@openemail/sdk' LANGUAGES.length // 200 const current = await openemail.languages.list() resolveLanguage('Deutsch')?.code // 'de'resolveLanguage('zh-TW')?.code // 'zh-Hant'languageByCode('DE')?.native // 'Deutsch'isRtlLanguage('ar') // true

الجدول مضمّن في الحزمة، بترتيب المنتقي، فيمكن ملء منتقٍ قبل أول طلب. وlanguages.list() يعيد السجلات نفسها من الشبكة كمصفوفة عادية، لمن يفضّل السجلات الحالية على تلك التي شُحنت مع هذا الإصدار. ويأخذ resolveLanguage رمزًا أو اسمًا إنجليزيًا أو اسمًا محليًا أو اسمًا بديلًا (فـ zh-TW اسم بديل لرمز لم يعد مدرجًا)، ويطابق languageByCode رمزًا تامًا دون حساسية لحالة الأحرف، وستة عشر من السجلات لغات تُكتب من اليمين إلى اليسار. ابحث في native وlabel وcode معًا، واعرض native أولًا، واحفظ الرمز.

لا يُعاد استدعاء emails.translate تلقائيًا. فهو ينفق استدعاءات للنموذج ولا يكتب شيئًا، فلا شيء هناك لجعله عديم أثر التكرار، وإعادة المحاولة بعد طلب بلا إجابة لن تشتري سوى الإجابة نفسها مرتين.

  • لغة لا تُحلّ إلى شيء تعطي validation_error على translate.to، قبل إرسال أي شيء.
  • translation_too_long فوق 30,000 حرف، وtranslation_not_configured عندما لا يكون في التثبيت أي إعداد للذكاء الاصطناعي، وtranslation_failed عندما لا يجيب المزوّد. ولا يرسل أي منها الرسالة دون ترجمة كحل بديل.
  • يعمل مع template: فالمخرَج المعروض هو ما يُترجم، فيخدم جسم مخزَّن واحد كل لغة يقرأ بها عملاؤك. والقالب الذي يعرض مستندًا كاملًا يحتفظ بـ doctype وكتل <style> وقواعد @font-face الخاصة به: إذ لا يذهب إلى النموذج سوى الجسم ويُعاد الباقي حوله. ويُترك <title> كما هو، وهو ما لا يعرضه شيء على أي حال.
  • إعادة المحاولة لا تكلّف شيئًا إضافيًا. فالترجمة ليست جزءًا من بصمة منع التكرار (الطلب هو الجزء، بما فيه translate)، لذا فإن إعادة إرسال طلب بلا إجابة بالـ Idempotency-Key نفسه تعيد تشغيل الرسالة الموجودة أصلًا بدل أن تترجم وترسل ثانية.
  • الرسالة المترجمة التي تكون في الطابور أو مجدولة مجمّدة ضد تغيير الصياغة. وemails.reschedule ما زال ينقلها؛ أما تغيير ما تقوله فيعني الإلغاء وإعادة الإرسال.

المرفقات

الحقل content يُرسل بترميز base64 على الشبكة. مرّر بايتات وتُرمَّز لك.

attachment.ts
attachments: [  { filename: 'invoice.pdf', content: pdfBytes, contentType: 'application/pdf' },]

الدالة toBase64 مُصدَّرة إن احتجتها في مكان آخر. وهي تعمل على دفعات، وهو ما لا يفعله btoa(String.fromCharCode(...bytes)). فذاك يفشل مع أي شيء يتجاوز نحو 100 كيلوبايت، ويفشل مع الملف الحقيقي لا مع الملف الذي اختبرت به.