Introduction to Our API

Description

Structure and Overview of the XML Messages Used by the API

Mapp's Application Programming Interface (API) relies completely on an XML message transmitted via secure hypertext transfer protocol (HTTPS) using the POST command.

All XML messages are POSTed to https://echo.bluehornet.com/api/xmlrpc/index.php. In the HTTP request header, be sure to explicitly identify the Content-Type as "application/x-www-form-urlencoded".

The entire XML message required by each API method is communicated in the HTTP POST command as a single name-value pair where the name of the parameter is "data" and the value of the parameter is the entire XML message that must be URL-encoded. Failure to pass the XML message as the value associated with the "data" parameter is the number one source of error.

If you are accessing our API via your own CNAME, then you must ensure that the CNAME has its own valid security certificate.

To see if your account is enabled for API integration, please contact your Mapp account manager, or Technical Support at https://mapp.com/tech-support/. If you are new to Mapp, contact americas@mapp.com to learn how Empower Enterprise can help you manage powerful email marketing programs.

As part of Mapp's security protocol all remote IP addresses used to connect via the API must be whitelisted with our network.

Understanding the structure of the XML that our API accepts is key to your implementation. All XML messages are wrapped within the <api> root. Directly inside this root element are the two elements that communicate the bulk of your XML message: the <authentication> and the <data> elements. The authentication element contains your account-specific information associated with each method call. The data element contains the information of the actual method call. ( NOTE: The data element contained within the XML message is not the same thing as the "data" parameter that must be included in the POST command.)

The basic structure of the XML message is as follows:

After each POST, the Empower Enterprise platform will return either a response message providing confirmation details specific to the method invoked, or it will return an error message specific to the method invoked and the reason for the failure.

Mapp's API enables you to manage both promotional emails and transactional emails. All of the methods from the Legacy class are used for promotional emails and all the methods from the Transactional class are used for transactional emails.

Sending a Promotional Email

To send a promotional email, use the legacy.send_campaign method. Here's where you specify the recipients for the message, the content of the message (both HTML and plain text), and when you want the message to be sent. The assumption of this method call is that you want to send an email using content generated from your content management system to a segment of your subscriber database that you've already defined within Empower Enterprise.

Retrieving Email Performance Metrics

Use the legacy.message_stats method to receive a full set of performance metrics for a given message. The returned metrics include sends, delivered, bounces, opens, clicks, and a variety of information about the message including campaign, targeted segments, bill codes and more.

Adding An Individual to Your Subscriber Database

To add an individual to your subscriber database (as in the case of someone opting in to receive promotional emails from your web site, mobile text-to-opt-in, social site signup widget, etc.) then use legacy.manage_subscriber method. This method not only enables you to add profile information and email preferences, you can also use it to identify the URL of the sign up page, the Refer-a-Friend program the sign-up came from (if applicable), any custom field values that you want to capture, and any pre-defined segments that you want to add the individual to. Finally, this method call lets you determine whether to send a double opt-in confirmation email and also whether to send a Welcome email to the individual.

Uploading a List of Subscribers

The legacy.bulk_sync method lets you upload a list of individuals that can include both new and existing subscribers. You would typically use this method when:

• your method of collecting promotional email opt-ins is not directly integrated with Empower Enterprise,
• you have your own management system to perform customer segmentation and you want to load this segment into Empower Enterprise, and
• you want to update your subscriber database within Empower Enterprise with additional and/or updated profile information.

The process to follow is that you have a list of subscribers in a text file that resides on an HTTP(s) or FTP server and you are instructing Empower Enterprise to pull the file and upload it into your subscriber database. This method enables you to define the file's column headers which includes any pre-defined custom fields. You can also specify any pre-defined segments that you want to add the subscribers to, and whether to send a double opt-in confirmation or a Welcome email.

Opting Out Subscribers

To unsubscribe an individual person from your database, use the legacy.manage_subscriber method. To unsubscribe a group of subscribers contained within a list, use the legacy.delete_subscribers method.

Synchronizing Your Customer Profile Data Fields

You can create, edit, and delete custom fields using the account.addCustomField, account.updateCustomField, and account.removeCustomField methods respectively.

Currently, you can only create custom fields having either a string or a date data type. Support for other data types such as integer and float is forthcoming, but not just yet. When you create a new custom field, you can also provide a default value that should appear in the body of an email containing the custom field in the event that a particular customer record does not have a value of its own for that field. This method will return a Field ID that your system will reference when updating or removing that field via the API.

By using the account.updateCustomField method, you can change the friendly name of the custom field, its data type and whether or not the field should be displayed in the hosted sign-up page.

The account.getCustomFields method returns the full list of custom fields configured for your account. This is a handy method to call if you are integrating your application with Empower Enterprise and you want to display the list of custom fields from your customer database in Empower Enterprise within your application. This method lets you specify how many custom fields to include in the result set and the offset – a handy feature if you are using paging within your application's user interface.

Synchronizing Your Customer Segmentation

You can create, edit, and delete static segments using the account.addStaticSegment, account.updateStaticSegment, and account.removeStaticSegment methods respectively.

When you create a new static segment, you can specify which category you want to associate the segment with, and whether or not the segment should appear in the online registration page. The account.addStaticSegment method returns a segment ID that your system will reference when updating or removing that segment via the API. Static segments can also be flagged as "test segments" and as such, they will become available for use when you want to send test messages to a specific audience during your message QA process.

The account.getStaticSegments method returns the full list of static segments configured for your account. This is a handy method to call if you are integrating your application with Empower Enterprise and you want to display the list of segments from your customer database in Empower Enterprise within your application. This method lets you specify how many static segments to include in the result set and the offset – a handy feature if you are using paging within your application's user interface.

Categories are logical groupings of static segments displayed within survey pages and sign up forms. For example, a category could be called "Music Preferences" with four static segments associated with it, "Rock Genre", "Jazz", "Blues", and "Classical". A person who selects "Rock Genre" in the "Music Preference" category then becomes added to the "Rock Genre" static segment. Use the account.addCategory, account.updateCategory, and account.removeCategory methods to create, edit, and delete categories respectively. Use the account.updateStaticSegment method if you want to associate an existing static segment with a category, change the existing category association to a new one, or to change it to an uncategorized static segment. You can always specify what category a new static segment should be associated with using the account.addStaticSegment method also.

Sending a Transactional Email

While the definition of a promotional email is self-explanatory, a transactional email tends to be loosely defined. Here at Mapp, we strictly adhere to the definition of a transactional email according to the CAN-SPAM Act. Specifically, a transactional message consists only of content that:

• facilitates or confirms a commercial transaction that the recipient already has agreed to;
• gives warranty, recall, safety, or security information about a product or service;
• gives information about a change in terms or features or account balance information regarding a membership, subscription, account, loan or other ongoing commercial relationship;
• provides information about an employment relationship or employee benefits; or
• delivers goods or services as part of a transaction that the recipient already has agreed to.

Furthering the distinction between promotional and transactional emails, Empower Enterprise can send transactional emails to anyone – including those that are not included within your email marketing database.

Empower Enterprise is a highly scalable and highly flexible platform for sending transactional emails. There are two stages for transactional messages: (1) draft template, and (2) live template. The reason for these two stages is because transactional message templates are cached in memory to ensure high availability since expectations are that Empower Enterprise sends the transactional email immediately when commanded to do so.

Sending a transactional message is a two-step process. First you create a transactional message template. Then, you trigger the creation of the transactional email and its immediate send using the template you've previously created.

You can create transactional message templates two ways. First, use the transactional.insertTemplate method call to upload the HTML and plain text content which creates both the draft and the live version of the message. Second, you can create and manage the transactional message template by logging into Empower Enterprise and selecting Messages > Transactional Messages > Create Transactional Template. Naturally, the vast majority of all transactional emails will require some degree of personalization. Mapp's Transactional Messaging platform implements the open-source Smarty template/presentation framework.

To send the transactional email, use the transactional.sendTransaction method call. Here's where you will pass in the data values for any personalization used within the body of the email. This method will also enable you to automatically subscribe the recipient of the transactional email for your promotional emails provided that this person has explicitly opted in to receiving your promotional emails during the purchase process.

Any changes that you need to make to a transactional message template are uploaded using the transactional.updateTemplate method call. To protect the integrity of the live transactional message template, updates are only made to the draft version. To promote the draft to the live version, use the transactional.rebuildTemplate method call.

---