You can use Retently’s API to send transactional email surveys after your customers trigger an event in your web application.
IMPORTANT: If you’re already sending transactional surveys using our API, please be informed that you may be using a deprecated endpoint: https://app.retently.com/api/v2/nps/customers/survey.
The deprecated endpoint will be supported throughout the current year and will be deactivated by the end of 2020, with further notice.
The deprecated endpoint doesn’t support the transactional campaign’s new schedule options:
Survey sampling
Survey delay
Survey throttle
If you want to benefit from these options, consider switching to the new endpoint and adjust your implementation based on the new API Response payload, as described in this tutorial.
Set up a transactional email campaign in Retently
To create a new campaign, go to the Campaigns page, choose a survey metric (NPS, CSAT, CES, 5-STAR), next select email as your survey channel, and from the dropdown list with campaign types, select the Transactional option.
Assign a survey template
In the campaign editor, start with choosing the survey template that your customers, who match this campaign, will receive in their Inbox. You can select an existing email template, or create and customize a new one.
Make sure the survey template has your company’s logo, otherwise you will not be able to select and use it.
When everything looks ok, hit the Assign button to add it as the main survey template in your campaign.
Filter your audience
As a rule, your campaign audience will be defined by your web app trigger, pushed through our API and only the customers that trigger the event will be surveyed in this campaign.
However, you can apply an additional filter to narrow your surveyed audience.
For instance, if you’re passing the customer’s country as a tag in your API request, then you will be able to add some extra filters in Retently and survey only customers that live in a particular country.
Your audience filters would look as in the example below:
In most cases, there is no need to adjust the audience filters at all. But, if you have to, we recommend checking our article to learn more about the audience segmentation in campaigns.
Edit the survey schedule
The first thing to do in the Schedule section is to specify how your surveys will be triggered. Since we are configuring this campaign for your web app events, pushed through our API, then choose the “API” option from the drop-down menu.
NOTE: It’s important to select the needed service because the content on the Setup page will adjust based on your choice. For our goal, we will need the “send survey” API endpoint and configurations.
Next, you have three options that will help you configure how and when your surveys will be sent to your campaign’s audience:
Sample audience: Choose what percentage of the triggered events will result in a survey being sent. When switched off, all triggered events will result in a survey.
Delay survey: Send the survey at a later date from the triggered event. When switched off, the survey will be sent immediately.
Throttle survey: Throttle helps avoid over-surveying customers. If a customer has been surveyed recently in this campaign, then any new triggered surveys will be discarded until a specific number of days have passed since the last survey was received. When switched off, customers will be surveyed in this campaign every time they trigger an event. This option won’t affect the schedule in other campaigns.
Reminders
Reminders will help increase your survey response rate. For instance, if a customer didn't respond to your survey within three days after opening it, our system will send them a reminder email survey. This way, you will be reaching your customers once more when they might be more likely to answer the survey.
Moreover, you can choose a different survey template for your reminders, with a different wording or style, that might be more appealing to your survey respondents. You can create a new email survey template in the Templates section of your campaign, or on the Templates page.
Notifications
In the Notifications section, you can create custom notifications and keep track of your progress.
When creating a new notification you will be asked to choose one or more event types you want to be notified about, the notification frequency (immediately, daily or weekly digest), and the channel (email or Slack).
Don't forget to save your notifications and make sure they are enabled.
Autoresponders
In this section, you can create a set of email auto-responders meant to engage with customers who did not leave any text feedback, left a Detractor score or simply to ask Promoters to leave their reviews on specific platforms and spread word-of-mouth. Autoresponders will be sent to respondents with a random delay between 5 and 60 minutes from the moment they've answered the survey.
Webhooks
Webhooks allow you to send HTTP requests to another web application every time an event is triggered, be it new feedback, a bounced survey or an unsubscribed customer. Don't forget to save each created webhook and make sure they're enabled.
Setup
In the Setup section, you will find our “send survey” API endpoint and more details about the API request that you have to perform in order to create the customer in Retently and send the transactional survey.
NOTE: If the “send survey” API endpoint and configuration are not displayed, then go back to the Schedule section and make sure that API is selected in your services drop-down menu.
Activating your campaign
The final step is to activate the transactional email campaign by switching the toggle button ON.
No surveys will be sent just yet because we haven’t connected the campaign to an event in your web app using our API. We will do this next!
Configure the API request in order to send surveys
API Request
When your customers trigger a specific event that you are tracking in your web application, you need to call our “send survey” endpoint:
[POST] https://app.retently.com/api/v2/nps/audience/survey
When calling the endpoint, you have to pass the following headers:
Content-Type: application/json
Authorization: api_key={{api_key}}
For the “Authorization” parameter you will need to generate an API key in your Retently account. To do so, access the “API Tokens” page. If you don’t have an API key generated yet, you will be asked to create a new one. Give the new key a name, and click the Generate API token button.
However, if you already have one or more keys, then you can either use one of the existing ones or simply generate a new one by clicking the Generate New API Token link.
After you have generated the API key, add it to your Headers instead of the {{api_key}} example value. Your “Authorization” parameter should look like this:
Authorization: api_key=34212-10e5-4175-8d0a-32874b999999
Next, in the Request’s body you have to pass the following parameters:
campaign: (required, string) - The campaign ID where your customers will be surveyed. The campaign ID will be available in your transactional email campaign’s Setup section, or you can pull the ID by calling our “Get campaigns” endpoint.
subscribers: (required, array) - An array of objects that may contain 1 or up to 100 customers per request. Each customer object may include the following parameters:
- email: (required, string) - A variable with the email address of the customer that should receive the survey;
- first_name: (optional, string) - A variable with the first name of the customer;
- last_name: (optional, string) - A variable with the last name of the customer;
- company: (optional, string) - A variable with the company name of the customer;
- tags: (optional, array) - Any data passed in the array, will be imported as tags along with the customer. Example: [“foo”, “bar”, “baz”];
- properties (optional, array) - An array of objects which include customer properties. Check our article on managing customer properties via API.
Note: If your request includes customers that were previously added to Retently, then their data will be updated with the information you will pass in the current request.
Request example:
{
"campaign": "5a9d595701c85b3722499999",
"subscribers": [
{
"email": "john.smith@example.com",
"first_name": "John",
"last_name": "Smith",
"company": "ACME",
"tags": [
"foo",
"bar",
"baz"
],
"properties": [
{
"label": "Subscription",
"type": "string",
"value": "Free trial"
}
]
}
]
}API Response
After you’ve made your request, a response will let you know if it went through successfully or if something wrong happened along the way.
Example of a successful response:
{
"success": true,
"code": 200,
"message": "Success.",
"status": "queued"
}The status “queued” means that the customer has been created (or updated) in Retently, has been added to the queue and will receive the survey according to your campaign’s schedule setting.
In case the request wasn’t successful, you may receive one of the following status codes:
Code 400: The customer was not added and the survey wasn’t sent as the email address is not valid or the campaign type is not transactional.
Response example:
{
"success": false,
"status": "error",
"code": 400,
"message": "Campaign 5a9d595701c85b37224ab2d0 is not transactional"
}Response example:
{
"success": false,
"status": "error",
"code": 400,
"message": "Validation Error: Invalid email addresses",
"data": [
{
"status": "fail",
"email": "john.smithexamplecom",
"first_name": "John",
"last_name": "Smith",
"company": "ACME",
"tags": [“foo”, “bar”, “baz”],
"reason": "\"email\" - Invalid email address"
}
]
}
Code 401: The API key is not valid.
Response example:
{
"message": "Invalid API key.",
"code": 401,
"data": null
}
Code 403: The customer was not added and the survey wasn’t sent as the campaign is not active.
Response example:
{
"success": false,
"status": "error",
"code": 404,
"message": "Campaign 5e930c43075a507f51399999 is not active."
}
Code 404: The customer was not added and the survey wasn’t sent as the campaign could not be found in your account.
Response example:
{
"success": false,
"status": "error",
"code": 404,
"message": "Campaign 5e930c43075a507f51399999 could not be found."
}
If you need to check our other endpoint, feel free to access the API documentation.