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.