NAV Navbar
Logo
shell

SmartReach API

Getting started

Welcome to the SmartReach API!

Below describes the path on how to use our APIs. We recommend creating an API key, review the Authentication section on how to create one, then once ready, dive in to API calls.

Authentication

REST API keys

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "X-API-KEY: ImqrZcZhtIBHZt9e0vZsZoaZPs34EyP7"

Make sure to replace ImqrZcZhtIBHZt9e0vZsZoaZPs34EyP7 with your API key.

Pre-generated keys can be used to authenticate use of the REST API endpoints. New key can be generated through the SmartReach interface.

Generating API keys in SmartReach interface

To create or manage keys for a specific SmartReach user, go to Settings > APIKey.

alt text

X-API-KEY: ImqrZcZhtIBHZt9e0vZsZoaZPs34EyP7

Campaigns

Get Campaign List

curl "https://api.smartreach.io/api/v1/campaigns"
  -H "X-API-KEY: ImqrZcZhtIBHZt9e0vZsZoaZPs34EyP7"

The above command returns JSON structured like this:

{
    "status": "success",
    "message": "Campaigns found",
    "data": {
        "campaigns": [
            {
                "id": 16,
                "account_id": 2,
                "team_id": 1,
                "shared_with_team": false,
                "name": "blacklisttest campaign",
                "owner_name": "john doe",
                "owner_email": "john.doe@gmail.com",
                "status": "running",
                "stats": {
                    "total_sent": 1,
                    "total_opened": 1,
                    "total_replied": 1,
                    "total_steps": 2,
                    "current_prospects": 1,
                    "current_opted_out": 0,
                    "current_completed": 1,
                    "current_paused": 0,
                    "current_bounced": 0,
                    "current_to_check": 0,
                    "current_failed_email_validation": 0,
                    "current_in_progress": 0,
                    "current_unsent_prospects": 0
                },
                "head_step_id": 19,
                "settings": {
                   "timezone": "America/Los_Angeles",
                    "daily_from_time": 32400,
                    "daily_till_time": 64800,
                    "consecutive_email_delay": 60,
                    "days_preference": [
                        false,
                        true,
                        true,
                        true,
                        true,
                        true,
                        false
                    ],
                    "mark_completed_after_days": 3,
                    "max_emails_per_day": 100,
                    "open_tracking_enabled": true,
                    "click_tracking_enabled": false,
                    "warmup_started_at": 1507059003157,
                    "warmup_length_in_days": 10,
                    "warmup_starting_email_count": 5
                    "from_email": "p@userjoy.co",
                    "to_email": "nikhil.reddy132@gmail.com",
                    "opt_out_msg": "PS: If you don't want to hear from me,
                      just let me know",
                    "opt_out_is_text": true,
                    "email_priority": "equal",
                    "signature": "<p>Regards,</p><p>Prateek</p>"
                },
            }
        ]
    }
}

This retrieves all campaigns.

HTTP Request

GET https://api.smartreach.io/api/v1/campaigns

Get Campaign

curl "https://api.smartreach.io/api/v1/campaigns/16"
  -H "X-API-KEY: ImqrZcZhtIBHZt9e0vZsZoaZPs34EyP7"

The above command returns JSON structured like this:

{
    "status": "success",
    "message": "Campaign found",
    "data": {
        "campaign": {
          {
              "campaign_id": 16,
              "overall_stats": {
                  "total_sent": 1,
                  "total_opened": 1,
                  "total_clicked": 1,
                  "total_opted_out": 1,
                  "total_replied": 1,
                  "total_steps": 2,
                  "total_failed_email_validation": 0,
                  "total_prospects": 0,
                  "total_to_check": 0
              },
              "stepwise_stats": [{
                  "body": "",
                  "label": "",
                  "step_id": 1,
                  "subject": "",
                  "total_sent": 1,
                  "total_opened": 1,
                  "total_clicked": 1,
                  "total_prospects": 1,
                  "total_opted_out": 1,
                  "total_replied": 1
                },
              ],
              "timewise_stats": [{
                    "time_axis_name": "2017-11-15",
                    "total_sent": 1,
                    "total_opened": 1,
                    "total_clicked": 1,
                    "total_prospects": 1,
                    "total_opted_out": 1,
                    "total_replied": 1
                },
              ],
          }
        }
    }
}

This retrieves campaign by the campign ID specified.

HTTP Request

GET https://api.smartreach.io/api/v1/campaigns/<ID>

provide the campign id in the url you want to access

URL Parameters

Parameter Description
ID The ID of the campaign to retrieve

Prospects

Get Prospects

curl "https://api.smartreach.io/api/v1/prospects?page=1"
  -H "X-API-KEY: ImqrZcZhtIBHZt9e0vZsZoaZPs34EyP7"

The above command returns JSON structured like this:

{
    "status": "success",
    "message": "Prospects found",
    "data": {
        "total_count": 1,
        "prospects": [
            {
                "id": 1,
                "account_id": 2,
                "first_name": "jhon",
                "last_name": "doe",
                "email": "jhon.doe@gmail.com",
                "list": "",
                "company": "",
                "city": "",
                "country": "",
                "timezone": "Kwajalein",
                "created_at": 1493893976127,
                "custom_fields": {
                    "state": "",
                    "gender": "",
                    "street": "",
                    "username": ""
                },
                "campaign_name": "sample campaign",
                "to_check": false
            }
        ]
    }
}

This endpoint retrieves 1000 PRospects at a time .

HTTP Request

GET https://api.smartreach.io/api/v1/prospects?page=<ID>

The request returns list of 1000 prospects at a time.

A single page retrives around 1000 prospects at a time.

URL Parameters

Parameter Description
ID the page id of the prospects to retrive

Add Prospect

curl "https://api.smartreach.io1/api/v1/prospects"
  -H "X-API-KEY: ImqrZcZhtIBHZt9e0vZsZoaZPs34EyP7"
  -H "Content-Type: application/json"
  -X POST -d '{"city": "NY", "company": "Amazon",
  "country": "USA","phone": "", "state": "",
  "email": "jhonDoe@gmail.com","first_name": "jhon",
  "last_name": "doe","list": "sample", "timezone": "",
   "custom_fields":{}}'

The above command requires JSON data structured like this:

{
    "city": "NY",
    "company": "Amazon",
    "country": "USA",
    "phone": "",
    "state": "",
    "email": "jhonDoe@gmail.com",
    "first_name": "jhon",
    "last_name": "doe",
    "list": "sample",
    "timezone": "",
    "custom_fields":{},
}

HTTP Request

POST https://api.smartreach.io1/api/v1/prospects

The request adds a prospect to the prospect list.

Data to post Parameters

Parameter Description
city prospect’s city
company prospect’s company
country prospect’s country
phone prospect’s phone
state prospect’s state
email prospect’s email
first_name prospect’s first name
last_name prospect’s last name
list prospect is grouped by
timezone prospect’s time zone (We accept Olson timezone IDs.)
custom_fields user created fields to store prospects additional details

Email category is a required field and cannot store a null or invalid email.

Apart from the above data custom_fields store data of user created columns.columns created with blank space and uppercase letters are changed to “_” and lowercase letters respectively, for eg. if a user column was created with “New Column”, the new variable in custom_fields would be “new_column”

Errors

Example of error response

{"status":"error",
"message":"Please login",
"data":{"error_type":"unauthorized"}
}

The SmartReach API uses the following error codes:

Type Error Codes Description
invalid_param 400 Your parameters were not valid.
bad_request 400 Record was not found.
not_found 404 URL was not valid.
rate_limit 429 The request has been rate limited.
api_error 500 Internal API error.
forbidden 403 the requested api is accessible by administrator only.
unauthorized 401 Your API key is wrong