Email Message Files

How to Work With Email Message Files via Aspose.Email Cloud API

Aspose.Email Cloud API supports email message files with EML, MSG, MHTML and HTML format. We have API for creating, editing, converting such files. Also, email message files can be used in the built-in email client.

Our SDKs support two different ways of operating with email message files using MapiMessageDto and EmailDto. This tutorial shows how to use an EmailDto.

To see how to setup SDKs use the SDK setup tutorial.

Email Message Files

Simply put, email message files are the files using to exchanging messages between people using electronic devices. Sounds simple, isn’t it?

You may already know this. In our time, it’s hard to find a person who doesn’t use email message. We use emails everywhere at our work, in a friendly conversation, etc.

There are many ways to send and retrieve emails, so, there are many file formats for these purposes.

Let’s find out which email formats exist:

EML — using in Microsoft Outlook Express as well as some other email programs. An email message saved to a file in the MIME RFC 822 standard format. EML files usually contain plain ASCII text for the main message body, headers and hyperlinks and attachments.
MSG — using in Microsoft Outlook and Exchange. An MSG file can contain plain ASCII text as in EML files.
HTML — the extension for web pages created for display in browsers. The HTML file format is very convenient to display emails on the web sites.

As we have mentioned before, email message files are using for exchanging messages. With Aspose.Email Cloud API you can easily change the email’s data, attachments and other information. The API can help you to simplify the development of your product and achieve your goals. The Cloud approach provides you with the processing power of our servers, using them you do not need to process messages on your servers, provide this to us. User-friendly API provides security and ease of development.

How to Create Email Object and Save It as File on Storage

The best way to work with emails is to use EmailDto objects. EmailDto object contains all email’s data:

Email’s data that is contained in EmailDto

Collection of alternate views of the message.
Email message attachments.
BCC recipients.
Message subject.
Sender address.
The address collection that contains the recipients of a message.
Email message body as plain text.
Body encoding.
The content type of message body: PlainText, Html, Rtf.
CC recipients.
Message date.
Delivery notification options.
From address.
Document headers.
HTML body.
Linked resources of a message.
The list of addresses to reply to for the mail message.
And other email’s data.

Create Email File — EmailDto Object

First, let’s create an EmailDto object and save it as a file on the Storage.

To create an email file (EML, MSG, MHTML, HTML) you need to create EmailDto object. To initialize EmailDto object let’s define main fields: From (accepts MailAddress object which contains the email address of a sender), To (accepts List of MailAddress objects; parameter To can contain several email addresses), Subject (accepts a string with a subject of an email), Body (accepts a string with a body’s content).

After creating EmailDto object we save it to Storage. To save it we need to choose storage and folder where we want to save our created email file. Also, we need to create a name for this email file. EmailApi class has a function called SaveAsync which requires one parameter — EmailSaveRequest.

EmailSaveRequest has 3 fields:

Format defines a file format.
Value is an EmailDto object.
StorageFile is an StorageFileLocation object that defines the email file location on Storage.

Look at the following code examples:

How to create an EmailDto object and save it as a file on storage?

var email = new EmailDto
{
    From = new MailAddress("From address", "organizer@aspose.com", "Accepted"),
    To = new List<MailAddress> {new MailAddress("To address", "attendee@aspose.com", null)},
    Subject = "Some subject",
    Body = "Some body"
};
var storage = "First storage";
var folder = "folder/on/storage";
var emailFile = "email.eml";
var format = "Eml";

await api.Email.SaveAsync(new EmailSaveRequest(
    new StorageFileLocation(storage, folder, emailFile), 
    email, format));

Java

EmailDto email = new EmailDto()
    .from(new MailAddress("From Name", "organizer@aspose.com", null))
    .addToItem(new MailAddress("To Name", "attendee@aspose.com", null))
    .subject("Some subject")
    .body("Some body");
String emailFile = "email.eml";
String storage = "First storage";
String folder = "folder/on/storage";
String format = "Eml";

api.email().save(new EmailSaveRequest(
    new StorageFileLocation(storage, folder, emailFile),
    email, format));

Python

email = models.EmailDto(
    # 'from' is reserved, so from field is named '_from':
    _from=models.MailAddress('From Name', 'organizer@aspose.com'),
    to=[models.MailAddress('To Name', 'attendee@aspose.com')],
    subject='Some subject',
    body='Some body')
storage = 'First storage'
folder = 'folder/on/storage'
email_file = 'email.eml'
file_format = 'Eml'

api.email.save(models.EmailSaveRequest(
    models.StorageFileLocation(storage, folder, email_file),
    email, file_format))

Ruby

email = EmailDto.new(
  from: MailAddress.new(address: 'from@aspose.com'),
  to: [MailAddress.new(address: 'to@aspose.com')],
  subject: 'Some subject',
  body: 'Some body')
 
folder = 'folder/on/storage'
storage = 'First storage'
email_file = "email.eml"
format = "Eml"

api.email.save(
  EmailSaveRequest.new(
    storage_file: StorageFileLocation.new(
      storage: storage,
      folder_path: folder,
      file_name: email_file),
    value: email,
    format: format))

Typescript

var email = new EmailDto();
email.from = new MailAddress('From address', 'organizer@aspose.com');
email.to = [new MailAddress('To address', 'attendee@aspose.com')];
email.subject = 'Some subject';
email.body = 'Some body';
 
var storage = 'First storage';
var folder = 'folder/on/storage';
var emailFile = 'email.eml';
var format = 'Eml';

await api.email.save(new EmailSaveRequest(
    new StorageFileLocation(storage, folder, emailFile),
    email, format));

PHP

$email = (new EmailDto())
    ->setFrom(new MailAddress("Organizer Name", "organizer@aspose.com"))
    ->setTo(array(new MailAddress("Attendee Name", "attendee@aspose.com")))
    ->setSubject("Some subject")
    ->setBody("Some body");

$storage = "First storage";
$folder = "folder/on/storage"; 
$emailFile = "email.eml";
$format = "Eml";

$api->email()->save(new EmailSaveRequest(
    new StorageFileLocation($storage, $folder, $emailFile),
    $email, $format));

You can edit the EmailDto object and save it again. If file name and location will be the same, the file will be overwritten.

How to Download Email File From Storage

You can download files from the Storage.

FileApi class has DownloadFileAsync function which allows to download files from Storage asynchronous as a Stream. This function has one required parameter — DownloadFileRequest. To define it you need to pass 2 parameters into it: a file’s path as a string and a name of Storage you want to download from.

To download the file that we created in the previous step from the Storage, use the following steps:

How to download a file from the Storage?

var resultStream = await api.CloudStorage.File.DownloadFileAsync(
    new DownloadFileRequest($"{folder}/{emailFile}", storage));

Java

byte[] result = api.cloudStorage().file().downloadFile(
    new DownloadFileRequest(folder + "/" + emailFile, storage, null));

Python

downloaded_file_location = api.cloud_storage.file.download_file(
    models.DownloadFileRequest(folder + '/' + email_file, storage))

Ruby

downloaded_file_location = api.cloud_storage.file.download_file(
    DownloadFileRequest.new(folder + '/' + email_file, storage))

Typescript

var downloaded = await api.cloudStorage.file.downloadFile(
    new DownloadFileRequest(folder + '/' + emailFile, storage));

PHP

$downloaded = $api->cloudStorage()->file()->downloadFile(
    new DownloadFileRequest($folder.'/'.$emailFile, $storage));
$fileContent = $downloaded->fread($downloaded->getSize());

Also, you can download a file in another format.

Aspose.Email Cloud allows you to download email messages from Storage in many different file formats. For example, you have an EML file, you want to download it but in MSG. You can download it immediately without separate converting.

To download email file from Storage you need to call GetAsFile function from EmailApi. GetAsFile accepts only one required parameter — EmailGetAsFileRequest.

To initialize EmailGetAsFileRequest you need to pass 4 parameters into it: a name of an email file on Storage as a string, a result file’s extension as an Enum (EML, MSG, MsgUnicode, MHTML, HTML), storage’s name as a string and a path to a folder on Storage where email file is.

If you do everything right you will get the email file as a Stream.

How to download a file from the Storage in a different format?

var file = await api.Email.GetAsFileAsync(new EmailGetAsFileRequest(
    emailFile, "Msg", storage, folder));

Java

byte[] file = api.email().getAsFile(new EmailGetAsFileRequest(
    emailFile, "Msg", storage, folder));

Python

file = api.email.get_as_file(models.EmailGetAsFileRequest(
    email_file, 'Msg', storage, folder))

Ruby

file = api.email.get_as_file(EmailGetAsFileRequest.new(
  file_name: email_file, format: 'Msg', storage: storage, folder: folder))

Typescript

const file = await api.email.getAsFile(new EmailGetAsFileRequest(
    emailFile, 'Msg', storage, folder));

PHP

$file = $api->email()->getAsFile(new EmailGetAsFileRequest(
    $emailFile, 'Msg', $storage, $folder));

You can download the file as an EmailDto object:

EmailDto provides you with an easier way to work with emails. It allows to change and get data from an email file in several code lines.

If you want to get an email from Storage as an EmailDto object — you need to use GetAsync from EmailApi.

Unlike the previous case, here we need to pass EmailGetRequest into GetAsync.

EmailGetRequest accepts 2 required parameters: an email document format as Enum (EML, MSG, MsgUnicode, MHTML, HTML), email document file name as a string; and 2 optional parameters: storage’s name as a string and a path to a folder on Storage where email file is as a string too.

After calling GetAsync you get EmailDto object.

How to download a file as EmailDto object?

var emailDto = await api.Email.GetAsync(new EmailGetRequest(
    "Eml", emailFile, folder, storage));

Java

EmailDto emailDto = api.email().get(new EmailGetRequest(
    "Eml", emailFile, folder, storage));

Python

email_dto = api.email.get(models.EmailGetRequest(
    'Eml', email_file, folder, storage))

Ruby

email_dto = api.email.get(EmailGetRequest.new(
  format: 'Eml', file_name: email_file, folder: folder, storage: storage))

Typescript

const emailDto = await api.email.get(new EmailGetRequest(
    'Eml', emailFile, folder, storage));

PHP

$emailDto = $api->email()->get(new EmailGetRequest(
    'Eml', $emailFile, $folder, $storage));

How to Append Email Object to “INBOX” Folder of IMAP Account

We can append this EmailDto object to the “INBOX” folder of an IMAP account:

See how to setup and use email client in the Quickstart with an email client tutorial.

To append an email to the “INBOX” folder of an IMAP account, you should create *.account file with IMAP account credentials at first. Then you need to call AppendAsync function from ClientMessageApi.

AppendAsync has only one required parameter — ClientMessageAppendRequest.

ClientMessageAppendRequest object has 4 parameters:

Account location on storage represented as a StorageFileLocation object.
Email account folder to store a message as a string. For example, “INBOX”.
Mark message as sent. Nullable bool parameter.
Email document. In our case it should be represented as a MailMessageDto object.

As a result, you will add an email from model to a specified folder in an email account.

How to append EmailDto object to the “INBOX” folder of an IMAP account?

var imapAccount = "imap.account";
var messageId = await api.Client.Message.AppendAsync(
    new ClientMessageAppendRequest(
        new StorageFileLocation(storage, folder, imapAccount),
        "INBOX",
        new MailMessageDto(emailDto),
        true));

Java

String imapAccount = "imap.account";
ValueTOfString messageId = api.client().message().append(
    new ClientMessageAppendRequest(
        new StorageFileLocation(storage, folder, imapAccount),
        "INBOX",
        new MailMessageDto(emailDto),
        true));

Python

imap_account = 'imap.account'
message_id = api.client.message.append(
    models.ClientMessageAppendRequest(
        models.StorageFileLocation(storage, folder, imap_account),
        'INBOX',
        models.MailMessageDto(email_dto),
        True))

Ruby

imap_account = 'imap.account'
message_id = api.client.message.append(
  ClientMessageAppendRequest.new(
    account_location: StorageFileLocation.new(
      storage: storage,
      folder_path: folder,
      file_name: imap_account),
    folder: 'INBOX',
    message: MailMessageDto.new(email_dto),
    mark_as_sent: true))

Typescript

const imapAccount = 'imap.account';
var messageId = await api.client.message.append(
    new ClientMessageAppendRequest(
        new StorageFileLocation(storage, folder, imapAccount),
        'INBOX',
        new MailMessageDto(emailDto),
        true));

PHP

$imapAccount = 'imap.account';
$messageId = $api->client()->message()->append(
    new ClientMessageAppendRequest(
        new StorageFileLocation($storage, $folder, $imapAccount),
        'INBOX',
        new MailMessageDto($emailDto),
        true));

How to Convert Email From One Format to Another

If you don’t want to use all these models and storages, and just want to convert email file from one format to another, use the fast and convenient Converter developed by Aspose.

To convert email file use ConvertAsync from EmailApi. This function requires only one parameter — EmailConvertRequest which requests a file for converting.

It has 3 required parameters:

Email file format to convert from. Possible values are: EML, MSG, MsgUnicode, MHTML, HTML.
Email file format to convert to.
File to convert as a Stream.

How to convert an email from one format to another?

using(var emlStream = File.OpenRead("email.eml"))
{
    var mapiStream = await api.Email.ConvertAsync(
        new EmailConvertRequest("Eml", "Msg", emlStream));
    //...
}

Java

byte[] fileToConvert = IOUtils.toByteArray(
    new FileInputStream("email.eml"));
byte[] mapiBytes = api.email().convert(
    new EmailConvertRequest("Eml", "Msg", emlBytes));

Python

mapi = api.email.convert(
    models.EmailConvertRequest('Eml', 'Msg', 'email.eml'))
with open(mapi, 'r') as f:
    filedata = f.read()
    # ...

Ruby

mapi_file = api.email.convert(
  EmailConvertRequest.new(
    from_format: 'Eml',
    to_format: 'Msg',
    file: File.new('email.eml')))
converted = File.open(mapi_file, 'rb') do |f|
  bin = f.read
  # ...
end

Typescript

let mapi = await api.email.convert(
    new EmailConvertRequest('Eml', 'Msg', fs.readFileSync('email.eml')));

PHP

$mapi = $api->email()->convert(
    new EmailConvertRequest('Eml', 'Msg', "email.eml"));

Email Message Files

How to Work With Email Message Files via Aspose.Email Cloud API

Email Message Files

How to Create Email Object and Save It as File on Storage

Create Email File — EmailDto Object

How to Download Email File From Storage

How to Append Email Object to “INBOX” Folder of IMAP Account

How to Convert Email From One Format to Another

More Tutorials