REST Email Marketing API Documentation

INTRODUCTION

This is the documentation for the REST version of the APIs for Symphonie. The REST interface is modern and easy to use from a variety of programming and scripting languages. The REST interface for Symphonie allows a great deal of control over the application, enabling you to create new items (such as mailings or recipients), extract information about opens, clickthroughs, deliverability, and more, plus allows data to be extracted for reporting or other purposes. It is possible to automate a great deal of functionality through the API, although, keep in mind, Symphonie has features that are too complex to to automate easily through an API. For these you will still need to use Symphonie's interface. Examples include segmentation, dynamic content, and workflows. For both segmentation and dynamic content, the interface in Symphonie offers hundred of choices and a flexibility in defining and organizing the conditions that would be impractical to do in an API. For workflows, the logic is inherently visual, where the process flow moves from one node to another down a line that is visually shown in the interface and would be difficult to describe in an API.

Note: If you work from a Microsoft .NET environment, perhaps using Microsoft Visual Studio for your development, you may find our SOAP/XML interface is easier to use. When tools like MSVS is pointed at the WSDL page for the SOAP/XML interface, it builds the complete infrastructure of classes and functions in code for you, allowing a compiled, type-safe environment to do development.


Logins

For Symphonie, the login to use the API is no different than any other logins into the interface. Logins can be created in the interface and assigned passwords and security limitations. We recommend that you create a dedicated API login for your use with a long, strong password. Grant the login only the security rights that are required to accomplish the tasks you want done. If you are only adding recipients, for example, don’t give the login rights to send emails or run reports. We do not recommend using the same login for the API that a user has for the web interface access. It is likely that the API access will need to continue even if the user moves on to another company, so leaving the login enabled exposes you to a security risk. You may lock down the IP addresses allowed to access the interface in the administrative section of the web interface. It is also likely that a user with rights in the Symphonie interface will have more security rights than is the minimum required for the API. If you call an API where you do not have the required security rights, the return will be “No permission”.


Standard arguments

Every function call requires certain arguments, so these are not listed on every page of the function documentation. The Account is the customer name assigned to you by Goolara for hosted customers, or the value entered during the installation of the on-premise version. The Login is the name created for you by a Symphonie administrator. It can be a name like j.smith, or a full email address like joe.smith@example.com. Every account requires a password, and we recommend that you create strong passwords, especially for the API. The apiVersion field is for future versions of Symphonie to enable backwards compatibility should we need to change the API functionality. The field is optional and not passing a value or providing the value 0 will give you the most recent version of the function.
account
Your company name.
login
The name created for your use. Often something like ApiUser for API access.
password
The password for this account. We recommend you make this random and at least ten characters.
apiVersion
(Optional) Specify the desired version of this function to execute. Defaults to 0, meaning to use the most recent version.

Passing the password

The password can be passed in the headers for GET, PUT, and DELETE verbs. For POST, just include it with the other arguments. To make testing in a browser easy, functions based on GET can pass the password on the URL, allowing the results to be easily seen on screen.


Determining audiences

Using Symphonie and the REST API there are several different ways that you can determine the audience for the email you want to send. If the email is transactional and the audience is one or a few people at a time, you can provide the recipients at the time you tell Symphonie to send the content. If you are sending something like a newsletter, where there will be many recipients for the content, you can have the audience selected in one of several ways:


  1. Provide the recipients for each mailing as you send it. This gives optimal flexibility, as each mailing can have a different set of recipients, but does require you to manage the recipient list.
  2. Send to a set of list recipients marked as subscribed in the system. In Symphonie we call this a topic-based send, where the recipients are all those that have been marked as subscribed to that topic. This solution is easy for senders who want a simple way to send to the subscribed recipients of a topic with each sending.
  3. Use Symphonie segmentation to store the recipients. What we call fixed segments in Symphonie can be created using the API. The recipients can be identified one time and reused over and over for subsequent mailings. Complicated logic conditions cannot be created for segments using the API, but those segments can be created using the web interface and then used for mailings posted through the API.

In Symphonie you can target any recipient in the system at any time. You are not constrained to only sending to recipients subscribed to your 'list'. Symphonie will automatically remove any recipient who has unsubscribed, is on hold, or is suppressed, so you can target any recipient in the database.


Mail Merge and Dynamic Content

Symphonie has several options to change the content for each recipient. Simple mail merge, such as substituting the person’s email address into the content or building the unsubscribe link can be done through simple HTML and works fine through the API. Symphonie also features dynamic content options, where logic is expressed in conditions that determine what content is shown. For example, based on the zip code of the recipient, the nearest store could be computed and a block of HTML inserted that is specific to that store. This level of complicated logic cannot be built using the API. Mailings created in the web interface can be launched by the API, but the dynamic content sections will need to be added in the interface.

The description of the available mail merge tags is in this documentation, here.


Storing information about recipients (demographics and offline events)

Symphonie allows you to create additional fields of data that are stored with each recipient. We call these Demographics. You can create any fields you want to store information. You are not limited in the number of fields you can create, or in the names of the fields you create (you are not limited to selecting from a set of pre-defined fields). This is useful to store information such as the recipient’s birthday, zip code, salesperson, or other information.

Demographics are useful for information where there is a direct mapping of one field back to the recipient. A recipient has a single birthday, for example, but demographics aren’t useful for storing something that could have many possible different values, such as the white papers the person has downloaded. For this kind of data, use Symphonie’s External Events feature which allows you to create additional custom tables to store any information you want. Both Demographics and Offline Events can be created using the REST API.


Internationalization and Time Zones

Symphonie can be used wth any language in the world. The content sent through Symphonie can use any character set. Just be sure you tell Symphonie what language and character set is being used when you create your content. Symphonie has two settings for internationalization of the content. The CharsetId and the BodyLanguageId. The CharsetId is defined internationally by the Internet Assigned Number Authority (IANA) and the values can be found here:

https://www.iana.org/assignments/character-sets/character-sets.xhtml

This list includes common names like "US-ASCII' or 'Big5'. Symphonie supports the use of regional-sepcific code pages. More and more, email clients understand Unicode, so selecting UTF-8 is often a good, flexible choice if you're not sure.

The BodyLanguageId identifies the language used in the content. Some examples include "en-US" for English as spoken in the United States, or "fr-FR", as French as spoken in France, versus "fr-CA" which is French as spoken in Canada. A list of identifiers can be found here:

https://en.wikipedia.org/wiki/Language_localisation

International characters can also be used in any content you add to Symphonie, such as mailing titles, segment names, fields in demographics, etc. When data is returned it is formatted as per your settings for culture in the administrative record. Numbers, dates, and times will be formatted to appear the way that is acceptable for those culture settings.

Internally, Symphonie stores all system times in UTC 0 to support an international audience. The times are adjusted automatically to your time zone based on the administrative record. The API also uses the time zone of the Administrative record to adjust times, so when providing times make sure you adjust them as needed based on the time zone of the API user account. And when exporting data, be aware that the times will be adjusted to that time zone.


URL

For Goolara hosted accounts, your URL will be something like https://companyname.goolara.net/api/rest. For on-premise deployments, your URL will be the address of your Symphonie administrative web site plus some additional pathing.


Names VS IDs

The APIs are designed to take names whenever possible. The name of a mailing, the email address of a recipient, the name of a segment, etc. However, there are times where it can be useful to provide the numeric ID for the object instead. So instead of an email address, for example, you could provide the Recipient ID, 45352. Generally, whenever the APIs ask for an object name, you can instead provide the ID.


Adding recipients

You must explicitly add recipients. Specifying an email address that doesn’t exist in the database when making a call to send a mailing, create a segment, etc. will not cause that recipient to be auto-added. Hopefully you are keeping some demographics on your recipients such that an auto-added recipient that only has an email address would mean you are missing key information about that recipient. Be sure you have created all your recipients with their demographics and assigned subscriptions prior to calling a routine that acts on recipients.


Large result sets

If the returned data could be thousands of rows then the first set of rows is returned (often 500 rows) with a field indicating the actual number of rows. If all the data is returned, the number of rows in the data set should match the total in the field. If there is more, use the Utility/GetFile API call to retrieve the entire result set. Results should be downloaded within a few hours of the request or the data may be deleted. The data returned in the API calls is formatted using JSON, but when retrieving a large file using the Utility/GetFile API the results are formatted as a CSV file.


Mail merge delimiters

Symphonie can use different delimiters to indicate the start and end of mail merge sections. The default delimiters are [- and -], and these can be nested. If your content uses [- or -] as part of your regular content you can choose different delimiters, but otherwise you should just stay with the defaults.


Security and Permissions

Every API call goes through a security check in Symphonie. The required security attribute is listed with the API documentation, and can be configured using the website where users, groups, and security can be created.


Content and templates

With the systems of many of our competitors, you must create your content before it can be assigned to a 'campaign' or mailing. In Symphonie, content can be uploaded and reused for a Document send. Documents are normally used for transactional emails, things like the welcome email, a shipping notification, or anything sent by the workflows. A Mailing in Symphonie is to be used for a larger-audience sending, something like a newsletter posting or advertisement. In this case it is assumed that you will not be sending this same information to recipients over and over, so there isn't a reusable storage location for this content. Simply upload whatever you want to send. Symphonie also features the ability to create re-usable templates, but these are mostly for users of the web interface to help them get going. There's no API use of templates.


Errors

When attempting a new API call, you may receive an unexpected result. The REST calls must be made with the exact right argument names and path or you will get an error similar to this:

{"Message":"The request is invalid.","ModelState":{"args.login":["The login field is required."]}}


This message indicates that a required argument, the "login" field, was not provided in your data.


When passing data for Get or Put verbs, the arguments are checked and must line-up exactly. A spelling mistake will cause the function to return an error. However, that is not true of Post arguments. If you type the wrong argument name for a nullable or non-required variable, the system will simply ignore it. For example, let's say you want to provide the recipientLoggingLevel to one of the several functions that take this as a Post argument, but you mistype it, as we often do, as recipientLogginLevel (missing a g). This will be accepted without issue and appear to work properly, but the default value will be used for the recipientLoggingLevel, not the value you passed in. Since recipientLogginLevel is not a known argument, it is silently ignored on Post verbs. Be sure you check that you are getting the results you expect before deploying into production.

Other errors that occur when calling the APIs are documented with each function description.

Share this: