API Reference

Welcome to the FollowUp API documentation!

You can use our API to access, create and update your reminders.

JSON will be returned in all responses from the API including errors. We currently have code examples using curl and will provide examples for ruby once we push our gem.

Authentication

To retreive an access token using an API key, use this code:

$ curl -i https://api.followup.cc/users/current.json?api_key=myapikey \
-H 'Accept:application/json'

To retreive an access token using oauth, use this code:

$ curl -i https://followup.cc/oauth/token \
-F grant_type=password \
-F client_id="<yourclientid>" \
-F client_secret="<yourclientsecret>" \
-F username=<youremailaddress>\
-F password=<yourpassword>

The above command returns JSON structured like this:

{
  "access_token":"<youraccesstoken>",
  "token_type":"bearer",
  "expires_in":7200,
  "refresh_token":"<yourrefreshtoken>"
}

To retreive a new access token after it has expired, use this code:

$ curl -i http://followup.cc/oauth/token \
-F grant_type=refresh_token \
-F client_id="<yourclientid>" \
-F client_secret="<yourclientsecret>" \
-F refresh_token="<yourrefreshtoken>"

The above command returns JSON structured like this:

{
  "access_token":"<yournewaccesstoken>",
  "token_type":"bearer",
  "expires_in":7200,
  "refresh_token":"<yournewrefreshtoken>"
}

FollowUp provides two methods of accesing the API, via an API key or Oauth access token.

API Keys

We recommend this option if you only need to access your own account.

API keys are available here.

FollowUp expects for the api key to be included in all API requests that looks like the following:

https://api.followup.cc/users/current.json?api_key=myapikey

Oauth

We recommend this option if your application needs to access other user’s accounts.

FollowUp expects for the access token key to be included in all API requests that looks like the following:

https://api.followup.cc/users/current.json?access_token=myaccesstoken

Access tokens expire 2 hours after creation. New Access tokens can be obtained using refresh tokens which is detailed in the CURL example to the right.

Reminders

Reminder object

A reminder object has the following fields:

Attribute Type Description
id integer The id of the reminder
subject string The subject of the email you sent to followup
action_address string The followup email address used to set the reminder. eg 1day@followup.cc
action_method string The method followup recived your reminder email with. eg "to", "cc", "bcc"
send_reminder_to string Which of your emails the reminder will be sent to
responded_to boolean Whether the reminder has been responded to or not
is_recurring boolean Whether the reminder is to be repeated or not
repeat_interval string String representing the interval period of when the reminder should be repeated
header_created_at timestamp UTC Unix timestamp representation of when the reminders header was created at
was_scheduled_at timestamp UTC Unix timestamp representation of when the reminder was scheduled
starts_at timestamp UTC Unix timestamp representation of when the reminder starts
cancelled_at timestamp UTC Unix timestamp representation of when the reminder was cancelled
expired_at timestamp UTC Unix timestamp representation of when the reminder expired
user_email hash Hash of the user email who the reminder belongs to
to_addresses array List of addresses present in ‘to’ field, when sending an email
cc_addresses array List of addresses present in ‘cc’ field
body_html string Content of the email, represented in html structure
body_text string Content of the email, without html tags
attachments array List of attachments. In order to download them, use links from reminder object, with current access token in params.

Get all reminders

$ curl "https://api.followup.cc/v1/reminders.json?access_token=myaccesstoken&scope[]=past&scope[]=cancelled&email=stu@argon.io" \
-H 'Accept:application/json'

The above command returns JSON structured like this:

{
  "type": "reminder.list",
  "total_count": 5,
  "pagination": {
    "next_page_number": null,
    "next_page_url": null,
    "total_pages": 1
  },
  "reminders": [
    {
      "id": 1,
      "subject": "This is a test reminder",
      "action_address": "1day@followup.cc",
      "action_method": "to",
      "send_reminder_to": "stu@argon.io",
      "responded_to": false,
      "is_recurring": false,
      "repeat_interval": null,
      "header_created_at": 1404709308,
      "was_scheduled_at": 1404709358,
      "starts_at": 1404795791,
      "cancelled_at": null,
      "expired_at": null,
      "body_html": "<div dir=\"ltr\">message example</div>\r\n",
      "body_text": "message example\r\n",
      "to_addresses": ["1min@followup.cc"],
      "cc_addresses": ["hello@example.cc"],
      "attachments": [
        {
          "file_name": "panda.jpg",
          "file_url": "https://api.followup.cc/v1/attachments/411861/panda.jpg",
          "content_type": "image/jpeg"
        }
      ],
      "user_email": {
        "id": 34,
        "email": "stu@argon.io",
        "is_primary": true,
        "user_id": 42,
        "is_confirmed": true,
        "created_at": 1393200248
      }
    }
  ]
}

This endpoint retrieves all reminders associated with your account.

HTTP Request

GET https://api.followup.cc/v1/reminders.json?access_token=myaccesstoken

Query Parameters

Parameter Type Required Description
email string false If set the result will only include reminders for the given email.
scope array false Pass a given scope to filter your reminders.

Scope Parameters

Scope paramaters filter your reminders and can also be chained together by passing multiple scope paramters in an array.

Parameter Description
past Filter by past reminders
future Filter by future reminders
recent Filter by reminders from the past month
expired Filter by expired reminders
cancelled Filter by cancelled reminders
uncancelled Filter by reminders that have not been cancelled
unscheduled Filter by reminders that are yet to be scheduled
active Filter by active reminders that are yet to be sent
responses Filter by reminders that have been responded to (Must have response detection enabled for your account)
recurring Filter by recurring reminders
non_recurring Filter by reminders that are only sent once
was_scheduled Filter by reminders that have been scheduled
this_month Filter by reminders from this month

Get a specific reminder

$ curl "https://api.followup.cc/v1/reminders/1.json?access_token=myaccesstoken"
-H 'Accept:application/json'

The above command returns JSON structured like this:

{
  "id": 1,
  "subject": "This is a test reminder",
  "action_address": "1day@followup.cc",
  "action_method": "to",
  "send_reminder_to": "stu@argon.io",
  "responded_to": false,
  "is_recurring": false,
  "repeat_interval": null,
  "header_created_at": 1404709308,
  "was_scheduled_at": 1404709358,
  "starts_at": 1404795791,
  "cancelled_at": null,
  "expired_at": null,
  "user_email": {
    "id": 34,
    "email": "stu@argon.io",
    "is_primary": true,
    "user_id": 42,
    "is_confirmed": true,
    "created_at": 1393200248
  }
}

This endpoint retrieves a specific reminder.

HTTP Request

GET https://api.followup.cc/v1/reminders/1.json?access_token=myaccesstoken

URL Parameters

Parameter Required Description
ID true The ID of the reminder to retrieve

Create a reminder

curl
"https://api.followup.cc/v1/reminders.json?access_token=myaccesstoken" \
  -X POST \
  -H 'Accept:application/json'

The above command returns JSON structured like this:

{
  "status": 201,
  "header": {
    "Content-Type": "text/json",
    "Content-Length": "15"
  },
  "chunked": false,
  "writer": {},
  "block": null,
  "length": 15,
  "body": [
    "Reminder queued"
  ]
}

This endpoint creates a reminder associated with your account.

HTTP Request

POST https://api.followup.cc/v1/reminders.json?access_token=myaccesstoken

Query Parameters

Parameter Type Required Description
to string true The action to set a reminder with followup eg 1day@followup.cc.
subject string true The subject of the email.
body string true The body of the email.
from string true Which email you want to send the reminder from.

Reschedule a reminder

$ curl "https://api.followup.cc/v1/reminders/1/reschedule.json?access_token=myaccesstoken" \
-X PUT \
-H 'Accept:application/json' \
-H 'Content-Type:application/json' -d'
{
  "starts_at": 1404706692
}'

The above command returns JSON structured like this:

{
  "id": 1,
  "subject": "This is a test reminder",
  "action_address": "1day@followup.cc",
  "action_method": "to",
  "send_reminder_to": "stu@argon.io",
  "responded_to": false,
  "is_recurring": false,
  "repeat_interval": null,
  "header_created_at": 1404709308,
  "was_scheduled_at": 1404709358,
  "starts_at": 1404706692,
  "cancelled_at": null,
  "expired_at": null,
  "user_email": {
    "id": 34,
    "email": "stu@argon.io",
    "is_primary": true,
    "user_id": 42,
    "is_confirmed": true,
    "created_at": 1393200248
  }
}

This endpoint creates a reminder associated with your account.

HTTP Request

PUT https://api.followup.cc/v1/reminders/1/reschedule.json?access_token=myaccesstoken

Query Parameters

Parameter Type Required Description
starts_at timestamp true The time the reminder will send as a UTC Unix timestamp.

Update a reminder’s recipient

$ curl "https://api.followup.cc/v1/reminders/1/update_recipient.json?access_token=myaccesstoken" \
-X PUT \
-H 'Accept:application/json' \
-H 'Content-Type:application/json' -d'
{
  "email": stuartdoe@gmail.com
}'

The above command returns JSON structured like this:

{
  "id": 1,
  "subject": "This is a test reminder",
  "action_address": "1day@followup.cc",
  "action_method": "to",
  "send_reminder_to": "stuartdoe@gmail",
  "responded_to": false,
  "is_recurring": false,
  "repeat_interval": null,
  "header_created_at": 1404709308,
  "was_scheduled_at": 1404709358,
  "starts_at": 1404795791,
  "cancelled_at": null,
  "expired_at": null,
  "user_email": {
    "id": 35,
    "email": "stuartdoe@gmail.com",
    "is_primary": false,
    "user_id": 42,
    "is_confirmed": true,
    "created_at": 1393200398
  }
}

This endpoint updates the recipient of the reminder.

HTTP Request

PUT https://api.followup.cc/v1/reminders/1/update_recipient.json?access_token=myaccesstoken

Query Parameters

Parameter Default Description
email true The email address of the new recipient. This email address must be an email address from your account.

Send the reminder now

 $ curl "https://api.followup.cc/v1/reminders/1/send_now.json?access_token=myaccesstoken" \
 -X PUT \
 -H 'Accept:application/json' \
 -H 'Content-Type:application/json' -d'
 {
   "cancel": true
 }'

The above command returns JSON structured like this:

{
  "id": 1,
  "subject": "This is a test reminder",
  "action_address": "1day@followup.cc",
  "action_method": "to",
  "send_reminder_to": "stu@argon.io",
  "responded_to": false,
  "is_recurring": false,
  "repeat_interval": null,
  "header_created_at": 1404709308,
  "was_scheduled_at": 1404709358,
  "starts_at": 1404795791,
  "cancelled_at": null,
  "expired_at": null,
  "user_email": {
    "id": 34,
    "email": "stu@argon.io",
    "is_primary": true,
    "user_id": 42,
    "is_confirmed": true,
    "created_at": 1393200248
  }
}

This endpoint sends the reminder straight away and also has the option to cancel it too.

HTTP Request

PUT https://api.followup.cc/v1/reminders/1/send_now.json?access_token=myaccesstoken

Query Parameters

Parameter Default Description
cancel false a boolean field which indicates whether you would like to cancel the reminder at the time of sending.

Snooze a reminder

$ curl "https://api.followup.cc/v1/reminders/1/send_now.json?access_token=myaccesstoken" \
 -X PUT \
 -H 'Accept:application/json' \
 -H 'Content-Type:application/json' -d'
 {
   "seconds": 1800
 }'

The above command returns JSON structured like this:

{
  "id": 2,
  "subject": "This is a test reminder",
  "action_address": "1day@followup.cc",
  "action_method": "to",
  "send_reminder_to": "stu@argon.io",
  "responded_to": false,
  "is_recurring": false,
  "repeat_interval": null,
  "header_created_at": 1404709308,
  "was_scheduled_at": 1404709358,
  "starts_at": 1404762736,
  "cancelled_at": null,
  "expired_at": null,
  "user_email": {
    "id": 34,
    "email": "stu@argon.io",
    "is_primary": true,
    "user_id": 42,
    "is_confirmed": true,
    "created_at": 1393200248
  }
}

This endpoint snoozes a reminder for a given time period. The current reminder will be expired and a new reminder will be created and returned.

HTTP Request

PUT https://api.followup.cc/v1/reminders/1/snooze.json?access_token=myaccesstoken

Query Parameters

Parameter Default Description
seconds 0 an integer representing how many seconds you would like the reminder snoozed for.

Cancel a reminder

$ curl "https://api.followup.cc/v1/reminders/1.json?access_token=myaccesstoken" \
 -X DELETE \
 -H 'Accept:application/json' \
 -H 'Content-Type:application/json'

The above command returns JSON structured like this:

{
  "id": 1,
  "subject": "This is a test reminder",
  "action_address": "1day@followup.cc",
  "action_method": "to",
  "send_reminder_to": "stu@argon.io",
  "responded_to": false,
  "is_recurring": false,
  "repeat_interval": null,
  "header_created_at": 1404709308,
  "was_scheduled_at": 1404709358,
  "starts_at": 1404795791,
  "cancelled_at": 1404762901,
  "expired_at": null,
  "user_email": {
    "id": 34,
    "email": "stu@argon.io",
    "is_primary": true,
    "user_id": 42,
    "is_confirmed": true,
    "created_at": 1393200248
  }
}

This endpoint cancels the remidner.

HTTP Request

PUT https://api.followup.cc/v1/reminders/1.json?access_token=myaccesstoken

Users

User object

A user object has the following fields:

Attribute Type Description
id integer Id of the user
email string Email address of the user
first_name string First name of the user
last_name string Last name of the user
timezone string Timezone of the user
send_confirmation boolean Whether or not to send confirmation emails to the user upon creation of a reminder
store_message_body boolean Whether or not to send the body of the reminder in the reminder email for the user
communications boolean Whether or not to send announcements and newsletters to the user
reply_to_customization boolean Whether or not to set the reply-to the reminder’s recipients instead of no-reply@followup.cc
include_attachments_customization boolean Whether or not to include any attachments sent in the reminder
snooze_bar_size_customization string What size the user’s snooze bar is set to.
day_start_hour integer Represents what time your day starts at
phone_number string User’s phone number
is_confirmed boolean Whether the user is confirmed or not
created_at timestamp UTC Unix timestamp representation of when the user was created

Get the current user

$ curl "https://api.followup.cc/v1/users/current.json?access_token=myaccesstoken" \
-H 'Accept:application/json'

The above command returns JSON structured like this:

{
  "id": 42,
  "email": "stu@argon.io",
  "first_name": null,
  "last_name": null,
  "timezone": "Pacific Time (US & Canada)",
  "send_confirmation": true,
  "store_message_body": false,
  "communications": true,
  "reply_to_customization": false,
  "include_attachments_customization": true,
  "snooze_bar_size_customization": "full",
  "day_start_hour": 7,
  "phone_number": null,
  "is_confirmed": true,
  "created_at": 1393200247
}

This endpoint retrieves all of the your user details.

HTTP Request

GET https://api.followup.cc/v1/users/current.json?access_token=myaccesstoken

User Emails

User email object

A user email object has the following fields:

Attribute Type Description
id integer Id of the user email
email string Email address of the user_email
is_primary boolean Whether the user_email is the primary user_email for the user
is_confirmed string Whether the user_email has been confirmed
created_at timestamp UTC Unix timestamp representation of when the user_email was created

Get all user emails

$ curl "https://api.followup.cc/v1/user_emails.json?access_token=myaccesstoken" \
-H 'Accept:application/json'

The above command returns JSON structured like this:

{
  "type": "user_email.list",
  "total_count": 2,
  "pagination": {
    "next_page_number": null,
    "next_page_url": null,
    "total_pages": 1
  },
  "user_emails": [
    {
      "id": 34,
      "email": "stu@argon.io",
      "is_primary": true,
      "user_id": 42,
      "is_confirmed": true,
      "created_at": 1393200248
    }
  ]
}

This endpoint retrieves all of the your user details.

HTTP Request

GET https://api.followup.cc/v1/user_emails.json?access_token=myaccesstoken

Get a specific user email

$ curl "https://api.followup.cc/v1/user_emails/1.json?access_token=myaccesstoken" \
-H 'Accept:application/json'

The above command returns JSON structured like this:

{
  "id": 34,
  "email": "stu@argon.io",
  "is_primary": true,
  "user_id": 42,
  "is_confirmed": true,
  "created_at": 1393200248
}

This endpoint retrieves details of a specific user email.

HTTP Request

GET https://api.followup.cc/v1/user_emails/1.json?access_token=myaccesstoken

Errors

Error object

The API returns an error list comprised of the following:

Field Description
type error.list
errors an array of errors

ERROR OBJECT ATTRIBUTES

Erorr lists returns JSON structured like this:

{
  "type": "error_list",
  "errors": [
    {
      "status": "missing_param",
      "message": "seconds is missing",
      "field": "seconds"
    }
  ]
}

Each Error Object has the following attributes

Field Description
code A string indicating the kind of error, used to further qualify the HTTP response code
message Optional. Human readable description of the error
field Optional. Used to identify a particular field or query parameter that was in error.

Error codes

Error Code Meaning
400 Bad Request – The API request is malformed.
401 Unauthorized – Your access token is wrong
403 Forbidden – The reminder requested is hidden for administrators only
404 Not Found – The specified reminder could not be found
405 Method Not Allowed – You tried to access a reminder with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The reminder requested has been removed from our servers
429 Too Many Requests – You’re requesting too many reminders! Slown down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.