Manage lists and send transactional or commercial email

 

Applies To: Dynamics Marketing

Microsoft Dynamics Marketing provides external APIs for sending and managing transactional marketing email or commercial (promotional) marketing email. It also enables external systems to manage lists and their member contacts.

Transactional email is sent to individuals rather than to a large list of recipients and contains information that completes a transaction or process the recipient has started. An example of transactional email is the email receipt that you receive after completing your online shopping. The receipt contains information about the item, price, method of payment, and shipment details.

Commercial email is generally sent to groups of contacts that are prospects or customers. Commercial marketing emails offers "one-to-many" emails, usually with a list, and allows the sender to choose what, when, and how the content will be delivered. You can retrieve a list of commercial email marketing messages that are marked “Send Externally” by using RetrieveCommercialEmailMessagesRequest class, or send a commercial email marketing message using SendCommercialEmailMessageByIdRequest class.

Using list management and segmentation features you can perform a variety of tasks related to contact lists. These features are a key element of the marketing database functions in Microsoft Dynamics Marketing. More information:  Perform list management and segmentation

Note

Before you use Microsoft Dynamics Marketing APIs to create transactional or commercial emails, ensure that API is enabled on your Dynamics Marketing instance. More information: Getting started with the SDK. For more information on how to create and set transactional or commercial emails in Dynamics Marketing, see Validate, test and send messages.

The Microsoft Azure Service Bus is used as the communication channel and endpoint for sending and receiving the API messages and for facilitating queuing of external API requests in a similar way that Microsoft Dynamics Marketing Connector for Microsoft Dynamics CRM does. The Azure Service Bus accommodates the Microsoft Dynamics Marketing authentication and authorization model and can be used in external systems to send and receive messages about email requests and responses. More information:** ** Site configuration and integration settings

The following image shows how the Azure Service Bus is used as the communication channel and endpoint for sending and receiving the API messages.

Microsoft Dynamics Marketing communication channel

You can use APIs to send email, and then use OData feeds or the Microsoft Dynamics Marketing user interface to look at the established key indicators such as opens, bounces, and clicks to track and analyze the performance of email marketing.

The list API allows external systems to control lists through segments. Using this API, external systems can create, update, and delete lists, as well as add or remove members from lists.

With the transactional email API you can include external data from client systems, send emails with dynamic promotional content, and track the emails’ performance. An external system can use the transactional email API to do the following actions:

  • Send email using either an email address or contact identifier.

  • Set the priority of an email message.

  • Specify external data (for example, order, product, or pricing information) to be embedded in the email.

  • Track queuing and response status.

  • Retrieve a list of email marketing messages that can be used in a transaction.

In addition, you can set contact permissions for an email address or for multiple email addresses to receive particular types of information. For example, a given contact or contact group can be marked to receive only transactional mail, or only promotional mail, or both. You can add any combination of contact permissions to email addresses and categorize them to receive a particular type of information. You can create new category values, extend them or modify them as required, and Dynamics Marketing takes care of synchronizing these values to send emails as per the defined frequency.

Commercial email APIs offers another way of sending emails to the target audience based on the EmailMessage request group set in the Site configuration and integration settings. Any given commercial email can be sent multiple times to the target audience. For example, you could set the custom field “CreditCardBounced” on the contact record and create a query to identify users whose credit card has bounced, and then send them emails to inform them about the incident. To ensure that the emails are sent only to the target audience, email message sending is triggered only for the flagged contacts. Depending on your requirements, you can write and use customized script to reset the flags and refresh marketing lists or queries to avoid sending multiple emails to the same contact. If the commercial mail is using a query, you just need to set relevant conditions on each contact record.

In addition, you can set contact permissions for an email address or for multiple email addresses to receive particular types of information. For instance, a given contact or contact group can be marked to receive only transactional mail, or only promotional mail, or both. You can add any combination of contact permissions to email addresses and categorize them to receive a particular type of information. You can create new category values, extend them or modify them as required, and Dynamics Marketing takes care of synchronizing these values to send emails as per the defined frequency.

The SetContactPermissionsRequest class and SetContactsPermissionsRequest class are available to help you specify contact permissions for an email address or for multiple email addresses. In addition, you can use the RetrieveContactPermissionsRequest class to get the contact permissions for an email address, or the RetrieveMissingContactPermissionsRequest class to retrieve a list of email addresses that contact permissions are missing from. To get a demonstration on how to set contact permissions for single and multiple email addresses, retrieve contact permissions for an email address, or retrieve a list of email addresses that have missing contact information, see Sample: Manage lists and send transactional or commercial email.

See Also

Microsoft.Dynamics.Marketing.SDK.Messages.EmailMessage
Developer overview of Microsoft Dynamics Marketing
Getting started with the SDK
Quick start with sample code
Sample code
Sample: Manage lists and send transactional or commercial email
Assembly included in the Microsoft Dynamics Marketing SDK
Web service and assembly reference