REST Email Marketing API Documentation


Documents are a space where you can store content that will be reused for sending to recipients over time. Documents and mailings are very similar in Symphonie, the main difference is in how the recipient list is determined. Both mailings and documents support HTML and plain text, open and clickthrough tracking, dynamic content, testing, previewing, and more. Documents are designed to be sent to one or a few recipients at a time, based on some event external to Symphonie. That event could be someone signing up for your newsletter, in which case the first mail they might receive would be a document with a welcome message.

A mailing in Symphonie is designed to be sent one time. A newsletter, for example, which recipients wouldn't want to receive again.

Besides welcome messages, documents are often used for birthday greetings, shipping notices, order confirmations, notices of credit card expirations — anything that is based on some event occurring. This kind of message is often called a transactional email, since some transaction occurred that triggered the mail to be sent.

To use a document, you must first prepare it with the content you want to send to recipients. You can use mail merge and dynamic content to personalize the message for each recipient. Once you have the document prepared you can trigger it to be sent to one or more recipients. In some ways a document is like a template, in that you have some content prepared that isn't being sent at the time you prepare it, but later based on some event. Symphonie supports the creation of new document via a template, so a document itself would not be called a template in Symphonie.

Documents can be triggered based on events in Symphonie, such as sending a welcome-type message to recipients when they are first loaded into Symphonie. The Workflow logic in Symphonie sends Documents, but many interesting events occur outside Symphonie. For example, an external system knows when a customer has placed an order and should be sent an order confirmation. This API can be used to trigger a Document to be sent.

Documents support mail merge fields and Dynamic Content. Mail merge tags can be added through the API, but Dynamic Content is too complicated to create using the API. Use the web interface to create Documents with Dynamic Content.

Documents have a templating feature call DynamicTags. You can add the mail merge tag for DynamicTags anywhere in the Document, including the content, subject line, or reply-to address. When you queue a Document with a DynamicTag, you must provide the substitution value. Symphonie merges this data into the messages and delivers it.

Large sections of the content can be provided by DynamicTags. In fact, the content can be nothing but a single DynamicTag mail merge tag, but we would like to discourage this. We recommend that you build the static parts of the content as the Document, and only substitute the dynamic portions using DynamicTags. It will be easier to see what was sent to recipients, and allows non-technical people to edit the message in the interface without requiring involvement of the programmers.

Symphonie keeps the details of the opens, clicks, and deliverability for every Document sent. Because of this, once a Document has been sent it cannot be deleted.

As a user of Goolara Symphonie, the REST API is free and included in the latest version of the software. If you have any questions about using Symphonie’s REST API, feel free to contact us.