Email Marketing Integration Guide
How to integrate your email marketing system with Follow Up Boss
When user creates a new email to send
Make this API call when user creates a new email in your system. This can be a one-off email blast or automated drip email.
POST https://api.followupboss.com/v1/emCampaigns
{
"origin": "Curaytor",
"originId": "912",
"name": "Can I help",
"subject": "Can I help?",
"bodyHtml": "I saw you're browsing our website, can I help with..."
}
Set origin field with the name of your email system and originId with your internal ID assigned to the new email.
You will get a response that looks like this:
201 OK
{
"id": 102,
"origin": "Curaytor",
"originId": "912",
"name": "Can I help",
"subject": "Can I help?",
"bodyHtml": "I saw you're browsing our website, can I help with..."
}
id field in the response is Follow Up Boss ID of the campaign. This value is important, save it in your system as you will need it later to update Follow Up Boss on emails sent, opens, clicks, etc.
You can use merge fields in the subject and bodyHtml:
%contact_name% - full name of the recipient
%contact_first_name% - first name of the recipient
%contact_last_name% - last name of the recipient
%contact_email% - email address of the recipient
%contact_phone% - phone number of the recipient
%contact_address% - full address of the recipient
%contact_street% - street address of the recipient
%contact_city% - city of the recipient
%contact_state% - state of the recipient
%contact_zipcode% - zip code of the recipient
%contact_country% - country of the recipient
%agent_name% - full name of the sender (user in FUB)
%agent_first_name% - first name of the sender (user in FUB)
%agent_last_name% - last name of the sender (user in FUB)
%agent_email% - email address of the sender (user in FUB)
%agent_phone% - phone number of the sender (user in FUB)
%inquiry_address% - address of the last property the recipient inquired about
%source_name% - lead source name of the recipient
Those merge fields will be replaced with their actual values when email is displayed in Follow Up Boss. If your system uses different convention for naming merge fields, replace them to match the fields listed above.
After you created an email marketing campaign it won't be visible in the Follow Up Boss UI yet until you start sending email marketing events for that campaign (see below).
When user edits an email in your system
Use this endpoint to update Follow Up Boss when a user edits marketing email in your system, for example changes email subject or body. This is more relevant for automated drip emails but may be applicable to one-off email blasts too when user saves email as a draft and later edits it before sending out.
PUT https://api.followupboss.com/v1/emCampaigns/:id
{
"name": "How can I help",
"subject": "How can I help?",
"bodyHtml": "I saw you're browsing our website, how can I help with..."
}
:id parameter is the value of id field you received in the response when creating that email marketing campaign with POST /emCampaigns.
When your system sends out email to recipients
Notify Follow Up Boss about marketing emails sent out by marking this API request:
POST https://api.followupboss.com/v1/emEvents
{"emEvents": [
{
"type": "delivered",
"occurred": "2017-04-09T16:10:59Z",
"recipient": "[email protected]",
"campaignId": 102,
"userId": 3
},
{
"type": "delivered",
"occurred": "2017-04-09T16:11:00Z",
"recipient": "[email protected]",
"campaignId": 102,
"userId": 3
},
...
]}
campaignId field contains id value you received in the response when creating that email marketing campaign with POST /emCampaigns.
userId is an optional field that allows you to specify the ID of the user in Follow Up Boss that email was sent from. This is useful to display email correctly in Follow Up Boss including replacing merge fields with correct user name, email, etc. This field is optional and defaults to the current authenticated user (the user whose API key is being used to authenticate API request).
This endpoint allows sending multiple events in a batch request, you can send up to 100 events per API request. When sending an email to a large number of recipients, we recommend breaking down the list of recipients into batches of 100 and send each batch in a separate POST request.
Marketing emails will be visible in Follow Up Boss under Timeline on the Person screen:
When your system detects clicks, opens, unsubscribes, etc.
Notify Follow Up Boss about events related to marketing emails sent out such as opens, clicks, unsubscribes, bounces and spam reports.
POST https://api.followupboss.com/v1/emEvents
{"emEvents": [
{
"type": "open",
"occurred": "2017-04-09T16:10:59Z",
"recipient": "[email protected]",
"campaignId": 102
},
{
"type": "click",
"occurred": "2017-04-09T16:11:00Z",
"recipient": "[email protected]",
"campaignId": 102,
"url": "https://google.com"
},
...
]}
campaignId field contains id value you received in the response when creating that email marketing campaign with POST /emCampaigns.
type field can be one of the following values:
delivered - Email was sent out to a recipient.
open - Recipient opened the email.
click - Recipient clicked on a link in the email.
bounced - Email bounced, it means recipient's email server rejected the email. This is a generic bounce event, use it if your system doesn't distinguish between soft and hard bounces.
soft-bounce - Email bounced temporarily.
hard-bounce - Email bounced permanently.
unsubscribe - Recipient unsubscribed from further emails.
spamreport - Recipient reported email as spam.
dropped - Sending email wasn't attempted because of the previous history with recipient (bounced, unsubscribed, etc).
You can batch your events and send up to 1000 events in one API request.
Opens, clicks will be visible in Follow Up Boss next to the marketing email under timeline on the Person screen:
Getting people from Follow Up Boss
Once user enables integration in your system you can pull existing people from Follow Up Boss into your application with GET https://api.followupboss.com/v1/people. To sync new and updated people we recommend using webhooks.
Updated over 3 years ago