Guide to Common Solutions

The system has a fully featured API meaning anything you do in the applications interface can be achieved programatically. This guide provides Developers with a brief introduction into the system and solutions to common API tasks.

Key Concepts & Terms

Emails

Emails are of course the messages we are sending out. We have 3 types:

  • Campaign Emails - these are emails sent to a batch of users on a one off basis such as a newsletter
  • Recurring Emails - these are emails typically sent every day to a batch of recipients. Such as birthday emails, a request a review email or a 30 day reminder email. Typically the content of these emails stays the same every day, but the recipients change each day.
  • Trigger Emails - these are instantaneous emails sent to a single recipient on the receipt of the API command

Campaigns/Split Tests

A Campaign or Split Test is a level above emails, used for running A/B tests. This level ensures that any emails within this are controlled at who they go to. A recipient will only be able to receive a single one of these emails, simplifying the list management for the user.

Folders

Maxemail has a 'MS Windows' style folder system for organising any item or asset. Any number of sub-folders can be used to ensure the interface is tidy and free of clutter. Permissions can also be set on folders to restrict which users can access or edit the contents within the folders. When creating emails, lists or other assets using the API there is usually a simple option to specify a folder ID of where to create the item.

Lists

Lists are a group of email addresses. For example you may have a list for your newsletter, a list for press contacts and so on. Recipients can appear on any number of lists, however the email address and their associated profile data is only stored once in Maxemail. Therefore you can never have a scenario where an email address has 2 different first names.

Maxemail automatically de-dupes on import, plus when using multiple lists on a campaign.
Maxemail also has the concept of include and suppression lists. Include list types are people you wish to send to, exclude people you wish to not send the email to. Exclude lists always take priority over include lists.
Lists can be maintained in Maxemail by appending to them rather than the need to create multiple lists each time you load new data in.

Profile data

Profile data is sets of fields you wish to store data about an email address to, such as name, newsletter preferences and other useful information used to personalise and target emails with.

Unsubscribes

Maxemail has functions to automatically handle unsubscribes. There are 2 types; Local and Global. Inserting into an email a local unsubscribe link will only unsubscribe them from the list the email was sent to. If this is used then you should ensure you maintain the list in Maxemail rather than load new lists each time, otherwise you will keep sending to unsubscribed recipients.

If you use the Global Unsubscribe it will unsubscribe the recipient from all lists, and add them to a Global Suppression list that is used on all email sends. This is the recommended method.

Segments

These are rules which are used to select who within your list the email should be sent to. They are optional, but provide the user with greater control. Examples might include:

  • Only send where 'Gender' field = 'Male'
  • Only send where 'Registration Date' = 3 days ago

Developers can take advantage of segments as they allow Maxemail to make decisions on who to send to, rather than filtering the data that is pushed into Maxemail.

Snippets & Dynamic Content Rules

Snippets are blocks of HTML and Text that can be inserted into an email. These are usually used as part of a dynamic content rule where different snippets are merged into the email depending on what you know about each recipient.

Solutions to Common Automation Projects

Uploading data lists

Developers need to make a choice as to how they manage their data in conjunction with Maxemail before proceeding. This usually involves a decision between maintaining a single list within Maxemail, or creating a brand new list each time.

Our recommendation is where possible to maintain a single list in Maxemail and update this on a regular basis. This is because:

  • Maxemail can handle unsubscribe preferences for you - creating a new list every time negates some of the useful functionality
  • It is less work on your part, particulary if an email is to be triggered on the back of the import as the user can template the email with the single list attached rather than this be all handled by you the developer
  • It keeps the number of lists, and therefore clutter in the interface down. From experience this reduces the likelihood of user error

If you are managing subscriptions outside Maxemail, then your subscription and unsubscribe processes should add the recipient to your primary list (or subscription-type list), or set the recipient's subscription flag to false on that list, respectively. Please see the list.insertRecipient and list.updateRecipient methods. You could even add unsubscribe complaints directly to the Global Unsubscribe List, so that it's impossible to send any emails to the recipient from your Customer Space.

If you do decide to create a new list each time use a folder as this ensures the clutter in the interface is minimised. We do not recommend deleting lists.

Triggering emails instantly

As Triggered Emails are often used following subscriptions, the email_send.trigger method reduces the import of the recipient and the sending of the Triggered Email to a single command. You simply define the email address, any associated profile data (such as name) and the email to trigger. The recipient will be added to your Customer Space if it doesn't already exist, the profile data set, and the email to them queued for send.

You can store whole blocks of content in a profile field but this is not recommended. This is because the content will not be rendered and any links within these will not be tracked. For this it is better to create a content snippet which can be merged into the email. This must be done before the trigger command.

One issue to be aware of is Maxemail will only send a triggered email once it has been set to approved. If you find your test commands are not sending through an email this is the place to look first.

Scheduling a daily email

There are 2 key scenarios:

  • You need to send the same content each day to a different list of recipients
  • You need to create an email with different content every day, to the same or different people

If you are looking at scenario 1, then we suggest you create the email as a 'Recurring Email' in Maxemail. If the frequency setting is disabled (can be easily done in the interface) then you can update your list each day, and then once this is imported, set the recurring email's next run time to the time you wish to send the email, so the system will automatically deal with the rest. This dramatically reduces the number of calls you need to make, while still allowing users to control the email via the user interface, even disabling it by removing the email from approved status. While testing your code we recommend keeping the email in draft status so no emails will be sent. You can see if the process has worked correctly by looking at the next run timestamp in the email's 'Recurring' tab within Maxemail.

If scenario 2 is required then again we would recommend a normal email. You would need to specify all the details of this email (email headers, HTML content, lists to assign, segments, etc.) and then schedule it.

With both of these scenarios a common mistake is to not ensure all processes are complete before sending the email. Eg.: the list is still importing when you schedule the email; or you have not created all of the content. A quick solution is to schedule the email for a period of time when this will definitely be ready, or a more robust solution to poll the list status and only send when the import is complete.

Creating content to merge into an email

Maxemail enables you to create content that can be pulled into an email, rather than having to populate each recipients profile data with the content details to merge. This can help reduce the amount of data transfer involved.

For example, you might want to merge in the product details of their latest purchase. In the customer record you can include a product ID, and you can create a content snippet containing the block of HTML and text for that product. If you need to merge more than one product ID you can store multiple product IDs in a single profile field as a concatanated string (Eg. 12,45,68). Maxemail has the capability to merge in a specific product snippet based upon its position in the string.

Most developers will be comfortable with over-writing the content snippet each time the content changes. However there will be the need on occassions to keep content snippets as they were. In this instance we recommend creating content snippets in date folders, and within the email we can refer to the snippet by using a dynamic date tag.

Another common mistake made by developers is sending emails to recipients even if there is no content for them that match their profile, resulting in blank sections of the email. For example, a project for a daily news service allowed customers to subscribe to several different topics - if there was no news for that topic nothing would be merged in. If the recipient was only subscribed to topics with no content, they would receive a blank email! The list must be filtered so the only people to be sent an email are those who are subscribed to sections with new content. This could be achieved by only populating the list with these people, or by creating a segment to filter the list.

Downloading Reporting Data

Typically this can be catergorised into 2 types of requests:

  • List cleansing information - bounces and unsubscribes
  • Who was sent/opened/clicked on what

Any information can be tracked by Maxemail can be extracted but typically these are the key examples.

For scenario 1, if you don't need to know which email campaign the bounce or unsubscribe was against then we recommend using the Quick Data Export service. This allows you to specify a date range for bounce and unsubscribe activity. Therefore you can configure your code to only report on the bounces or unsubscribes since the last time you requested the information.

In scenario 2, typically it is more important to build up a history of who received what email, and what actions they did with that email (bounced, opened, clicked, what they clicked on, conversion/revenue activity).

The key to this is to have a database structure that stores this information. This is a traditional relational database structure.

It is importants to ensure that the frequency and number of requests are controlled, as too much and/or too often might cause the user account to be suspended. We recommend an early AM process to gather the stats you require from the previous day.

Further Information & Support

Full details of the available API functions are available within the User Manual. To arrange support and guidance through your Integration & Automation project contact your Account Manager to facilitate this.