NAV
cURL Node

Introduction


Send has an official nodejs library.

Current API version "V1"
API endpoint:
  "https://app.send.rest/api/v1/"


Send has an official nodejs library.

Current API version "V1"
API endpoint:
  "https://app.send.rest/api/v1/"

Welcome to the Send API! You can use our API to schedule SMS/Email/Webhook notifications or to save logs. JSON is returned by all APIs although language-specific libraries convert them to appropriate objects.

We have language bindings in Shell and node. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Alt text

Basics

Authentication

To authorize, use this code:

// Javascript library picks up tokens from 
//  - cheetahToken
//  - cheetahKey

// export cheetahToken=XXX
// export cheetahKey=YYY
# With shell, you can just pass the correct header with each request
curl "https://app.send.rest/"
  -H "cheetah-token: XXX"
  -H "cheetah-key: YYY"

Make sure to replace XXX with your API token (cheetahToken). Make sure to replace YYY with your API key (cheetahKey).

Send uses token & key to allow access to the API. You can get them from your profile here.

Send APIs expect following in header

Send won't allow access to APIs without token/key and will send a "failed" json with message "No auth".

Scheduling

var send = require("send-rest");

// Now 
send.log({}).done(); // by default notifications are scheduled for now

// Future
send.log({}).future({
  when : ["in 300 seconds"], // Duration between the notifications [CHECK EXAMPLES]
  dieout : 2, // Stop sending this notification after 'dieout' times
  start : "in 60 seconds" // Send this notification after 'start' time
}).done();
curl -X POST \
  https://app.send.rest/api/v1/job \
  -H 'Content-Type: application/json' \
  -H 'cheetah-token: XXX' \
  -H 'cheetah-key: YYY' \
  -d '{
    "type" : "future", # Available options : [now, future], default is now
    "medium" : "log",
    "when" : ["in 300 seconds"], # Duration between the notifications [CHECK EXAMPLES]
    "dieout" : 2, // Stop sending this notification after 'dieout' times
    "start" : "in 60 seconds", # Send this notification after 'start' time
    # ...
}'

Types

Send has two Notification types.

Future

Future depends on three variables

Examples

Notification Medium

var send = require("send-rest");

// email
send.email({}).to().from().future({}).done()
send.email({}).to().from().done()
// log
send.log({}).future({}).done()
send.log({}).done()
// sms
send.sms({}).to().from().future({}).done()
send.sms({}).to().from().done()
// webhook
send.webhook({}).to().future({}).done()
send.webhook({}).to().done()

curl -X POST \
  https://app.send.rest/api/v1/job \
  -H 'Content-Type: application/json' \
  -H 'cheetah-token: XXX' \
  -H 'cheetah-key: YYY' \
  -d '{
    # ...
    "medium" : "sms", # Available options : [sms, log, mail, hook], default is mail
    # ...
}'

Send supports following sending mediums

You can use following service providers for SMS

You can use following service providers for Email

Set up SMS/Email

Time Format

var send = require("send-rest");

send.log({}).future({
  // ...
  when : ["in 300 seconds"], // Duration between the notifications [CHECK EXAMPLES]
  // ...
}).done();
curl -X POST \
  https://app.send.rest/api/v1/job \
  -H 'Content-Type: application/json' \
  -H 'cheetah-token: XXX' \
  -H 'cheetah-key: YYY' \
  -d '{
    # ...
    "when" : ["in 300 seconds"], # Duration between the notifications [CHECK EXAMPLES]
    # ...
}'

Send supports Chrono time formats

Examples of format

Templates / API Support

var send = require("send-rest");

// Template Name : "bitcoin" (https://app.send.rest/editor)

// Hi #{name},
// Here is your daily bitcoin price
// <br>
// <img src="https://api.restcharts.com/chart/spline?data={{props bpi}}{{>prop}},{{/props}}" />
// <br>

send.email({
  template : "bitcoin", // template name
  subject: "Greetings #{name}", // Use variables in subject and template
  params : { "name" : "John" }, // Static Variables
  api : {
    url : "https://api.coindesk.com/v1/bpi/historical/close.json",
    method : "GET" 
  } // Response is available in Template
}).to().from().done();

// POST
//api: {
//  url: 'http://server.com',
//  method: 'POST',
//  headers: [
//    {
//      name: 'key',
//      value: 'ZZZ'
//    }
//  ],
//  postData: {
//    mimeType: 'application/x-www-form-urlencoded',
//    params: [
//      {
//        name: 'foo',
//        value: 'bar'
//      },
//      {
//        name: 'hello',
//        value: 'world'
//      }
//    ]
//  }
//}
# Template Name : "bitcoin" (https://app.send.rest/editor)

# Hi #{name},
# Here is your daily bitcoin price
# <br>
# <img src="https://api.restcharts.com/chart/spline?data={{props bpi}}{{>prop}},{{/props}}" />
# <br>

curl -X POST \
  https://app.send.rest/api/v1/job \
  -H 'Content-Type: application/json' \
  -H 'cheetah-token: XXX' \
  -H 'cheetah-key: YYY' \
  -d '{
    # ...
    "template" : {
            "name" : "bitcoin", # template name
            "subject" : "Greetings #{name}", # Use variables in subject and template 
            "params" : { "name" : "John" }, # Static Variables
            "api" : {
                "url" : "https://api.coindesk.com/v1/bpi/historical/close.json",
                "method" : "GET",
            }  # Response is available in Template
    }
    # ...
}'

# POST
#api: {
#  url: 'http://server.com',
#  method: 'POST',
#  headers: [
#    {
#      name: 'key',
#      value: 'ZZZ'
#    }
#  ],
#  postData: {
#    mimeType: 'application/x-www-form-urlencoded',
#    params: [
#      {
#        name: 'foo',
#        value: 'bar'
#      },
#      {
#        name: 'hello',
#        value: 'world'
#      }
#    ]
#  }
#}

One of the most powerful feature of templates is support for static variables and APIs. You can pull data from APIs and use them to draw charts/tables etc. or you can use static variables to personalize notifications while scheduling.

Params

Parameters can be used to personalize the notifications, parameter support is available in notification subject and body(template).

You can specify a variable by giving it a unique name and including in subject or body(template) using #{variable_name} format.

API Support

Send also supports 3rd party API responses in body of the notification (template).

Possible use cases for using APIs can be

Tracking

Alt text

Using multiple API sources

var send = require("send-rest");

send.email({
    template : "hn_apple",
    // ..
    api : [{
        url : "https://hn.algolia.com/api/v1/search_by_date?query=apple&tags=story",
        method : "GET",
        namespace : "hn"
    },{
        url : "https://itunes.apple.com/lookup?id=909253&entity=album",
        method : "GET",
        namespace : "apple"
    }],
    // ...
}).to().from().done();
curl -X POST \
  https://app.send.rest/api/v1/job \
  -H 'Content-Type: application/json' \
  -H 'cheetah-token: XXX' \
  -H 'cheetah-key: YYY' \
  -d '{
    # ...
    "template" : {
            "name" : "hn_apple",
            # ...


            "api" : [{
                "url" : "https://hn.algolia.com/api/v1/search_by_date?query=apple&tags=story",
                "method" : "GET",
                "namespace" : "hn"
            },{
                "url" : "https://itunes.apple.com/lookup?id=909253&entity=album",
                "method" : "GET",
                "namespace" : "apple"
            }]


            # ...
    }
  }'

Let`s say you want to pull data from multiple API sources in a single email, you can do so by specifying 'namespace' of each API.

Response will be available under respective 'namespace' while using in templates.

Template

{{for hn.hits}}
    < a href="{{:url}}">{{:title}}< /a >
{{/for}}

{{:apple.resultCount}}

JSView

Send uses JsViews to render the response from APIs in templates (templates are stored on send.rest; visit dashboard here or call "Create Template API" to generate one).

A complete documentation is out of scope, please visit the playground and full documentation here.

Examples Alt text

APIs

Create Template

var send = require("send-rest");
send.template("hn","Hello #{name}");
curl -X POST \
  https://app.send.rest/api/v1/template \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'cheetah-token: XXX' \
  -H 'cheetah-key: YYY' \
  -d '{
    "name" : "hn",
    "template" : "Hello #{name}"
}'

Response JSON:

{"status":"success"}

API

Please note that if template exists with matching name, it will get updated.

Dashboard

You can also create/update templates using Send dashboard. Alt text

Create Now Job

var send = require("send-rest");
// Email
send.email({
  template : "templateName",
  subject: "Greetings #{name}",
  params : { "name" : "Sam" }
}).to("sample@gmail.com").from("company@domain.com").done(function(){
  console.log("Done");
});
// Log
send.log({
  template : "templateName",
  subject: "Update Done",
  params : { "server" : "local" }
}).done(function(){
  console.log("Done");
});
// SMS
send.sms({
  template : "templateName",
  params : { "server" : "local" }
}).to("+NUMBER").from("+NUMBER").done(function(){
  console.log("done");
});
// Hook
send.webhook({
  template : "templateName",
  params : { "time" : "20/20/20" , "server" : "local" }
}).to("https://server.com").done(function(){
  console.log("done");
});

#Email
curl -X POST \
  https://app.send.rest/api/v1/job \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'cheetah-token: XXX' \
  -H 'cheetah-key: YYY' \
  -d '{
    "type" : "now",
    "to" : "sample@gmail.com",
    "from" : "company@domain.com",
    "template" : {
            "name" : "templateName",
            "subject" : "Greetings #{name}",
            "params" : { "name" : "Sam" }
    }
}'
# Log
curl -X POST \
  https://app.send.rest/api/v1/job \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'cheetah-token: XXX' \
  -H 'cheetah-key: YYY' \
  -d '{
    "type" : "now",
    "template" : {
            "name" : "log",
            "subject" : "#{server}",
            "medium": "log",
            "params" : {
                "server" : "Ingwe"       
            }
    }
}'
#SMS
curl -X POST \
  https://app.send.rest/api/v1/job \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'cheetah-token: XXX' \
  -H 'cheetah-key: YYY' \
  -d '{
    "type" : "now",
    "to" : "+NUMBER",
    "from" : "+NUMBER",
    "template" : {
            "name" : "templateName",
            "subject" : "Greetings #{name}",
            "params" : { "name" : "Sam" },
            "medium" : "sms"
    }
}'
# Web Hook
curl -X POST \
  https://app.send.rest/api/v1/job \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'cheetah-token: XXX' \
  -H 'cheetah-key: YYY' \
  -d '{
    "type" : "now",
    "to" : "https://requestb.in/xxj4znxx",
    "template" : {
        "name" : "jsonTemplate",
        "medium" : "hook",
        "subject" : "json",
        "params" : {
            "name" : "John",
            "companyName" : "Ingwe"       
        }
    },
}'

Response JSON:

{"status":"success","jobId":"JOB_ID"}

API

You can easily create notifications to be sent now using "Create Now Job" API.

Dashboard

Send provides a list of all the 'finished jobs' with status and detailed logs.

You can visit log section in dashboard to check status of any finished job. minipic

You can also set email triggers which get activated when failure threshold for failed notifications crosses.

minipic

Create Future Job

var send = require("send-rest");

// Email
send.email({
  template : "templateName",
  subject: "Greetings #{name}",
  params : { "name" : "Sam" }
}).future({
  when : ["in 300 seconds"],
  dieout : 2
}).to("sample@gmail.com").from("company@domain.com").done(function(){
  console.log("Done");
});
#Email
curl -X POST \
  https://app.send.rest/api/v1/job \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'cheetah-token: XXX' \
  -H 'cheetah-key: YYY' \
  -d '{
    "type" : "future",
    "to" : "sample@gmail.com",
    "from" : "company@domain.com",
    "template" : {
            "name" : "templateName",
            "subject" : "Greetings #{name}",
            "params" : { "name" : "Sam" }
    },
    "when" : "in 300 seconds",
    "dieout" : 2
}'

Response JSON:

{"status":"success","jobId":"JOB_ID"}

API

Future requires three parameters.

When: Defines duration between the notifications, it can be a single string or array of strings in "chrono" time format. In case of array, notifications will be sent in cyclic manner till 'dieout' times.

Dieout: Maximum number of times to send notifications.

Start: Send notification after 'start' time

Examples

Example 1

When ["in 300 seconds"]
Dieout 4
Notifications will have sent 4 times at 300 seconds , 600 seconds , 900 seconds , 1200 seconds (from now)

Example 2

When ["in 300 seconds","in 200 seconds"]
Dieout 4
Notifications will have sent 4 times at 300 seconds , 500 seconds , 800 seconds , 1000 seconds (from now)

Example 3

When ["in 300 seconds","in 200 seconds"]
Dieout 2
Notifications will have sent 2 times at 300 seconds , 500 seconds (from now)

Example 4

When ["in 300 seconds","in 200 seconds"]
Dieout Not specified
Notifications will have sent infinite times at 300 seconds , 500 seconds, 800 seconds ... (from now)
To stop these notifications you will have to call delete job API

Delete Job

var send = require("send-rest");
send.del("JOBID").done(function(){
  console.log("Done");
})
curl -X DELETE \
  https://app.send.rest/api/v1/job/:JOBID \
  -H 'Cache-Control: no-cache' \
  -H 'cheetah-token: XXX' \
  -H 'cheetah-key: YYY'

Response JSON:

{"status":"success"}

API

Delete a job which was scheduled for future. Please note that deleted jobs are not counted in billing.

Example

Future Email with API data

var send = require("send-rest");
send.email({
  template : "welcome",
  subject : "Hi #{name}",
  params : { "name" : "John" , "companyName" : "send.rest" },
  api : {
    url : "https://api.coindesk.com/v1/bpi/historical/close.json",
    method : "GET"
  }
}).future({
  when : ["in 50 minutes","in 150 minutes"],
  dieout : 2,
  now : false
}).to("to@email.com").from("from@email.com").done(function(){
  console.log("done");
});

// Dieout 1 : "in 50 minutes"
// Dieout 2 : "in 50 minutes","in 150 minutes"
// Dieout 3 : "in 50 minutes","in 150 minutes","in 50 minutes"
// And so on (cyclic)
// To send the email everyday specify when as ["in 1 day"] and skip dieout parameter.
curl -X POST \
  https://app.send.rest/api/v1/job \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'cheetah-token: XXX' \
  -H 'cheetah-key: YYY' \
  -d '{
    "type" : "future",
    "to" : "to@email.com",
    "from" : "from@email.com",
    "template" : {
            "name" : "welcome",
            "subject" : "Hi #{name}",
            "params" : {
                "name" : "John",
                "companyName" : "Send.rest"       
            },
            api : {
              url : "https://api.coindesk.com/v1/bpi/historical/close.json",
              method : "GET"
            }
    },
    "when" : ["in 50 minutes","in 150 minutes"],
    "dieout" : 2,
    "now" : false
}'

# Dieout 1 : "in 50 minutes"
# Dieout 2 : "in 50 minutes","in 150 minutes"
# Dieout 3 : "in 50 minutes","in 150 minutes","in 50 minutes"
# And so on (cyclic)
# To send the email everyday specify when as ["in 1 day"] and skip dieout parameter.

Template Name : welcome

Hello #{name} ,
Here is the current bitcoin price in USD  {{:bpi.USD.rate}} $

- Team #{companyName}

#{track_it}

Send 2 Emails having bitcoin price in USD