Открыть сервис
Главная → Блог → MAPISendMail

MAPISendMail

MAPISendMail — это функция Windows API (Application Programming Interface), предназначенная для отправки электронных писем с использованием почтовой подсистемы MAPI (Messaging Application Programming Interface). Функция является частью библиотеки Simple MAPI и позволяет приложениям инициировать отправку сообщения, вызывая стандартный почтовый клиент, установленный в операционной системе, без необходимости реализации собственного протокола передачи почты.

История и происхождение

MAPI была разработана корпорацией Microsoft в начале 1990-х годов как часть стратегии по созданию универсального интерфейса для обмена сообщениями в операционных системах Windows. Simple MAPI, частью которой является функция MAPISendMail, представляет собой упрощённый набор из 12 функций, предназначенных для выполнения базовых операций с электронной почтой: отправки, чтения и администрирования почтовых ящиков.

Функция MAPISendMail впервые появилась в Windows 95 и Microsoft Exchange Client. В последующих версиях Windows, включая Windows 2000, XP, Vista, 7, 8, 10 и 11, она оставалась доступной для обратной совместимости. Несмотря на появление более современных технологий (например, MAPI Extended, Collaboration Data Objects), MAPISendMail продолжает использоваться в унаследованных приложениях и скриптах.

Техническое описание

Прототип функции

Функция объявлена в заголовочном файле mapi.h и экспортируется из библиотеки mapi32.dll. Прототип на языке C выглядит следующим образом:

``c ULONG FAR PASCAL MAPISendMail( LHANDLE lhSession, ULONG ulUIParam, lpMapiMessage lpMessage, FLAGS flFlags, ULONG ulReserved ); ``

Параметры

  • lhSession — дескриптор сеанса MAPI, полученный при вызове MAPILogon. Если сеанс не требуется, может быть равен 0.
  • ulUIParam — дескриптор родительского окна для отображения диалоговых окон (например, окна выбора профиля или ошибки).
  • lpMessage — указатель на структуру MapiMessage, содержащую данные отправляемого письма.
  • flFlags — флаги, управляющие поведением функции:
  • MAPI_DIALOG — отобразить диалоговое окно почтового клиента перед отправкой.
  • MAPI_LOGON_UI — при необходимости отобразить окно входа в почтовую систему.
  • MAPI_NEW_SESSION — создать новый сеанс MAPI, даже если существующий активен.
  • MAPI_FORCE_DOWNLOAD — принудительно загрузить все новые сообщения перед отправкой.
  • ulReserved — зарезервированный параметр, должен быть равен 0.

Структура MapiMessage

Структура MapiMessage содержит основную информацию о письме:

  • ulReserved — зарезервировано.
  • lpszSubject — тема письма (строка с завершающим нулём).
  • lpszNoteText — тело письма (текст).
  • lpszMessageType — тип сообщения (обычно NULL).
  • lpszDateReceived — дата получения (не используется при отправке).
  • lpszConversationID — идентификатор обсуждения (необязательно).
  • flFlags — флаги сообщения (например, MAPI_SENT).
  • lpOriginator — указатель на структуру MapiRecipDesc с данными отправителя (заполняется системой).
  • nRecipCount — количество получателей.
  • lpRecips — массив структур MapiRecipDesc с данными получателей.
  • nFileCount — количество вложений.
  • lpFiles — массив структур MapiFileDesc с описаниями вложений.

Возвращаемые значения

Функция возвращает один из кодов:

  • SUCCESS_SUCCESS (0) — письмо успешно отправлено.
  • MAPI_E_USER_ABORT — пользователь прервал операцию.
  • MAPI_E_FAILURE — общая ошибка.
  • MAPI_E_INSUFFICIENT_MEMORY — недостаточно памяти.
  • MAPI_E_LOGON_FAILURE — ошибка входа.
  • MAPI_E_TOO_MANY_FILES — превышено количество вложений.
  • MAPI_E_TOO_MANY_RECIPIENTS — превышено количество получателей.
  • MAPI_E_ATTACHMENT_NOT_FOUND — файл вложения не найден.
  • MAPI_E_ATTACHMENT_OPEN_FAILURE — не удалось открыть файл вложения.
  • MAPI_E_DISK_FULL — на диске недостаточно места.

Применение

Отправка писем из приложений

MAPISendMail используется в различных приложениях для отправки электронных писем без реализации собственного SMTP-клиента. Типичные сценарии:

  • Отправка отчётов об ошибках из программ.
  • Рассылка уведомлений и напоминаний.
  • Отправка документов из офисных приложений (например, Microsoft Excel или Word).
  • Интеграция с системами документооборота.

Пример использования на C++

Ниже приведён упрощённый пример вызова MAPISendMail для отправки письма одному получателю:

```cpp

include <windows.h>

include <mapi.h>

include <tchar.h>

void SendMailExample() { MapiMessage msg = {0}; MapiRecipDesc recip = {0};

// Настройка получателя recip.ulRecipClass = MAPI_TO; recip.lpszName = _T("Иванов Иван"); recip.lpszAddress = _T("SMTP:ivanov@example.com");

msg.lpszSubject = _T("Тестовое письмо"); msg.lpszNoteText = _T("Это тестовое сообщение, отправленное через MAPISendMail."); msg.nRecipCount = 1; msg.lpRecips = &recip;

ULONG result = MAPISendMail(0, 0, &msg, MAPI_DIALOG, 0); if (result == SUCCESS_SUCCESS) { // Письмо отправлено } } ```

Использование в скриптах

MAPISendMail может вызываться из скриптовых языков (например, VBScript, PowerShell) через COM-объекты или напрямую через вызовы Win32 API. В VBScript типичный подход — использование объекта CDO.Message с MAPI-транспортом, однако прямой вызов MAPISendMail через CreateObject("MAPI.Session") также возможен.

Ограничения и особенности

  • Зависимость от почтового клиента: MAPISendMail не отправляет письма напрямую через SMTP. Она делегирует задачу почтовому клиенту, установленному по умолчанию (например, Microsoft Outlook, Mozilla Thunderbird, The Bat!). Если клиент не настроен или отсутствует, функция вернёт ошибку.
  • Ограничения Simple MAPI: функция не поддерживает расширенные возможности, такие как шифрование, цифровые подписи, форматированный HTML-текст (только plain text) или работа с несколькими почтовыми ящиками.
  • Потокобезопасность: MAPISendMail не является потокобезопасной. Вызов из нескольких потоков одновременно может привести к непредсказуемому поведению.
  • Поддержка в современных Windows: функция устарела, но сохраняется для обратной совместимости. Корпорация Microsoft рекомендует использовать более современные API, такие как MAPI Extended или Graph API.
  • Проблемы с длинными именами файлов: в некоторых версиях Windows вложения с длинными именами могут обрабатываться некорректно.

Критика и альтернативы

Критика

Основные недостатки MAPISendMail связаны с её архитектурными ограничениями:

  • Отсутствие контроля над процессом отправки (приложение не может узнать, было ли письмо действительно доставлено).
  • Зависимость от стороннего ПО (почтового клиента), что снижает надёжность.
  • Невозможность отправки писем в фоновом режиме без отображения диалоговых окон.
  • Отсутствие поддержки современных стандартов (HTML, вложения с кириллическими именами, кодировки).

Альтернативы

Для замены MAPISendMail в современных приложениях используются:

  • MAPI Extended (Extended MAPI) — более мощный интерфейс, доступный через COM-объекты (например, IMAPISession, IMessage). Требует установленного почтового клиента.
  • CDO (Collaboration Data Objects) — библиотека для работы с сообщениями, поддерживающая как MAPI, так и SMTP.
  • SMTP-клиенты — прямые реализации протокола SMTP (например, System.Net.Mail.SmtpClient в .NET, smtplib в Python). Не требуют установленного почтового клиента.
  • Graph API — облачный API Microsoft для работы с почтой Exchange Online.
  • Web-сервисы — REST API почтовых сервисов (Gmail API, Яндекс.Почта API).

Интересные факты

  • MAPISendMail является одной из немногих функций Windows API, которая не требует явного вызова MAPILogon для отправки письма (если передать lhSession = 0). В этом случае система автоматически создаёт временный сеанс.
  • Функция может быть использована для отправки писем без отображения пользовательского интерфейса, если не указан флаг MAPI_DIALOG. Однако это не гарантирует отсутствие диалогов, так как почтовый клиент может всё равно запросить подтверждение.
  • В некоторых версиях Windows (например, Windows 10) MAPISendMail может работать некорректно с почтовыми клиентами, установленными из Microsoft Store (например, «Почта Windows»), из-за различий в архитектуре MAPI.

Источники

  1. Microsoft Docs. «MAPISendMail function (MAPI.h)» — документация Windows SDK.
  2. Microsoft Docs. «Simple MAPI» — обзор интерфейса Simple MAPI.
  3. Книга: «Programming Windows» by Charles Petzold (раздел, посвящённый MAPI).
  4. MSDN Magazine. «Using Simple MAPI to Send Mail from Your Application» (статья, 1998 г.).
  5. Документация Microsoft по MAPI Extended (Exchange Server SDK).

BFOmetr — база данных и аналитика по компаниям России.

На главную BFOmetr →

Похожие материалы