Shreya for Courier

Posted on Sep 6, 2022 • Updated on Oct 3, 2022 • Originally published at courier.com

Sending Secret Messages with the Courier API and Node.js

Follow along with the video tutorial:

We are launching our first hackathon next week, and giving away over $1K in prizes! Join us in building a cool project and winning any of the following prizes 🏆

Courier Hacks 1st Place: Top submission for use for notifications and demonstration of proper app-to-user notifications with the Courier API will receive $1000 via Zelle or PayPal.
Courier Hacks 2nd Place: 2nd Place submission for use for notifications and demonstration of proper app-to-user notifications with the Courier API will receive the Apple AirPods Pro.
Public Favorite: Public favorite winner will receive a Keychron Keyboard.
Runners-Up: Runners-up submissions will receive a Hydro Flask.

Additionally, everyone who submits a project successfully integrating the Courier API will receive a $20 Amazon gift card!

Not sure where to start? In this tutorial, we will be building a Node.js app that sends multi-channel notifications in morse code.

What’s going on?

We are secret agents today, and our goal is to send encoded messages to our spy network. Some spies prefer reading emails, and others prefer reading texts, so we need to ensure that our app can accommodate all spy preferences.

Note: The first five secret agents to successfully complete this tutorial and this task will receive a gift from Courier.

In Chapter 1, we will first integrate the Gmail and Twilio APIs, which Courier will use to send emails and text messages. In Chapter 2, we will demonstrate how to send single messages and setup routing to send multi-channel notifications. In Chapter 3, we will integrate a translation API to convert our messages into Morse code.

We are hosting our first hackathon next month, starting September 5th until September 30th. Register now to submit this project for a chance to win some cool prizes.

Instructions

Chapter 1: Authorize Courier to send messages using Gmail and Twilio APIs

In this first Chapter, we will need to authorize our API to send the secret messages. Let’s get started by integrating the Gmail and Twilio APIs, enabling Courier to send emails and messages from a single API call.

Log in to your Courier account and create a new secret workspace.
For onboarding, select the email channel and let Courier build with Node.js. Start with the Gmail API since it only takes seconds to set up. All we need to do to authorize is log in via Gmail. Now the API is ready to send messages.
Copy the starter code, a basic API call using cURL, and paste it in a new terminal. It already has saved your API key and knows which email address you want to send to, and has a message already built in.

Once you can see the dancing pigeon, you are ready to use Courier to send more notifications. Before we build out our application, we need to set up the Twilio provider to enable text messages.

Head over to “Channels" in the left menu and search for Twilio. You will need an Account SID, Auth Token, and a Messaging Service SID to authorize Twilio.
Open twilio.com, login and open the Console, and find the first two tokens on that page. Save the Account SID and Auth Token in Courier.

Lasty, you need to locate the Messaging Service SID, which you create in the Messaging tab on the left menu. Checkout Twilio’s docs on how to create a Messaging Service SID, linked in the description.

Once we have all three pieces of information, install the provider. Now your Courier account is authorized to send any email or SMS within one API call.

Chapter 2: Send single and multi-channel notifications

In this next Chapter, you will start sending messages. To send the secret messages, head to the Send API documentation. Here you can find everything related to sending messages.

On the right, you will see some starter code and can select a language of your choice from cURL, Node.js, Ruby, Python, Go, or PHP.

Select Node.js to get started.

// Dependencies to install:
// $ npm install node-fetch --save

const fetch = require('node-fetch');

const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "message": {
      "template": "NOTIFICATION_TEMPLATE"
    }
  })
};

fetch('https://api.courier.com/send', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

This ]basic POST request can be edited to include the spies’ data such as how to contact them and the message you need to send. The “Notification Template” can be replaced with your own template.

Add an email address in the email field on the left, which you will notice automatically appears in the code snippet on the right.

// Dependencies to install:
// $ npm install node-fetch --save

const fetch = require('node-fetch');

const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "message": {
      "template": "NOTIFICATION_TEMPLATE",
      "to": {
        "email": "courier.demos+secretmessage@gmail.com"
      }
    }
  })
};

fetch('https://api.courier.com/send', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Next, you need to add the actual message you are sending. These messages are pretty simple, so you can write them directly into the API call instead of creating a template.

Write in a subject in the title object (this can be changed anytime).
In the email body, write your message.

// Dependencies to install:
// $ npm install node-fetch --save

const fetch = require('node-fetch');

const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "message": {
      "to": {
        "email": "courier.demos+secretmessage@gmail.com"
      },
      "content": {
        "title": "new subject",
        "body": "message"
      }
    }
  })
};

fetch('https://api.courier.com/send', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

As before, the data on the left automatically appears in the code snippet on the right. There is a content object that encompasses the title and body parameters.

Now you just need to make sure that this API call has access to your Courier account, which links to the Gmail and Twilio APIs.

Replace the Auth Token with the Courier API Key (stored in Courier account settings under API Keys)[https://www.courier.com/docs/guides/getting-started/nodejs/#getting-your-api-keys].

// Dependencies to install:
// $ npm install node-fetch --save

const fetch = require('node-fetch');

const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    Authorization: 'Bearer apikey'
  },
  body: JSON.stringify({
    "message": {
      "to": {
        "email": "courier.demos+secretmessage@gmail.com"
      },
      "content": {
        "title": "new subject",
        "body": "message"
      }
    }
  })
};

fetch('https://api.courier.com/send', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Send this code out from here to test that the API call works (click "Try it" above the code snippet).
Go to your Courier logs and click on the latest log for more information. You should be able to view how it is rendered for the user receiving the message. If there was an error, you should also be able to access an error code there.

Now you can integrate this code into our own Node.js application.

Open VS Code and open a new project with a file called index.js.
Past the code into the index.js file.
Install the node-fetch npm package, enabling you to make API calls.
Open a terminal and paste the command to install the package.

$ npm install node-fetch --save

Run the program in the terminal.

$ node index.js

Here, you may run into a node-fetch error, which is caused by the require statement on line 4. To fix this, install a different version of the package found on the node-fetch documentation: https://www.npmjs.com/package/node-fetch#class-response.

npm install node-fetch@2

Now when you run this program, you should get a response from Courier that includes the requestID in the VS Code console. This indicates that the API call was made successfully, and you can head over to the Courier datalog to determine if the message was also sent successfully.

Since you are a Secret Agent, you should probably protect the API key in case our code gets into the wrong hands.

Create a new file called .env.
Store the API Key as a variable in the .env file.

APIKEY="fksdjfgjsdkfgndfsmn"

Install the dotenv npm package, allowing you to access the variable in the index.js file.
Once the package is installed, access the key by referring to it as process.env.APIKEY.
Add require('dotenv').config() to the top of the index.js file.
Run this program to confirm that it still works the same.

At this point, you can send a single message to the spies via email. However, you know that some spies prefer to use text messages, so you will need to enable multi-channel notifications. Let’s head back to the Courier docs and scroll down to the routing object, which contains the method and channels. Two types of methods are available - all and single. ‘All’ means that Courier will attempt to send the message to every channel listed. “Single” means that Courier will attempt to send it to the first channel that works. Let’s integrate this into our program.

Add the routing object anywhere within the message object, at the same level as to and content.
Define the channels within the same routing object - you can choose SMS or email, in this case, since you already have an email address defined.

"message": {
    "to": {
      "email": process.env.EMAIL
    },
    "content": {
      "title": "new subject",
      "body": "message"
    },
    "routing": {
      "method": "single",
      "channels": "email"
    },
}

Convert the channels property into an array to define multiple channels and list both email and SMS.

"channels": ["email", "sms"]

You now have two different channels that this message can be sent to. All methods would send this message to both email and SMS. Single method would try to send this to the first that works. Since you have the user’s email address but not their phone number, this program can only send it via email.

If the two channels were reversed, Courier would try to send an SMS, fail to do so, and then default to sending an email.

"channels": ["sms", "email"]

Add the user’s phone number to make the SMS channel work. Now this program should be able to send text messages via Twilio.

"message": {
    "to": {
      "email": process.env.EMAIL,
      "phone_number": process.env.PHONENUMBER
    },
    "content": {
      "title": "new subject",
      "body": "message"
    },
    "routing": {
      "method": "single",
      "channels": ["sms", "email"]
    },
}

Change the single method to all and run the program again.

"message": {
    "to": {
      "email": process.env.EMAIL,
      "phone_number": process.env.PHONENUMBER
    },
    "content": {
      "title": "new subject",
      "body": "message"
    },
    "routing": {
      "method": "all",
      "channels": ["sms", "email"]
    },
}

Courier can now send via Twilio and Gmail within the same API call.

Chapter 3: Integrate a translation API to convert messages to Morse code

NOTE: The Morse API has a rate limit, which may give you an error if you run it too many times within the hour. In this case, you will have to wait for some time before continuing.

In this last Chapter, you will integrate the Fun Translations Morse API to encode the secret messages and send them over to the spies. You can search for documentation on the Morse API on the Fun Translations website.. Here you have access to all the information you need to make the call - you have an endpoint and an example demonstrating that the original message is a parameter for the endpoint.

🔗 Fun Translations: https://funtranslations.com/api/#morse

🔗 Fun Translations API: https://api.funtranslations.com/

Start by encasing the Courier API call in a function.
Add a call to that function below the async function definition.
Refactor options to courier_options.

// Dependencies to install:
// $ npm install node-fetch --save

const fetch = require('node-fetch');
require('dotenv').config()

async function send_secret_message() {

    const courier_options = {
        method: 'POST',
        headers: {
          Accept: 'application/json',
          'Content-Type': 'application/json',
          Authorization: 'Bearer ' + process.env.APIKEY
        },
        body: JSON.stringify({
          "message": {
            "to": {
              "email": process.env.EMAIL,
              "phone_number": process.env.PHONENUMBER
            },
            "content": {
              "title": "new subject",
              "body": "message"
            },
            "routing": {
              "method": "all",
              "channels": ["sms", "email"]
            },
          }
        })
      };

      fetch('https://api.courier.com/send', courier_options)
        .then(response => response.json())
        .then(response => console.log(response))
        .catch(err => console.error(err));

}

send_secret_message()

Before sending the message, you first need to make a call to the Morse API to translate the message. You can use node-fetch in the same way as you did for Courier to make this call.

Copy the code within the async function to make the new API call.
Paste the code above the Courier API call.
Update the endpoint to the Morse API endpoint.
Refactor options to morse_options for the first call.
Remove the authorization token in the Morse API call since it does not require an API Key.
Remove the body object.
Add the message - “hey secret agent x this is your message” - as a parameter within the endpoint and replace all spaces in the message with its url-encode (%20).

// Dependencies to install:
// $ npm install node-fetch --save

const fetch = require('node-fetch');
require('dotenv').config()

async function send_secret_message() {

    const morse_options = {
        method: 'GET',
        headers: {
          Accept: 'application/json',
          'Content-Type': 'application/json'
        }
      };

      const original_message = "hey%20secret%20agent%20x%20this%20is%20your%20message"
      const morse_endpoint = "https://api.funtranslations.com/translate/morse.json?text="+original_message

      fetch(morse_endpoint, morse_options)
        .then(response => response.json())
        .then(response => console.log(response))
        .catch(err => console.error(err));

    const courier_options = {
        method: 'POST',
        headers: {
          Accept: 'application/json',
          'Content-Type': 'application/json',
          Authorization: 'Bearer ' + process.env.APIKEY
        },
        body: JSON.stringify({
          "message": {
            "to": {
              "email": process.env.EMAIL,
              "phone_number": process.env.PHONENUMBER
            },
            "content": {
              "title": "new subject",
              "body": "message"
            },
            "routing": {
              "method": "all",
              "channels": ["sms", "email"]
            },
          }
        })
      };

      fetch('https://api.courier.com/send', courier_options)
        .then(response => response.json())
        .then(response => console.log(response))
        .catch(err => console.error(err));

}

send_secret_message()

Comment out the Courier API call, since you only need to test the code you just added.

When you run this program, we may receive an error that states that there is an error parsing the JSON. This issue is caused by an error in the documentation, which here states that it should be a POST request. However, on a separate API documentation, it is written as a GET request. Update the call type to GET, and you should see the translated message within the response.

ObviouslyClearly, you don’t want to send all of this information to the spies, y. You only need the secret message.

Isolate the message by logging response.contents.translated.

fetch(morse_endpoint, morse_options)
    .then(response => response.json())
    .then(response => console.log(response.contents.translated))
    .catch(err => console.error(err));

You need to be able to access the translation from this API call in the body of the Courier API call.

Create a variable called morse_response, which will hold the entire response from this call.
Convert the JSON object into a JavaScript object so that you can read it within your code.
Get the translated message out of that object and save it in a new variable called message.
Log this variable to confirm that it works.

const morse_response = await fetch(morse_endpoint, morse_options)
    // .then(response => response.json())
    // .then(response => console.log(response.contents.translated))
    // .catch(err => console.error(err));
const translation = await morse_response.json();
const message = translation.contents.translated
console.log(message)

Replace the message within the body of the Courier API call with the encoded message you just saved in the message variable.

"message": {
    "to": {
      "email": process.env.EMAIL,
      "phone_number": process.env.PHONENUMBER
    },
    "content": {
      "title": "new secret message",
      "body": message
    },
    "routing": {
      "method": "all",
      "channels": ["sms", "email"]
    },
}

The Courier datalog should show that the messages were successfully encoded and sent via both SMS and email. Here’s what the email looks like:

Conclusion

Our spies are now ready to receive their secret encoded messages. Try changing the body of the content to your own secret message and send it over to courier.demos+secretmessage@gmail.com ,and we will send a gift to the first five Secret Agents who complete this task! Don’t forget to submit your project to our Hackathon for a chance to win over $1000 in cash and prizes!XYZ.