Learning Objectives

In this tutorial, you’ll learn how to:

Work with Microsoft Outlook Email format (MSG files) and MAPI properties
Create, modify, and access MAPI messages, calendars, and contacts
Convert between MAPI objects and standard Dto objects
Save MAPI files to cloud storage and retrieve them
Access and modify specific MAPI properties
Implement MAPI operations in multiple programming languages

Prerequisites

Before starting this tutorial, make sure you have:

An Aspose Cloud account (sign up at dashboard.aspose.cloud)
Your Aspose Cloud credentials (Client ID and Client Secret)
The Aspose.Email Cloud SDK for your preferred programming language installed
Basic understanding of email formats and MAPI properties
Familiarity with Microsoft Outlook concepts

Introduction to MAPI Message Files

MAPI (Messaging Application Programming Interface) is Microsoft’s proprietary messaging architecture used primarily by Microsoft Outlook. MSG files are Microsoft Outlook’s email message format that store emails, appointments, contacts, tasks, and other items using the MAPI structure.

Aspose.Email Cloud provides comprehensive support for MSG files through its MAPI Message Files API, allowing you to:

Work directly with MSG files without requiring Microsoft Outlook
Access and modify individual MAPI properties
Convert between MAPI objects and standard formats (EML, ICS, VCF)
Create rich email messages, appointments, and contacts with all Outlook features

The API offers three main models for working with MAPI:

MapiMessageDto - Represents an email message
MapiCalendarDto - Represents an appointment or meeting object
MapiContactDto - Represents a contact

Each of these models can be converted to and from their corresponding standard models:

MapiMessageDto ↔ EmailDto
MapiCalendarDto ↔ CalendarDto
MapiContactDto ↔ ContactDto

Tutorial Steps

Step 1: Set Up Your Development Environment

First, ensure you have the Aspose.Email Cloud SDK installed for your preferred programming language. If you haven’t done this yet, refer to our SDK Setup Tutorial.

Step 2: Initialize the API Client

Create and configure the API client with your credentials:

# Python example
import os
from asposeemail.api_client import ApiClient
from asposeemail.api.email_cloud import EmailCloud
from asposeemail.configuration import Configuration

# Configure API key authorization
configuration = Configuration(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET"
)

# Create API client
api = EmailCloud(configuration)

Step 3: Working with MAPI Messages (Email)

Let’s start by creating, modifying, and converting a MAPI message:

# Python
from asposeemail.models import (
    MapiMessageDto, MapiRecipientDto, MapiAttachmentDto,
    StorageFileLocation, MapiMessageSaveRequest,
    MapiMessageGetRequest, MapiMessageFromFileRequest,
    MapiMessageAsFileRequest
)
import base64

# Create a MAPI message
mapi_message = MapiMessageDto(
    # Message properties
    subject="MAPI Message Example",
    body="This is the body of a MAPI message.",
    body_type="PlainText",
    client_submit_time=datetime.now(),
    delivery_time=datetime.now(),
    display_to="Recipient Name",
    flags=["MsgFlagRead", "MsgFlagUnsent", "MsgFlagHasAttach"],
    message_class="IPM.Note",
    message_format="Ascii",
    normalized_subject="MAPI Message Example",
    
    # Sender information
    sender_address_type="SMTP",
    sender_email_address="sender@example.com",
    sender_name="Sender Name",
    sender_smtp_address="sender@example.com",
    
    # Add recipients
    recipients=[
        MapiRecipientDto(
            address_type="SMTP",
            display_name="Recipient Name",
            email_address="recipient@example.com",
            recipient_type="MapiTo"
        ),
        MapiRecipientDto(
            address_type="SMTP",
            display_name="CC Recipient",
            email_address="cc@example.com",
            recipient_type="MapiCc"
        )
    ],
    
    # Add an attachment
    attachments=[
        MapiAttachmentDto(
            data_base64=base64.b64encode("This is attachment content".encode('utf-8')).decode('utf-8'),
            name="sample-attachment.txt"
        )
    ]
)

# Convert MAPI message to MSG file
msg_file = api.mapi.message.as_file(
    MapiMessageAsFileRequest("Msg", mapi_message)
)

print(f"MAPI message converted to MSG format, size: {len(msg_file)} bytes")

# Save the file locally for examination
with open("mapi_message_example.msg", "wb") as f:
    f.write(msg_file)
print("MSG file saved locally as 'mapi_message_example.msg'")

# Save MAPI message to cloud storage
storage = "First Storage"
folder = "mapi_examples"
file_name = "example_message.msg"

api.mapi.message.save(
    MapiMessageSaveRequest(
        storage_file=StorageFileLocation(storage, folder, file_name),
        value=mapi_message,
        format="Msg"
    )
)
print(f"MAPI message saved to storage as {file_name}")

# Retrieve MAPI message from storage
retrieved_message = api.mapi.message.get(
    MapiMessageGetRequest(
        format="Msg",
        file_name=file_name,
        folder=folder,
        storage=storage
    )
)
print("Retrieved MAPI message from storage")
print(f"Subject: {retrieved_message.subject}")
print(f"From: {retrieved_message.sender_name} <{retrieved_message.sender_email_address}>")

Let’s see how to do this in other programming languages:

C# Example

using System;
using System.IO;
using System.Text;
using System.Collections.Generic;
using System.Threading.Tasks;
using Aspose.Email.Cloud.Sdk.Api;
using Aspose.Email.Cloud.Sdk.Model;

// Initialize API client
var api = new EmailCloud("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

// Create a MAPI message
var mapiMessage = new MapiMessageDto
{
    Subject = "MAPI Message Example",
    Body = "This is the body of a MAPI message.",
    BodyType = "PlainText",
    ClientSubmitTime = DateTime.Now,
    DeliveryTime = DateTime.Now,
    DisplayTo = "Recipient Name",
    Flags = new List<string> {"MsgFlagRead", "MsgFlagUnsent", "MsgFlagHasAttach"},
    MessageClass = "IPM.Note",
    MessageFormat = "Ascii",
    NormalizedSubject = "MAPI Message Example",
    
    // Sender information
    SenderAddressType = "SMTP",
    SenderEmailAddress = "sender@example.com",
    SenderName = "Sender Name",
    SenderSmtpAddress = "sender@example.com",
    
    // Add recipients
    Recipients = new List<MapiRecipientDto>
    {
        new MapiRecipientDto
        {
            AddressType = "SMTP",
            DisplayName = "Recipient Name",
            EmailAddress = "recipient@example.com",
            RecipientType = "MapiTo"
        },
        new MapiRecipientDto
        {
            AddressType = "SMTP",
            DisplayName = "CC Recipient",
            EmailAddress = "cc@example.com",
            RecipientType = "MapiCc"
        }
    },
    
    // Add an attachment
    Attachments = new List<MapiAttachmentDto>
    {
        new MapiAttachmentDto
        {
            DataBase64 = Convert.ToBase64String(Encoding.UTF8.GetBytes("This is attachment content")),
            Name = "sample-attachment.txt"
        }
    }
};

// Convert MAPI message to MSG file
var msgStream = await api.Mapi.Message.AsFileAsync(
    new MapiMessageAsFileRequest("Msg", mapiMessage));

Console.WriteLine("MAPI message converted to MSG format");

// Save the file locally for examination
using (var fileStream = File.Create("mapi_message_example.msg"))
{
    await msgStream.CopyToAsync(fileStream);
}
Console.WriteLine("MSG file saved locally as 'mapi_message_example.msg'");

// Save MAPI message to cloud storage
var storage = "First Storage";
var folder = "mapi_examples";
var fileName = "example_message.msg";

await api.Mapi.Message.SaveAsync(
    new MapiMessageSaveRequest(
        new StorageFileLocation(storage, folder, fileName),
        mapiMessage, "Msg"));

Console.WriteLine($"MAPI message saved to storage as {fileName}");

// Retrieve MAPI message from storage
var retrievedMessage = await api.Mapi.Message.GetAsync(
    new MapiMessageGetRequest("Msg", fileName, folder, storage));

Console.WriteLine("Retrieved MAPI message from storage");
Console.WriteLine($"Subject: {retrievedMessage.Subject}");
Console.WriteLine($"From: {retrievedMessage.SenderName} <{retrievedMessage.SenderEmailAddress}>");

Step 4: Converting Between MAPI Message and EmailDto

One of the key features is the ability to convert between MAPI message and standard email formats:

# Python
from asposeemail.models import EmailDto, MailAddress, Attachment

# Create a standard EmailDto object
email = EmailDto(
    _from=MailAddress("Sender Name", "sender@example.com"),
    to=[MailAddress("Recipient Name", "recipient@example.com")],
    subject="Standard Email Example",
    body="This is a standard email that we'll convert to MAPI format.",
    is_body_html=False,
    attachments=[
        Attachment(
            base64_data=base64.b64encode("Attachment content".encode('utf-8')).decode('utf-8'),
            name="example.txt"
        )
    ]
)

# Convert EmailDto to MapiMessageDto
mapi_from_email = api.email.as_mapi(email)
print("Converted standard email to MAPI format")
print(f"MAPI subject: {mapi_from_email.subject}")
print(f"MAPI sender: {mapi_from_email.sender_name} <{mapi_from_email.sender_email_address}>")

# Convert MapiMessageDto back to EmailDto
email_from_mapi = api.mapi.message.as_email_dto(mapi_message)
print("\nConverted MAPI message back to standard email format")
print(f"Email subject: {email_from_mapi.subject}")
print(f"Email from: {email_from_mapi.from_.display_name} <{email_from_mapi.from_.address}>")
print(f"Email to: {email_from_mapi.to[0].display_name} <{email_from_mapi.to[0].address}>")

Java Example

import com.aspose.email.cloud.sdk.api.EmailCloud;
import com.aspose.email.cloud.sdk.model.*;
import java.util.Arrays;
import java.util.Base64;

// Create a standard EmailDto object
EmailDto email = new EmailDto()
    .from(new MailAddress("Sender Name", "sender@example.com"))
    .addToItem(new MailAddress("Recipient Name", "recipient@example.com"))
    .subject("Standard Email Example")
    .body("This is a standard email that we'll convert to MAPI format.")
    .isBodyHtml(false)
    .addAttachmentsItem(new Attachment()
        .base64Data(Base64.getEncoder().encodeToString("Attachment content".getBytes()))
        .name("example.txt")
    );

// Convert EmailDto to MapiMessageDto
MapiMessageDto mapiFromEmail = api.email().asMapi(email);
System.out.println("Converted standard email to MAPI format");
System.out.println("MAPI subject: " + mapiFromEmail.getSubject());
System.out.println("MAPI sender: " + mapiFromEmail.getSenderName() + 
                   " <" + mapiFromEmail.getSenderEmailAddress() + ">");

// Convert MapiMessageDto back to EmailDto
EmailDto emailFromMapi = api.mapi().message().asEmailDto(mapiMessage);
System.out.println("\nConverted MAPI message back to standard email format");
System.out.println("Email subject: " + emailFromMapi.getSubject());
System.out.println("Email from: " + emailFromMapi.getFrom().getDisplayName() + 
                   " <" + emailFromMapi.getFrom().getAddress() + ">");
System.out.println("Email to: " + emailFromMapi.getTo().get(0).getDisplayName() + 
                   " <" + emailFromMapi.getTo().get(0).getAddress() + ">");

Step 5: Working with MAPI Calendar Items

Now, let’s create and work with a MAPI calendar item:

# Python
from asposeemail.models import (
    MapiCalendarDto, MapiCalendarAttendeesDto, MapiCalendarEventRecurrenceDto,
    MapiCalendarDailyRecurrencePatternDto, MapiElectronicAddressDto,
    MapiCalendarAsFileRequest, MapiCalendarSaveRequest, MapiCalendarGetRequest
)

# Create a MAPI calendar item
mapi_calendar = MapiCalendarDto(
    # Calendar item properties
    busy_status="Tentative",
    start_date=datetime.now() + timedelta(days=1),  # Tomorrow
    end_date=datetime.now() + timedelta(days=1, hours=1),  # 1 hour meeting
    location="Conference Room A",
    body="Discussing the project progress",
    body_type="PlainText",
    subject="Project Status Meeting",
    
    # Add attendees
    attendees=MapiCalendarAttendeesDto(
        appointment_recipients=[
            MapiRecipientDto(
                address_type="SMTP",
                display_name="Attendee Name",
                email_address="attendee@example.com",
                recipient_type="MapiTo"
            ),
            MapiRecipientDto(
                address_type="SMTP",
                display_name="Optional Attendee",
                email_address="optional@example.com",
                recipient_type="MapiCc"  # CC recipients are treated as optional attendees
            )
        ]
    ),
    
    # Set organizer
    organizer=MapiElectronicAddressDto(
        email_address="organizer@example.com"
    ),
    
    # Set recurrence (daily for 10 occurrences)
    recurrence=MapiCalendarEventRecurrenceDto(
        recurrence_pattern=MapiCalendarDailyRecurrencePatternDto(
            occurrence_count=10,
            week_start_day="Monday"
        )
    )
)

# Convert MAPI calendar to MSG file
calendar_msg = api.mapi.calendar.as_file(
    MapiCalendarAsFileRequest("Msg", mapi_calendar)
)
print(f"MAPI calendar converted to MSG format, size: {len(calendar_msg)} bytes")

# Save locally
with open("mapi_calendar_example.msg", "wb") as f:
    f.write(calendar_msg)
print("Calendar MSG file saved locally as 'mapi_calendar_example.msg'")

# Save to cloud storage
storage = "First Storage"
folder = "mapi_examples"
file_name = "calendar_meeting.msg"

api.mapi.calendar.save(
    MapiCalendarSaveRequest(
        storage_file=StorageFileLocation(storage, folder, file_name),
        value=mapi_calendar,
        format="Msg"
    )
)
print(f"MAPI calendar saved to storage as {file_name}")

# Retrieve from storage
retrieved_calendar = api.mapi.calendar.get(
    MapiCalendarGetRequest(file_name, folder, storage)
)
print("Retrieved MAPI calendar from storage")
print(f"Subject: {retrieved_calendar.subject}")
print(f"Location: {retrieved_calendar.location}")
print(f"Start: {retrieved_calendar.start_date}")
print(f"End: {retrieved_calendar.end_date}")

Step 6: Converting Between MAPI Calendar and CalendarDto

Similarly to emails, you can convert between MAPI calendar and standard calendar formats:

# Python
from asposeemail.models import (
    CalendarDto, DailyRecurrencePatternDto, CalendarAsFileRequest
)

# Create a standard CalendarDto
calendar = CalendarDto(
    location="Meeting Room 101",
    summary="Weekly Team Sync",
    description="Discuss weekly progress and roadblocks",
    organizer=MailAddress("Organizer Name", "organizer@example.com"),
    attendees=[
        MailAddress("Attendee 1", "attendee1@example.com", "Accepted"),
        MailAddress("Attendee 2", "attendee2@example.com", "Tentative")
    ],
    start_date=datetime.now() + timedelta(days=2),
    end_date=datetime.now() + timedelta(days=2, hours=1),
    recurrence=DailyRecurrencePatternDto(
        occurs=5,
        week_start="Monday"
    )
)

# Convert standard calendar to MAPI format
mapi_from_calendar = api.calendar.as_mapi(calendar)
print("Standard calendar converted to MAPI format")
print(f"MAPI calendar subject: {mapi_from_calendar.subject}")
print(f"MAPI calendar location: {mapi_from_calendar.location}")

# Convert MAPI calendar to standard format
calendar_from_mapi = api.mapi.calendar.as_calendar_dto(mapi_calendar)
print("\nMAPI calendar converted to standard format")
print(f"Calendar summary: {calendar_from_mapi.summary}")
print(f"Calendar location: {calendar_from_mapi.location}")
print(f"Calendar organizer: {calendar_from_mapi.organizer.address}")

Step 7: Working with MAPI Contact Items

Next, let’s create and manipulate a MAPI contact:

# Python
from asposeemail.models import (
    MapiContactDto, MapiContactNamePropertySetDto,
    MapiContactPersonalInfoPropertySetDto, MapiContactProfessionalPropertySetDto,
    MapiContactElectronicAddressPropertySetDto, MapiContactElectronicAddressDto,
    MapiContactTelephonePropertySetDto, MapiContactAsFileRequest,
    MapiContactSaveRequest, MapiContactGetRequest
)

# Create a MAPI contact
mapi_contact = MapiContactDto(
    # Contact name information
    name_info=MapiContactNamePropertySetDto(
        given_name="John",
        surname="Smith",
        middle_name="Robert",
        display_name="John R. Smith",
        nickname="Johnny"
    ),
    
    # Personal information
    personal_info=MapiContactPersonalInfoPropertySetDto(
        business_home_page="www.example.com",
        spouse_name="Jane Smith",
        personal_home_page="www.johnsmith.example.com"
    ),
    
    # Professional information
    professional_info=MapiContactProfessionalPropertySetDto(
        title="Senior Developer",
        company_name="Acme Corporation",
        department_name="Research & Development",
        office_location="Building A, 5th Floor",
        profession="Software Engineering"
    ),
    
    # Electronic addresses
    electronic_addresses=MapiContactElectronicAddressPropertySetDto(
        default_email_address=MapiContactElectronicAddressDto(
            email_address="john.smith@example.com"
        ),
        email_address_1=MapiContactElectronicAddressDto(
            email_address="john.smith@example.com",
            display_name="John Smith",
            address_type="SMTP"
        ),
        email_address_2=MapiContactElectronicAddressDto(
            email_address="jsmith@work.example.com",
            display_name="John Smith (Work)",
            address_type="SMTP"
        )
    ),
    
    # Telephone numbers
    telephones=MapiContactTelephonePropertySetDto(
        business_telephone_number="+1 (234) 567-8901",
        home_telephone_number="+1 (234) 567-8902",
        mobile_telephone_number="+1 (234) 567-8903"
    )
)

# Convert MAPI contact to MSG file
contact_msg = api.mapi.contact.as_file(
    MapiContactAsFileRequest("Msg", mapi_contact)
)
print(f"MAPI contact converted to MSG format, size: {len(contact_msg)} bytes")

# Save locally
with open("mapi_contact_example.msg", "wb") as f:
    f.write(contact_msg)
print("Contact MSG file saved locally as 'mapi_contact_example.msg'")

# Save to cloud storage
storage = "First Storage"
folder = "mapi_examples"
file_name = "contact_john_smith.msg"

api.mapi.contact.save(
    MapiContactSaveRequest(
        storage_file=StorageFileLocation(storage, folder, file_name),
        value=mapi_contact,
        format="Msg"
    )
)
print(f"MAPI contact saved to storage as {file_name}")

# Retrieve from storage
retrieved_contact = api.mapi.contact.get(
    MapiContactGetRequest("Msg", file_name, folder, storage)
)
print("Retrieved MAPI contact from storage")
print(f"Name: {retrieved_contact.name_info.given_name} {retrieved_contact.name_info.surname}")
print(f"Email: {retrieved_contact.electronic_addresses.default_email_address.email_address}")
print(f"Company: {retrieved_contact.professional_info.company_name}")
print(f"Position: {retrieved_contact.professional_info.title}")

Step 8: Converting Between MAPI Contact and ContactDto

Just like with messages and calendars, you can convert between MAPI contacts and standard contact format:

# Python
from asposeemail.models import (
    ContactDto, EnumWithCustomOfEmailAddressCategory, EnumWithCustomOfPhoneNumberCategory
)

# Create a standard ContactDto
contact = ContactDto(
    surname="Johnson",
    given_name="Michael",
    gender="Male",
    job_title="Project Manager",
    company="Global Enterprises",
    email_addresses=[
        EmailAddress(
            EnumWithCustomOfEmailAddressCategory("Work"),
            "Michael Johnson", True, address="michael.johnson@work.com"
        ),
        EmailAddress(
            EnumWithCustomOfEmailAddressCategory("Home"),
            "Mike", False, address="mike.johnson@example.com"
        )
    ],
    phone_numbers=[
        PhoneNumber(
            EnumWithCustomOfPhoneNumberCategory("Work"),
            "+1-555-0123", True
        ),
        PhoneNumber(
            EnumWithCustomOfPhoneNumberCategory("Mobile"),
            "+1-555-4567", False
        )
    ]
)

# Convert standard contact to MAPI format
mapi_from_contact = api.contact.as_mapi(contact)
print("Standard contact converted to MAPI format")
print(f"MAPI contact name: {mapi_from_contact.name_info.given_name} {mapi_from_contact.name_info.surname}")
if mapi_from_contact.electronic_addresses and mapi_from_contact.electronic_addresses.email_address_1:
    print(f"MAPI contact email: {mapi_from_contact.electronic_addresses.email_address_1.email_address}")

# Convert MAPI contact to standard format
contact_from_mapi = api.mapi.contact.as_contact_dto(mapi_contact)
print("\nMAPI contact converted to standard format")
print(f"Contact name: {contact_from_mapi.given_name} {contact_from_mapi.surname}")
if contact_from_mapi.email_addresses and len(contact_from_mapi.email_addresses) > 0:
    print(f"Contact email: {contact_from_mapi.email_addresses[0].address}")

Step 9: Working with MAPI Properties

One of the most powerful features of the MAPI API is the ability to work with individual MAPI properties. Let’s explore how to access and modify specific properties:

# Python
from asposeemail.models import (
    MapiPropertyDto, MapiStringPropertyDto, MapiBooleanPropertyDto,
    MapiIntPropertyDto, MapiKnownPropertyDescriptor
)

# Examine the properties in a MAPI message
for prop in mapi_message.properties:
    # The property descriptor identifies the property
    descriptor = prop.descriptor
    
    if hasattr(descriptor, 'name'):  # Known property
        prop_name = descriptor.name
        
        # Different property types have different value fields
        if hasattr(prop, 'value'):  # String, Integer, Boolean properties
            prop_value = prop.value
        elif hasattr(prop, 'value_base64'):  # Binary properties
            prop_value = f"Binary data ({len(prop.value_base64)} bytes)"
        else:
            prop_value = "Unknown value type"
            
        print(f"Property: {prop_name}, Value: {prop_value}")

# Find a specific property - Subject
subject_property = next(
    (p for p in mapi_message.properties 
     if hasattr(p.descriptor, 'name') and p.descriptor.name == "TagSubject"),
    None
)

if subject_property:
    print(f"\nFound subject property: {subject_property.value}")
    
    # Create a modified list of properties
    modified_properties = list(mapi_message.properties)
    
    # Find the index of the subject property
    subject_index = modified_properties.index(subject_property)
    
    # Create a new string property with modified value
    new_subject = MapiStringPropertyDto(
        value="Modified Subject via Properties",
        descriptor=MapiKnownPropertyDescriptor(name="TagSubject")
    )
    
    # Replace the old property with the new one
    modified_properties[subject_index] = new_subject
    
    # Update the message properties
    mapi_message.properties = modified_properties
    
    print(f"Subject property modified to: {new_subject.value}")

# Convert the modified message to MSG
modified_msg = api.mapi.message.as_file(
    MapiMessageAsFileRequest("Msg", mapi_message)
)

# Save locally
with open("modified_properties_message.msg", "wb") as f:
    f.write(modified_msg)
print("Modified message saved as 'modified_properties_message.msg'")

Advanced MAPI Operations

Let’s explore some more advanced MAPI operations:

Creating an HTML Email with Embedded Images

# Python
# Create a MAPI message with HTML body and embedded image
html_body = """
<html>
<body>
<h1>HTML Email with Embedded Image</h1>
<p>This is a paragraph with <b>bold</b> and <i>italic</i> text.</p>
<p>Below is an embedded image:</p>
<img src="cid:image1" alt="Embedded Image" />
<p>Regards,<br>The Sender</p>
</body>
</html>
"""

# This is a small sample image in base64 (a red square)
sample_image_base64 = "iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAIAAAAC64paAAAABGdBTUEAALGPC/xhBQAAAAlwSFlzAAAO" + \
                       "vAAADrwBlbxySQAAABl0RVh0U29mdHdhcmUAUGFpbnQuTkVUIHYzLjUuNUmK/OAAAACISURBVDhP7ZM/" + \
                       "CsJAEEbXf0gh2NoJ9iKCjZ3gIawsbD2GRbB7D+bHC0jAzkLwANp/UizCbHaCtikEfMUw+83wJnnjCYw5" + \
                       "szWmSAA8YiQaNoFMU20dJBdTrQTJU6GVYXIc/KA9QgpP2nXO66Fj9JJ9qTdWHCYnRknbKI6TMsXTdfLl" + \
                       "f5R8fkwuHYtwDFvcSC8AAAAASUVORK5CYII="

# Create a MAPI message with HTML body
mapi_html_message = MapiMessageDto(
    subject="HTML Email with Embedded Image",
    body=html_body,
    body_type="Html",
    message_class="IPM.Note",
    sender_address_type="SMTP",
    sender_email_address="sender@example.com",
    sender_name="Sender Name",
    
    # Add recipients
    recipients=[
        MapiRecipientDto(
            address_type="SMTP",
            display_name="Recipient Name",
            email_address="recipient@example.com",
            recipient_type="MapiTo"
        )
    ],
    
    # Add the embedded image as an attachment
    attachments=[
        MapiAttachmentDto(
            data_base64=sample_image_base64,
            name="image1.png",
            # Content ID corresponds to the "cid:image1" in the HTML
            content_id="image1",
            # Content type specifies this is an embedded image
            content_type="image/png"
        )
    ]
)

# Convert to MSG file
html_msg = api.mapi.message.as_file(
    MapiMessageAsFileRequest("Msg", mapi_html_message)
)

# Save locally
with open("html_email_with_image.msg", "wb") as f:
    f.write(html_msg)
print("HTML email with embedded image saved as 'html_email_with_image.msg'")

Working with Recurring Appointments

# Python
# Create a MAPI calendar with complex recurrence pattern
weekly_meeting = MapiCalendarDto(
    subject="Weekly Team Meeting",
    location="Conference Room B",
    body="Regular team sync-up meeting",
    start_date=datetime.now().replace(hour=10, minute=0, second=0, microsecond=0) + timedelta(days=(7 - datetime.now().weekday())),  # Next Monday at 10 AM
    end_date=datetime.now().replace(hour=11, minute=0, second=0, microsecond=0) + timedelta(days=(7 - datetime.now().weekday())),   # Next Monday at 11 AM
    
    # Set organizer
    organizer=MapiElectronicAddressDto(
        email_address="manager@example.com"
    ),
    
    # Set recurrence (weekly on Monday and Wednesday, for 10 occurrences)
    recurrence=MapiCalendarEventRecurrenceDto(
        recurrence_pattern=MapiCalendarWeeklyRecurrencePatternDto(
            day_of_week=["Monday", "Wednesday"],  # Meets on Mondays and Wednesdays
            occurrence_count=10,                  # For 10 occurrences
            week_start_day="Monday"
        )
    ),
    
    # Add reminder
    reminder_delta=15,  # 15-minute reminder
    reminder_file_parameter="reminder.wav",
    reminder_set=True
)

# Convert to ICS file (iCalendar format)
ics_file = api.mapi.calendar.as_file(
    MapiCalendarAsFileRequest("Ics", weekly_meeting)
)

# Save locally
with open("weekly_recurring_meeting.ics", "wb") as f:
    f.write(ics_file)
print("Recurring meeting saved as 'weekly_recurring_meeting.ics'")

Troubleshooting Tips

If you encounter issues when working with MAPI files:

Property access issues:
- MAPI properties are strongly typed - make sure you’re using the right property type
- Some properties might not be available in all MAPI item types
- Check the property descriptor to ensure you’re accessing the right property
File format compatibility:
- MSG files are specific to Microsoft Outlook
- When converting between formats, some properties might not have equivalents
- Test conversion results to ensure critical data is preserved
Embedded content:
- For HTML emails with embedded images, ensure Content-ID references match
- Content types must be correctly specified for proper rendering
Storage paths:
- Verify storage names, folders, and file paths are correct
- Ensure you have appropriate permissions on the storage
Complex objects:
- MAPI objects can have deep hierarchies of properties
- Use debugging techniques to explore the structure of returned objects

What You’ve Learned

In this tutorial, you’ve learned how to:

Create and manipulate MAPI message, calendar, and contact objects
Convert between MAPI objects and standard Dto objects
Save MAPI files to and retrieve them from cloud storage
Access and modify specific MAPI properties
Work with complex MAPI features like HTML content and recurrence patterns
Implement MAPI operations in multiple programming languages

Further Practice

To reinforce your learning:

Create a tool that extracts specific MAPI properties from a batch of MSG files
Build a conversion utility that migrates Outlook MSG files to standard formats
Implement a custom property editor for MAPI messages
Create a calendar event generator with complex recurrence patterns
Build a contact management system that preserves all Outlook contact fields

Next Steps

Consider exploring these related tutorials:

Email Message Files - Learn more about working with standard email formats
Quick Start With Email Client - Use MAPI files with email clients

Helpful Resources

Have questions about this tutorial? Feel free to reach out to us on the Aspose.Email Cloud forum.