Quick Start With Email Client

Built-In Email Client

Aspose.Email Cloud API contains a built-in email client.

The built-in email client supports:

SMTP
POP3
IMAP
EWS
WebDav
Virtual multi-account

Virtual multi-account is a fast and convenient way to set up multiple email accounts and use them as a single one.

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

How to Work With Email Client

Before we start, we should set up an email account. This allows you to process your messages with built-in Email Client which is developed by Aspose.Email Cloud.

The created email account will be saved on storage, so you don’t have to repeat this operation later.

Setup email account

First of all, you need to set up your email account’s credentials with EmailClientAccountPasswordCredentials class. Define two fields: Login (Email client account login) and Password (Email client account password).

Then you need to initialize EmailClientAccount object. Let’s define the following parameters:

Host — Mail server hostname or IP address.
Port — Mail server port.
ProtocolType — Type of connection protocol. Enum, available values: IMAP, POP3, SMTP, EWS, WebDav.
SecurityOptions — Email account security mode Enum, available values: None, SSLExplicit, SSLImplicit, SSLAuto, Auto.
Credentials — Email client account credentials that we have created before.

To save your email account use SaveAsync from ClientAccountApi. You should create a request for this operation using ClientAccountSaveRequest, which has 2 parameters:

Value — Object we want to save on Storage.
StorageFile — StorageFileLocation object, which contains IMAP account’s file location information, including storage name, a path to an account folder, name of the file with IMAP account’s configurations.

var credentials = new EmailClientAccountPasswordCredentials { 
    Login = "example@gmail.com", 
    Password = "password" 
};

var receiveAccountDto = new EmailClientAccount {
    Host = "imap.gmail.com", 
    Port = 993, 
    ProtocolType = "IMAP", 
    SecurityOptions = "SSLAuto", 
    Credentials = credentials
};

var imapAccount = "imap.account"; 
var accountFolder = "folder/on/storage";
var storageName = "First storage";
var imapLocation = new StorageFileLocation(storageName, accountFolder, imapAccount);

await api.Client.Account.SaveAsync(new ClientAccountSaveRequest(
    imapLocation, receiveAccountDto));

Java

EmailClientAccountPasswordCredentials credentials =
    new EmailClientAccountPasswordCredentials(
        "example@gmail.com", "password");
EmailClientAccount receiveAccountDto = new EmailClientAccount(
    "imap.gmail.com", 993, "SSLAuto", "IMAP", credentials, null);

String imapAccount = "imap.account";
String accountFolder = "folder/on/storage";
String storageName = "First Storage";
StorageFileLocation imapLocation = new StorageFileLocation(
    storageName, accountFolder, imapAccount);

api.client().account().save(new ClientAccountSaveRequest(
  imapLocation, receiveAccountDto));

Python

credentials = models.EmailClientAccountPasswordCredentials(
    'example@gmail.com', 'password')

receive_account_dto = models.EmailClientAccount(
    'imap.gmail.com', 993, 'SSLAuto', 'IMAP', credentials)

imap_account = 'imap.account'
storage_name = 'First storage'
account_folder = 'folder/on/storage'
imap_location = models.StorageFileLocation(
    storage_name, account_folder, imap_account)

api.client.account.save(models.ClientAccountSaveRequest(
    imap_location, receive_account_dto))

Ruby

credentials = EmailClientAccountPasswordCredentials.new(
  login: 'example@gmail.com', password: 'password')
receive_account_dto = EmailClientAccount.new(
  host: 'imap.gmail.com',
  port: 993,
  security_options: 'SSLAuto',
  protocol_type: 'IMAP',
  credentials: credentials)

imap_account = 'imap.account'
storage_name = 'First Storage'
account_folder = 'folder/on/storage'
imap_location = StorageFileLocation.new(
  storage: storage_name,
  folder_path: account_folder,
  file_name: imap_account)

api.client.account.save(ClientAccountSaveRequest.new(
  storage_file: imap_location, value: receive_account_dto))

Typescript

const credentials = new EmailClientAccountPasswordCredentials(
    'example@gmail.com', 'password');
const receiveAccountDto = new EmailClientAccount(
    'imap.gmail.com', 993, 'SSLAuto', 'IMAP', credentials);

const imapAccount = 'imap.account';
const storageName = 'First storage';
const accountFolder = 'folder/on/storage';
const imapLocation = new StorageFileLocation(
    storageName, accountFolder, imapAccount);

await api.client.account.save(
    new ClientAccountSaveRequest(imapLocation, receiveAccountDto));

PHP

$credentials = new EmailClientAccountPasswordCredentials(
    "example@gmail.com", "password");
$receiveAccountDto = new EmailClientAccount(
    "imap.gmail.com", 993, "SSLAuto", "IMAP", $credentials);

$imapAccount = "imap.account";
$storageName = "First storage";
$accountFolder = "folder/on/storage";
$imapLocation = new StorageFileLocation(
    $storageName, $accountFolder, $imapAccount);

$api->client()->account()->save(new ClientAccountSaveRequest(
    $imapLocation, $receiveAccountDto));

Search Emails

To search for emails in your email account’s folders you need to call ListAsync from ClientMessageApi. This method has one parameter — ClientMessageListRequest, which is a request model for this operation. In this model you should define the following fields:

Folder — A folder in email account.
Account — Email account.
QueryString — A MailQuery search string.
Storage — Storage name where account file(s) located.
AccountStorageFolder — Folder in storage where account file(s) located.
Recursive [optional] — Specifies that should message be searched in subfolders recursively.
Type - Using this property you can get messages in different formats (as EmailDto, MapiMessageDto or a file represented as Base64 string).
Format - Base64 data format. Used only if Type is set to Base64.

After that, you will get a list of messages matching your search criteria as MailMessageBaseList.

Now you can search emails

const string imapFolderName = "INBOX";
MailMessageBaseList messages = await api.Client.Message.ListAsync(
    new ClientMessageListRequest(
        imapFolderName, imapAccount, "('From' Contains '.com')",
        storageName, accountFolder, true, "Dto"));

Java

String imapFolderName = "INBOX";
MailMessageBaseList messages = api.client().message().list(new ClientMessageListRequest(
    imapFolderName , imapAccount, "('From' Contains '.com')", storageName,
    accountFolder, true, "Dto", null));

Python

imap_folder_name = 'INBOX'
messages = api.client.message.list(models.ClientMessageListRequest(
    imap_folder_name, imap_account, "('From' Contains '.com')",
    storage_name, account_folder, True, 'Dto'))

Ruby

imap_folder_name = 'INBOX'
messages = api.client.message.list(ClientMessageListRequest.new(
  folder: imap_folder_name,
  account: imap_account,
  query_string: "('From' Contains '.com')",
  storage: storage_name,
  account_storage_folder: account_folder,
  recursive: true,
  type: 'Dto'))

Typescript

const imapFolderName = 'INBOX';
const messages = await api.client.message.list(new ClientMessageListRequest(
    imapFolderName, imapAccount, "('From' Contains '.com')",
    storageName, accountFolder, true, 'Dto'));

PHP

$imapFolderName = 'INBOX';
$messages = $api->client()->message()->list(new ClientMessageListRequest(
    $imapFolderName, $imapAccount, "('From' Contains '.com')",
    $storageName, $accountFolder, true, 'Dto'));

Fetch Message By Id

In the previous step, we have got a list of emails. Let’s fetch one of them by its Id.

To do this you should use the email’s Id, obviously, and FetchAsync method from ClientMessageApi. This method requires 1 parameter — ClientMessageFetchRequest, which is a request model for this operation. ClientMessageFetchRequest has the following parameters:

MessageId — Message identifier.
Account — Email account.
Folder — Account folder to fetch from (should be specified for some protocols such as IMAP).
Storage — Storage name where account file(s) located.
AccountStorageFolder — Folder in storage where account file(s) located.
Type - Using this property you can get messages in different formats (as EmailDto, MapiMessageDto or a file represented as Base64 string).
Format - Base64 data format. Used only if Type is set to Base64.

Аfter this operation you will receive an email as an object inherited from MailMessageBase.

Fetch found message by id

var foundMessage = messages.Value.First() as MailMessageDto;
var id = foundMessage.Value.MessageId;
var message = await Api.Client.Message.FetchAsync(new ClientMessageFetchRequest(
    id, imapAccount, null, storageName, accountFolder));

Java

MailMessageDto foundMessage = (MailMessageDto) messages.getValue().get(0);
String id = foundMessage.getValue().getMessageId();
MailMessageDto message = (MailMessageDto) api.client().message().fetch(
    new ClientMessageFetchRequest(
        id, imapAccount, null,
        storageName, accountFolder, "Dto", null));

Python

found_message = messages.value[0]   # type: models.MailMessageDto
id = found_message.value.message_id
message = api.client.message.fetch(models.ClientMessageFetchRequest(
    id, imap_account, None, storage_name, account_folder, 'Dto'))

Ruby

found_message = messages.value[0]
id = found_message.value.message_id
message = api.client.message.fetch(
  ClientMessageFetchRequest.new(
    message_id: id,
    account: imap_account,
    storage: storage_name,
    account_storage_folder: account_folder,
    type: 'Dto'))

Typescript

const foundMessage = messages.value[0] as MailMessageDto;
const id = foundMessage.value.messageId;
const message = await api.client.message.fetch(new ClientMessageFetchRequest(
    id, imapAccount, undefined, storageName, accountFolder, 'Dto'));

PHP

$id = $messages->getValue()[0]->getValue()->getMessageId();
$message = $api->client()->message()->fetch(new ClientMessageFetchRequest(
    $id, $imapAccount, null, $storageName, $accountFolder, 'Dto'));

Mark Message as Read

You need to know message’s Id to mark it as read. We have done it in previous steps.

To mark a message as read use SetIsReadAsync from ClientMessageApi. This method requires 1 parameter — ClientMessageSetIsReadRequest, which is a request model for this operation.

ClientMessageSetIsReadRequest has 3 parameters:

AccountLocation — Account location on storage.
MessageId — Message identifier.
IsRead — Specifies that message should be marked read or unread.

Mark message as read

await api.Client.Message.SetIsReadAsync(
    new ClientMessageSetIsReadRequest(
        imapLocation, id, true));

Java

api.client().message().setIsRead(
    new ClientMessageSetIsReadRequest(
        imapLocation, id, true));

Python

api.client.message.set_is_read(
    models.ClientMessageSetIsReadRequest(
        imap_location, id, True))

Ruby

api.client.message.set_is_read(
  ClientMessageSetIsReadRequest.new(
    account_location: imap_location,
    message_id: id,
    is_read: true))

Typescript

await api.client.message.setIsRead(
    new ClientMessageSetIsReadRequest(
        imapLocation, id, true));

PHP

$api->client()->message()->setIsRead(
    new ClientMessageSetIsReadRequest(
        $imapLocation, $id, true));

Delete Message

In an attempt to manage your messages, you may need to delete some of them. To remove a message, you should know the Id of the email you want to delete.

To delete email use DeleteAsync from ClientMessageApi. This method requires 1 parameter — ClientMessageDeleteRequest, which is a request model for this operation.

ClientMessageDeleteRequest requires the following parameters:

AccountLocation — Account location on storage.
MessageId — Message identifier.
Folder — Folder to delete message from.

await api.Client.Message.DeleteAsync(
    new ClientMessageDeleteRequest(
        imapLocation, id, imapFolderName));

Java

api.client().message().delete(
    new ClientMessageDeleteRequest(
        imapLocation, id, imapFolderName));

Python

api.client.message.delete(models.ClientMessageDeleteRequest(
    imap_location, id, imap_folder_name))

Ruby

api.client.message.delete(
  ClientMessageDeleteRequest.new(
    account_location: imap_location,
    message_id: id,
    folder: imap_folder_name))

Typescript

await api.client.message.delete(new ClientMessageDeleteRequest(
    imapLocation, id, imapFolderName));

PHP

$api->client()->message()->delete(
    new ClientMessageDeleteRequest(
        $imapLocation, $id, $imapFolderName));

Append new message

To append a new message to your email account — use AppendAsync from ClientMessageApi. This method requires 1 parameter — ClientMessageAppendRequest, which is a request model for this operation.

ClientMessageAppendRequest requires the following parameters:

AccountLocation — Account location on storage.
Folder — Path to folder on email server to append message to.
MarkAsSent — Mark message as sent.
Message — Email document.

var emailToAppend = new EmailDto
{
    From = new MailAddress{Address = "example@gmail.com"},
    To = new List<MailAddress> {new MailAddress{Address = "to@aspose.com"}},
    Subject = "Some subject",
    Body = "Some body"
};

var appendedMessageId = await api.Client.Message.AppendAsync(
    new ClientMessageAppendRequest(
        imapLocation, imapFolderName,
        new MailMessageDto(emailToAppend), true));

Java

EmailDto emailToAppend = new EmailDto()
    .from(new MailAddress().address("example@gmail.com"))
    .addToItem(new MailAddress().address("to@aspose.com"))
    .subject("Some subject")
    .body("Some body");
ValueTOfString appendedMessageId = api.client().message().append(
    new ClientMessageAppendRequest(
        imapLocation, imapFolderName,
        new MailMessageDto(emailToAppend), true));

Python

email_document = models.EmailDto(
    _from=models.MailAddress('From Name', 'example@gmail.com'),
    to=[models.MailAddress('To Name', 'to@aspose.com')],
    subject='Some subject',
    body='Some body')
appended_message_id = api.client.message.append(
    models.ClientMessageAppendRequest(
        imap_location, imap_folder_name,
        models.MailMessageDto(email_document), True))

Ruby

email = EmailDto.new(
  from: MailAddress.new(address: 'example@gmail.com'),
  to: [MailAddress.new(address: 'to@aspose.com')],
  subject: 'Some subject',
  body: 'Some body'
)
appended_message_id = api.client.message.append(
  ClientMessageAppendRequest.new(
    account_location: imap_location,
    folder: imap_folder_name,
    message: MailMessageDto.new(value: email),
    mark_as_sent: true))

Typescript

const email = new EmailDto();
email.from = new MailAddress('From address', 'example@gmail.com');
email.to = [new MailAddress('To address', 'to@aspose.com')];
email.subject = 'Some subject';
email.body = 'Some body';
const appendedMessageId = await api.client.message.append(
    new ClientMessageAppendRequest(
        imapLocation, imapFolderName,
        new MailMessageDto(email), true));

PHP

$email = (new EmailDto())
    ->setFrom(new MailAddress("Organizer Name", "example@gmail.com"))
    ->setTo(array(new MailAddress("Attendee Name", "to@aspose.com")))
    ->setSubject("Some subject")
    ->setBody("Some body");
$appendedMessageId = $api->client()->message()->append(
    new ClientMessageAppendRequest(
        $imapLocation, $imapFolderName,
        new MailMessageDto($email), true));

Setup email account for sending messages

All you have to do to setup your email account for sending messages is to use SaveAsync from ClientAccountApi. This method requires 1 parameter — ClientAccountSaveRequest, which is a request model for this operation.

ClientAccountSaveRequest requires the following parameters:

Value — EmailClientAccount object.
StorageFile — StorageFileLocation object.

var sendAccountDto = new EmailClientAccount
{
    Host = "smtp.gmail.com",
    Port = 465,
    ProtocolType = "SMTP",
    SecurityOptions = "SSLAuto",
    Credentials = credentials
};
var smtpAccount = "smtp.account";
var smtpLocation = new StorageFileLocation(
    storageName, accountFolder, smtpAccount);

await Api.Client.Account.SaveAsync(new ClientAccountSaveRequest(
    smtpLocation, sendAccountDto));

Java

EmailClientAccount sendAccountDto = new EmailClientAccount(
    "smtp.gmail.com", 465, "SSLAuto", "SMTP", credentials);
String smtpAccount = "smtp.account";
String smtpLocation = new StorageFileLocation(
    storageName, accountFolder, smtpAccount);
api.client().account().save(new ClientAccountSaveRequest(
    smtpLocation, sendAccountDto));

Python

send_account_dto = models.EmailClientAccount(
    'smtp.gmail.com', 465, 'SSLAuto', 'SMTP', credentials)
smtp_account = 'smtp.account'
smtp_location = models.StorageFileLocation(
    storage_name, account_folder, smtp_account)

api.client.account.save(
    models.ClientAccountSaveRequest(
        smtp_location, send_account_dto))

Ruby

send_account_dto = EmailClientAccount.new(
  host: 'smtp.gmail.com',
  port: 465,
  security_options: 'SSLAuto',
  protocol_type: 'SMTP',
  credentials: credentials)
smtp_account = 'smtp.account'
smtp_location = StorageFileLocation.new(
  storage: storage_name,
  folder_path: account_folder,
  file_name: smtp_account)
# Save account
api.client.account.save(ClientAccountSaveRequest.new(
  storage_file: smtp_location, value: send_account_dto))

Typescript

const sendAccountDto = new EmailClientAccount(
    'smtp.gmail.com', 465, 'SSLAuto', 'SMTP', credentials);
const smtpAccount = 'smtp.account';
const smtpLocation = new StorageFileLocation(
    storageName, accountFolder, smtpAccount);

await td.api().client.account.save(
    new ClientAccountSaveRequest(smtpLocation, sendAccountDto));

PHP

$sendAccountDto = new EmailClientAccount(
    "smtp.gmail.com", 465, "SSLAuto", "SMTP", $credentials);
$smtpAccount = "smtp.account";
$smtpLocation = new StorageFileLocation(
    $storageName, $accountFolder, $smtpAccount);

$api->client()->account()->save(
    new ClientAccountSaveRequest($smtpLocation, $sendAccountDto));

Send Email

To send a message using your email account — use SendAsync from ClientMessageApi. This method requires 1 parameter — ClientMessageSendRequest, which is a request model for this operation.

ClientMessageSendRequest requires the following parameters:

AccountLocation — Account location on storage.
Message — Email document to send.

var email = new EmailDto
{
    From = new MailAddress {Address = "example@gmail.com"},
    To = new List<MailAddress> {new MailAddress {Address = "to@aspose.com"}},
    Subject = "Some subject",
    Body = "Some body"
};
await api.Client.Message.SendAsync(
    new ClientMessageSendRequest(
        smtpLocation, new MailMessageDto(email)));

Java

EmailDto email = new EmailDto()
    .from(new MailAddress().address("example@gmail.com"))
    .addToItem(new MailAddress().address("to@aspose.com"))
    .subject("Some subject")
    .body("Some body");
api.client().message().send(
    new ClientMessageSendRequest(
        smtpLocation, new MailMessageDto(email)));

Python

email_document = models.EmailDto(
    _from=models.MailAddress('From Name', 'example@gmail.com'),
    to=[models.MailAddress('To Name', 'to@aspose.com')],
    subject='Some subject',
    body='Some body')
api.client.message.send(
    models.ClientMessageSendRequest(
        smtp_location, models.MailMessageDto(email_document)))

Ruby

email = EmailDto.new(
  from: MailAddress.new(address: 'example@gmail.com'),
  to: [MailAddress.new(address: 'to@aspose.com')],
  subject: 'Some subject',
  body: 'Some body'
)

api.client.message.send(
  ClientMessageSendRequest.new(
    account_location: smtp_location,
    message: MailMessageDto.new(value: email)))

Typescript

const email = new EmailDto();
email.from = new MailAddress('From address', 'example@gmail.com');
email.to = [new MailAddress('To address', 'to@aspose.com')];
email.subject = 'Some subject';
email.body = 'Some body';
await api.client.message.send(
    new ClientMessageSendRequest(
        smtpLocation, new MailMessageDto(email)));

PHP

$email = (new EmailDto())
    ->setFrom(new MailAddress("Organizer Name", "example@gmail.com"))
    ->setTo(array(new MailAddress("Attendee Name", "to@aspose.com")))
    ->setSubject("Some subject")
    ->setBody("Some body");
$api->client()->message()->send(
    new ClientMessageSendRequest(
        $smtpLocation, new MailMessageDto($email)));

Quick Start With Email Client

Built-In Email Client

How to Work With Email Client

Setup email account

Search Emails

Fetch Message By Id

Mark Message as Read

Delete Message

Append new message

Setup email account for sending messages

Send Email

More Tutorials