Edit

Email and EWS in Exchange

  • Article

Find out how to work with email messages, including how to create an email and how to perform other email-related tasks by using the EWS Managed API or EWS in Exchange.

At its core, Exchange is about email. But what makes an email an email? Well, email messages are one of the strongly typed items in Exchange, which means that they contain a particular set of properties, even before they're sent. Email messages are represented by the EmailMessage class in the EWS Managed API and by the Message element and its child elements in EWS.

In the EWS Managed API, the EmailMessage object derives from the Item object. The EmailMessage class extends the Item class by providing additional properties like EmailMessage.Sender and EmailMessage.IsRead, which are now common to nearly all messaging scenarios. When you get, update, or delete an email message, in most cases you can do that by using the EmailMessage object or the base Item object, depending on whether the properties you're working with are in the EmailMessageSchema or the ItemSchema class. Item creation is different because the Item class does not have a constructor, so when you're creating an email, you'll use the EmailMessage constructor to create it and the EmailMessage.Save or EmailMessage.SendAndSaveCopy methods to save it, or send it and save it.

Similarly, in EWS, use the CreateItem operation with the Message element to create an email message. To get, update, or delete emails by using EWS, the fact that the item being modified is an email message is not important, aside from the fact that additional properties are available on email messages. The same operations that are used for other strongly typed items are also used for email messages.

Task EWS Managed API method EWS operation
Create
EmailMessage.Save
CreateItem
Get
EmailMessage.Bind
GetItem
Update
Item.Update
UpdateItem
Delete
Item.Delete
DeleteItem

Because email messages are simply strongly typed items, in some cases you work with them in the same way that you work with generic items.

Create an email message by using the EWS Managed API

You can create an email message by using the EWS Managed API Save method, as shown in the code in the following example. Note that the example only saves the message in the Drafts folder, it does not send the message. For information about how to send the message or create and send the message in one step, see Send email messages by using EWS in Exchange.

This example assumes that service is a valid ExchangeService object and that the user has been authenticated to an Exchange server.

// Create a new email message.
EmailMessage message = new EmailMessage(service);
// Set properties on the email message.
message.ToRecipients.Add("mack@contoso.com");
message.Subject = "Project priorities";
message.Body = "(1) Buy pizza, (2) Eat pizza";
// Save the email message to the Drafts folder (where it can be retrieved, updated, and sent at a later time).
// This method call results in a CreateItem call to EWS.
message.Save(WellKnownFolderName.Drafts);
Console.WriteLine("A draft email message with the subject '" + message.Subject + "' has been saved to the Drafts folder.");

Create an email message by using EWS

You can create an email message by using the EWS CreateItem operation, as shown in the following example. This is also the XML request that the EWS Managed API sends when you create an email message. Note that the following example only saves the message in the Drafts folder, it does not send the message. For information about how to send the message or create and send the message in one ste, see Send email messages by using EWS in Exchange.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2010_SP2" />
  </soap:Header>
  <soap:Body>
    <m:CreateItem MessageDisposition="SaveOnly">
      <m:SavedItemFolderId>
        <t:DistinguishedFolderId Id="drafts" />
      </m:SavedItemFolderId>
      <m:Items>
        <t:Message>
          <t:Subject>Project priorities</t:Subject>
          <t:Body BodyType="HTML">(1) Buy pizza, (2) Eat pizza</t:Body>
          <t:ToRecipients>
            <t:Mailbox>
              <t:EmailAddress>mack@contoso.com</t:EmailAddress>
            </t:Mailbox>
          </t:ToRecipients>
        </t:Message>
      </m:Items>
    </m:CreateItem>
  </soap:Body>
</soap:Envelope>

The server responds to the CreateItem request with a CreateItemResponse message that includes a ResponseCode value of NoError, which indicates that the email was created successfully, and the ItemId of the newly created message.

Get, update, and delete an email message by using the EWS Managed API

You can use the EWS Managed API to get, update, or delete an email message in the same way that you perform these actions on any generic item from the Exchange store. For more information, see Work with Exchange mailbox items by using EWS in Exchange.

If you're updating an email message, see Email properties and elements in EWS in Exchange for a list of writable email message properties. To send a draft message after you've updated it, see Send a draft email message by using the EWS Managed API.

Get, update, and delete an email message by using EWS

You can use EWS to get, update, and delete an email message in the same way that you perform these actions on any generic item from the Exchange store. For more information, see Work with Exchange mailbox items by using EWS in Exchange.

If you're updating an email message, see Email properties and elements in EWS in Exchange for a list of writable email message properties. To send a draft message after you've updated it, see Send a draft email message by using EWS.

In this section

See also