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 its full and below referred methods is to be found on apidocs.symplify.com.
EXAMPLES
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 the database.
Use below REST method to check if the customer already exist in the Symplify database:
GET /{customerid}/lists/{id}/contacts/{originalId}
Option 1:
If the customer doesn’t exist you can use the following method to create the new contact:
POST /{customerid}/contacts
You can connect your list with a journey with a Subscriber joins list starter to trigger a welcome flow for all new contacts.
Option 2:
You can also combine creating a contact and triggering a specific onboarding journey:
POST /{customerid}/journeys/{id}/commence
The starter will provide the information about how to be reached.
2. Order confirmation
We want to set up an order flow so that our customers get the information they need after placing an order.
First step is to create the actual order confirmation email in Symplify. That's done in Journeys and is triggered with an API request starter:
POST /{customerid}/journeys/{id}/commence
The starter will provide the information about how to be reached.
The journey flow can then be continued with shipping confirmation and other events. Learn more about how to run a journey flow based on external events.
You will probably want to customize the content in these sendouts based on purchased products and estimated shipping details. This can be done by using handlebars in your content, you can build the structure yourself or you can reach out to your Success Manager at Symplify to get a customized layout.
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, the attributes must exist on the account:
sour (id 100)
sweet (id 101)
When a contact makes a change to the profile the following method can be used to update the contact in Symplify:
PUT /{customerid}/lists/{id}/contacts/{originalId}
To update attributes you can either use the attribute name OR the attribute id and send the data to Symplify under ”properties”:
“properties”: {”sour”:”yes”, ”sweet”:”no”}
OR
”properties”: {”100”:”yes”, ”101”:”no”}
4. Hosting unsubscribe page
We want to manage subscription preferences on 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 sendouts and when a contact 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 email address 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
Summary
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.
OTHER EXAMPLES
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
}