API Usage examples

In this article you’ll find some examples on how to use our API. To learn more about how to use the API, take a look at the overview

​The API in it’s full and below referred methods is to be found on 

EU: https://eu-proxy-<server>.symplifymail.com/swagger
North America: https://nam-proxy.symplifymail.com/mail/swagger

If your account is on an EU server, replace <server> with the server number of your Symplify account. You'll find it at the bottom of the main menu when logged in.

Click on the example methods to get more detailed information but please note that all the links to the API below is directed to server 1.
Make sure you're using the correct URL (above) before you start testing.

One quick thing though, the Original ID is the key for you to exchange data for a specific recipient.


So, let’s say we have a web shop. In our web shop we sell food. We have a delicious newsletter where we offer different content based on the recipient’s taste palates.
We use Symplify for all our communication with our customers.

1. Signup process

We want to set up a simple newsletter sign up hosted on our site and want the new recipients to be saved in our database in Symplify. To keep it simple, the customer will only enter their email address.

After created the form on our site we need to setup the connection to Symplify with the API.

​First, it’s a good thing to check if the customer already exists in our database, so that we don’t have duplicates.

We use below REST method to check if the customer already exist in our Symplify database:

GET /{customerid}/lists/{id}/contacts/{originalId}

If the customer doesn’t exist we use the following method to create our new recipient:

POST /{customerid}/lists/{id}/contacts

2. Order confirmation

We want to set up an order confirmation email so that our customers get a message when they’ve placed an order.

First step is to create the actual order confirmation email in Symplify. That's done in Journeys with an API request starter. The starter will provide the information about how to be reached.

POST /{customerid}/journeys/{id}/commence


​But, it’s great that we now can send an email confirming the purchase but it would be nice to give the customer a summary of the purchase. We can solve this in different ways. We can ourselves use handlebars in the confirmation email to present the order rows. If we want a more designed layout for this data we can contact our Success Manager on Symplify and get a custom confirmation email set up.

3. Update recipient data

Of course we want to send relevant content to our recipients and to be able to do so, we want to know their taste palates and areas of interests. In our sendouts we therefor include a link to a profile page. We then use the collected data to create segments in Symplify to target specific topics to specific recipients.

​In this case we’ll host the form ourselves so first we create the profile page on our site and then we create the recipient attributes in Symplify responding to the profile page choices. Our recipients can choose the taste palates sour and/or sweet. So, in Symplify, we create the attributes

sour (id 100)
sweet (id 101)

​Then it’s time to connect the profile page to our database Symplify.

We use the method

PUT /{customerid}/lists/{id}/contacts/{originalId}

​To update attributes we can either use the attribute name OR the attribute id and send the data to Symplify in ”properties”:

“properties”: {”sour”:”yes”, ”sweet”:”no”}


”properties”: {”100”:”yes”, ”101”:”no”}


4. Hosting unsubscribe page

We want to manage unsubscriptions in the profile page on our end so we create the opt out page and confirmation page on our site.

​We tag the link to the opt out page with an encrypted unique ID string {{message.guid}}{{message.id}}.

Example: http://www.example.com/optoutpage.html?id={{message.guid}}{{message.id}}

​Then we add above link in our Symplify emails and when the recipient clicks unsubscribe he/she will be redirected to our optout profile page.

​Our landing page/optout page should use the following REST methods to identify the recipient and also update its status (if the recipient chooses to do so after reaching opt out page).

​To get the emailaddress of the recipient (together with other attributes if wanted):

GET /{customerid}/lists/contacts?muid={{message.guid}}{{message.id}}

To change the current subscription status of the recipient:

PUT /{customerid}/lists/{id}/contacts/{originalId}/subscriptionstatus



So, with this setup we have a signup, a profile page (where our customers can choose preferred content or unsubscribe) and we have an order confirmation. A nice package.



​5. If you want to investigate if a recipient appears more than once on one recipient list

When recipient enters landingpage / profile page you can also check if recipients appears more than once with below rest method:

GET /{customerid}/lists/{id}/contacts

6. If you want recipients to be able to re-subscribe to a list they have unsubscribed from

PUT /{customerid}/lists/{id}/contacts/{originalId}/subscriptionstatus

Model schema for subscription status:​

SubscriptionStatusDto {
status (SubscriptionStatus) = [‘SUBSCRIBED’ or ‘UNSUBSCRIBED’]: subcsriptionstatus for email,
mobileStatus (MobileSubscriptionStatus) = [‘SUBSCRIBED’ or ‘UNSUBSCRIBED’]: subcsriptionstatus for mobile
Was this article helpful?
0 out of 0 found this helpful