إدارة رسائل البريد الإلكتروني والمرفقات باستخدام Microsoft Graph

Aspose.Email IGraphClient توفر مجموعة واسعة من الطرق لإدارة رسائل البريد الإلكتروني ومرفقاتها عبر Microsoft Graph.

العمليات المتاحة:

قائمة الرسائل
تصفية وتصفح الرسائل بالصفحات
جلب محتوى الرسالة
إنشاء وإرسال الرسائل (بما في ذلك المسودات وملفات EML)
نسخ وتحريك الرسائل
إدارة المرفقات (إنشاء، جلب، حذف، قائمة)

List رسائل
Fetch رسالة
Create رسالة
إرسال رسالة
CopyMessage رسالة
نقل رسالة
CreateAttachment
FetchAttachment
DeleteAttachment
ListAttachments

قائمة الرسائل

لاسترجاع الرسائل من مجلد مثل "صندوق الوارد"، استخدم ListMessages طريقة.

استرجاع قائمة المجلدات باستخدام client.ListFolders().
التكرار عبر كل مجلد.
تحقق مما إذا كان اسم عرض المجلد هو "Inbox".
إذا كان كذلك، قم بإدراج الرسائل في البريد الوارد باستخدام client.ListMessages(folder.ItemId).
التكرار عبر كل رسالة في البريد الوارد.
اطبع موضوع كل رسالة إلى وحدة التحكم.

var folders = client.ListFolders();

foreach (var folder in folders)
{
    if (folder.DisplayName.Equals("Inbox"))
    {
        // list messages in inbox
        var inboxMessages = client.ListMessages(folder.ItemId);

        foreach (var messageInfo in inboxMessages)
        {
            Console.WriteLine(messageInfo.Subject);
        }
    }
}

قائمة الرسائل بشكل غير متزامن باستخدام Microsoft Graph

يوضح مثال الكود التالي كيفية الوصول إلى مجلد البريد الوارد، جلب صفحة من رسائل البريد الإلكتروني مع ListMessagesAsync، وطباعة عناوينها:

var folders = await client.ListFoldersAsync();
foreach (var folder in folders)
{
    Console.WriteLine(folder.DisplayName);
}

var folderId = folders.Find(x => x.DisplayName == "Inbox").ItemId;
var msgsPage = await client.ListMessagesAsync(folderId, new PageInfo(15) { PageOffset = 0 }, null);
var msgs = msgsPage.Items;
foreach (var msg in msgs)
{
    Console.WriteLine(msg.Subject);
}

تصفية الرسائل حسب تاريخ الإرسال

الـ OrderBy طريقة من مجموعة المكتبة تتيح لك استرجاع الرسائل بترتيب مختلف (تصاعدي وتنازلي) بناءً على تاريخ إرسالها. يظهر المثال البرمجي التالي كيفية ترتيب الرسائل حسب تاريخ الإرسال:

تهيئة عميل Graph
- إنشاء نسخة من IGraphClient باستخدام GraphClient.GetClient() مع الموفر وTenantId.
إنشاء مُنشئ استعلام
- إنشاء نسخة من GraphQueryBuilder الكائن.
ترتيب الرسائل حسب التاريخ في:

ترتيب تنازلي
- استخدام builder.SentDate.OrderBy(false) لتعيين الترتيب تنازليًا.
- استدعِ client.ListMessages() للحصول على رسائل من البريد الوارد بحد 10، باستخدام الاستعلام من builder.GetQuery().
- خزن الرسائل المسترجعة في المتغير messages.
ترتيب تصاعدي
- حدد الترتيب تصاعديًا عن طريق استدعاء builder.SentDate.OrderBy(true).
- استخدام client.ListMessages() مرة أخرى لاسترجاع الرسائل من البريد الوارد، الآن بترتيب تصاعدي.
- خزن هذه الرسائل في المتغير messages.

IGraphClient client = GraphClient.GetClient(provider, TenantId);

var builder = new GraphQueryBuilder();

// create orderby messages query 'DESC'
builder.SentDate.OrderBy(false);
var messagePageInfo = client.ListMessages(KnownFolders.Inbox, new PageInfo(10), builder.GetQuery());
var messages = messagePageInfo.Items;

builder.Clear();

// create orderby messages query 'ASC'
builder.SentDate.OrderBy(true);
messagePageInfo = client.ListMessages(KnownFolders.Inbox, new PageInfo(10), builder.GetQuery());
messages = messagePageInfo.Items;

قائمة الرسائل مع التجزئة والتصفية

استخدم التجزئة عند العمل مع صناديق بريد كبيرة. المثال أدناه يسترجع الرسائل غير المقروءة على دفعات من 10 ويعلمها كمقروءة بعد المعالجة:

ابدأ العميل.
حدد عدد العناصر لعرضها في كل صفحة، على سبيل المثال، 10.
إنشاء مرشح لاسترجاع الرسائل غير المقروءة فقط باستخدام GraphQueryBuilder الفئة. الـ builder.IsRead.Equals(false) يضبط الشرط لتصفية الرسائل غير المقروءة.
استدعِ الـ ListMessages طريقة على كائن العميل، تحدد المجلد (Inbox) وعدد العناصر لكل صفحة (PageInfo(itemsPerPage)) كمعاملات. كما تمرّر كائن الاستعلام لتطبيق مرشح الرسائل غير المقروءة. يحتوي كائن PageInfo المرتجع (pageInfo) على الرسائل المسترجعة للصفحة الحالية في الخاصية Items.
إنشاء حلقة تستمر حتى الوصول إلى الصفحة الأخيرة (pageInfo.LastPage هو false). تُضاف الرسائل المسترجعة إلى قائمة الرسائل الحالية باستخدام messages.AddRange(pageInfo.Items).

//  reading unread messages with paging
using var client = GraphClient.GetClient(tokenProvider, config.Tenant);

// paging option
var itemsPerPage = 10;
// create unread messages filter
GraphQueryBuilder builder = new GraphQueryBuilder();
builder.IsRead.Equals(false);
var query = builder.GetQuery();

// list messages
var pageInfo = client.ListMessages(KnownFolders.Inbox, new PageInfo(itemsPerPage), query);
var  messages = pageInfo.Items;

while (!pageInfo.LastPage)
{
    pageInfo = client.ListMessages(KnownFolders.Inbox, pageInfo.NextPage, query);
    messages.AddRange(pageInfo.Items);
}

// set messages state as read
foreach (var message in messages)
{
    client.SetRead(message.ItemId);
}

جلب رسالة

استرجاع المحتوى الكامل لرسالة محددة. يوضح مثال الكود التالي كيفية استرجاع وعرض أحدث رسالة في البريد الوارد للعرض أو المعالجة:

استدعِ client.ListFolders() لاسترجاع جميع المجلدات المتاحة في صندوق البريد وتخزينها في المتغير folders.
تكرار عبر كل مجلد في مجموعة المجلدات باستخدام حلقة foreach.
داخل الحلقة، تحقق مما إذا كان اسم عرض المجلد يساوي "Inbox".
إذا كان المجلد هو البريد الوارد، استرجع الرسائل باستخدام client.ListMessages() مع معرف المجلد ItemId.
تحقق مما إذا كانت هناك أي رسائل في البريد الوارد عن طريق التأكد من أن inboxMessages.Count أكبر من 0.
إذا كانت هناك رسائل، استرجع الرسالة الأولى باستخدام client.FetchMessage() مع المعرف ItemId للرسالة الأولى.
إخراج جسم HTML للرسالة المستخرجة.

var folders = client.ListFolders();

foreach (var folder in folders)
{
    if (folder.DisplayName.Equals("Inbox"))
    {
        // list messages in inbox
        var inboxMessages = client.ListMessages(folder.ItemId);

        if (inboxMessages.Count > 0)
        {
            // fetch the first message in inbox
            var msg = client.FetchMessage(inboxMessages[0].ItemId);
            
            Console.WriteLine(msg.BodyHtml);
        }
        
    }
}

استعلامات Microsoft Graph مع OData

توفر Aspose.Email for .NET دعم استعلامات OData لـ Microsoft Graph. يتيح ذلك للمطورين تطبيق تصفية متقدمة، وفرز، واختيار، وتجزئة، وتوسيع عند العمل مع موارد Graph مثل المجلدات، الرسائل، جهات الاتصال، عناصر التقويم، والمزيد. الـ Aspose.Email.Clients.Graph.ODataQueryBuilder تم بناء الفئة لإنشاء معلمات استعلام OData بطريقة منظمة بدلًا من بناء سلاسل الاستعلام يدويًا. بهذه الطريقة، يمكنك استرجاع الحقول الضرورية فقط (Select) للكفاءة، استخدم التصفية (Filter) والفرز (OrderBy) لتنظيم البيانات. يمكنك أيضًا تطبيق التجزئة (Top, Skip) لمجموعات البيانات الكبيرة، توسيع الكيانات المرتبطة (Expand) في طلب واحد، وتمكين العد والبحث نص كامل لسيناريوهات متقدمة.

فيما يلي قائمة بـ GraphClient طرق تدعم ** اختياريًاODataQueryBuilder** معلمة:**

ListFolders
ListMessages
ListContacts
ListCalendarItems
ListAttachments
ListCategories
ListOverrides
ListRules
ListTaskLists
ListTasks
ListNotebooks

يوضح مثال الكود التالي كيفية استخدام ODataQueryBuilder لقائمة المجلدات واسترجاع رسائل البريد الإلكتروني المفلترة والمرتبة والمقسمة من صندوق البريد:**

var accessParameters = Settings.User1;

var provider = new AzureConfidentialTokenProvider(
    accessParameters.TenantId,
    accessParameters.ClientId,
    accessParameters.ClientSecret);

var client = GraphClient.GetClient(provider, accessParameters.TenantId);

client.Resource = Aspose.Email.Clients.Graph.ResourceType.Users;
client.ResourceId = accessParameters.Username;
client.EndPoint = "https://graph.microsoft.com";

// Example 1: List folders ordered by name
var builder = new ODataQueryBuilder { OrderBy = "name asc" };
var folders = client.ListFolders(builder);

foreach (var folder in folders)
{
    Console.WriteLine(folder.DisplayName);
}

// Example 2: Retrieve filtered and paged messages from Inbox
var folderId = folders.Find(x => x.DisplayName == "Inbox").ItemId;

builder = new ODataQueryBuilder
{
    Filter = "startswith(name,'A')",
    OrderBy = "name asc",
    Top = 10,
    Skip = 5,
    Select = new[] { "name", "age" },
    Expand = new[] { "children", "parents" },
    Count = true,
    Search = "\"John Doe\"",
    Format = "json"
};

var msgs = client.ListMessages(folderId, builder);

foreach (var msg in msgs)
{
    Console.WriteLine(msg.Subject);
}

إنشاء رسالة

استخدم الـ CreateMessage طريقة لحفظ رسالة جديدة مباشرةً في مجلد محدد، مثل البريد الوارد. يوضح المثال التالي كيفية إنشاء MapiMessage وإضافتها إلى صندوق البريد.

var msg = new MapiMessage(OutlookMessageFormat.Unicode)
{
    Subject = "My message",
    Body = "Hi, it is my message"
};

msg.Recipients.Add("sam@to.com", "Sam", MapiRecipientType.MAPI_TO);

// create message in inbox
client.CreateMessage(KnownFolders.Inbox, msg);

إرسال الرسائل

الـ إرسال طريقة من IGraphClient يتيح لك إرسال رسالة بريد إلكتروني مباشرة باستخدام MapiMessage كائن. في هذا المثال، تم إنشاء رسالة بسيطة، وتكوينها بتفاصيل المرسل والمستلم، ثم إرساله.

// prepare the message
var msg = new MapiMessage(OutlookMessageFormat.Unicode)
{
    Subject = "My message",
    Body = "Hi, it is my message"
};

msg.Recipients.Add("sam@to.com", "Sam", MapiRecipientType.MAPI_TO);
msg.SetProperty(KnownPropertyList.SenderName, "John");
msg.SetProperty(KnownPropertyList.SentRepresentingEmailAddress, "John@from.com");

// send message
client.Send(msg);

إرسال رسالة مسودة

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

إنشاء MapiMessage مع الموضوع، والمحتوى، والمستلمين.
حدد تفاصيل المرسل باستخدام خصائص الرسالة.
احفظ الرسالة في مجلد المسودات باستخدام CreateMessage.
إرسال المسودة بتمرير معرف العنصر الخاص بها إلى الـ Send() طريقة.

// prepare the message
var msg = new MapiMessage(OutlookMessageFormat.Unicode)
{
    Subject = "My message",
    Body = "Hi, it is my message"
};

msg.Recipients.Add("sam@to.com", "Sam", MapiRecipientType.MAPI_TO);
msg.SetProperty(KnownPropertyList.SenderName, "John");
msg.SetProperty(KnownPropertyList.SentRepresentingEmailAddress, "John@from.com");

// add message to Draft folder
var draftMessage = client.CreateMessage(KnownFolders.Drafts, msg);

// send a draft message
client.Send(draftMessage.ItemId);

إرسال رسالة EML

استخدم الـ MailMessage فئة لإنشاء وإرسال رسائل بصيغة EML. يوضح مثال الكود التالي كيفية إنشاء وإرسال رسالة بريد إلكتروني باستخدام Graph API:

// prepare the message
var eml = new MailMessage
{
    From = "from@domain.com",
    To = "to1@domain.com, to2@domain.com",
    Subject = "New message",
    HtmlBody = "<html><body>This is the HTML body</body></html>"
};

// send the message
graphClient.Send(eml);
graphClient.Create(KnownFolders.Inbox, eml);

نسخ الرسائل

لإنشاء نسخة مكررة من رسالة بريد إلكتروني موجودة، استخدم الـ CopyMessage طريقة الـ IGraphClient الواجهة.


// copy message to Inbox folder
var copiedMsg = client.CopyMessage(KnownFolders.Inbox, msg.ItemId);

نقل الرسائل

لنقل رسالة بريد إلكتروني موجودة من موقعها الحالي إلى مجلد جديد، استخدم الـ MoveMessage طريقة الـ IGraphClient الواجهة.

// move message to Inbox folder
var movedMsg = client.MoveMessage(KnownFolders.Inbox, msg.ItemId);

إدارة المرفقات

الـ IGraphClient في Aspose.Email for .NET يتيح لك العمل مع مرفقات البريد الإلكتروني برمجيًا. يشمل ذلك إنشاء، استرجاع، حذف، وإدراج المرفقات المرتبطة برسالة. يوضح مثال الكود التالي إدارة دورة حياة المرفق بالكامل لرسائل Outlook عبر Microsoft Graph API باستخدام Aspose.Email. يمكنك تخصيص محتوى المرفق والبيانات الوصفية حسب الحاجة.


// create an attachment
var attachment = new MapiAttachment();
attachment.SetProperty(KnownPropertyList.DisplayName, "My Attachment");
attachment.SetProperty(KnownPropertyList.AttachDataBinary, new byte[1024]);

// add an attachment to message
var createdAttachment = client.CreateAttachment(messageInfo.ItemId, attachment);

// fetch a message attachment
var fetchedAttachment = client.FetchAttachment(createdAttachment.ItemId);

// delete a message attachment 
client.DeleteAttachment(createdAttachment.ItemId);

// list the message attachments
var attachments = client.ListAttachments(messageInfo.ItemId);

إدارة مجلدات البريد في Microsoft Graph (Aspose.Email) إدارة عناصر Outlook عبر عميل Aspose.Email Graph