Управление электронными письмами и вложениями с помощью Microsoft Graph

Aspose.Email IGraphClient предоставляет широкий набор методов для управления электронными сообщениями и их вложениями через Microsoft Graph.

Доступные операции:

Список сообщений
Фильтровать и постранично просматривать сообщения
Получить содержимое сообщения
Создавать и отправлять сообщения (включая черновики и EML)
Копировать и перемещать сообщения
Управление вложениями (создание, получение, удаление, список)

Список сообщений

Чтобы получить сообщения из папки, например "Inbox", используйте 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 Client
- Создайте экземпляр IGraphClient используя GraphClient.GetClient() с провайдером и TenantId.
Create Query Builder
- Создать экземпляр 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 класс. The 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.
Отправьте черновик, передав его ItemId в 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 Client