Use Registered-E-mail API with Node-RED

Happy with this tutorial and want to test the Registered E-mail Direct API more? Head over to the documentation and the API reference for all the information you need to use the API.

Go to Registered E‑mail documentation


Introduction

The Registered E‑mail API allows you to integrate sending registered e‑mails within your existing e‑mail flows. In this tutorial, you are going to use Node-RED to integrate the API into your own (fictional) application.


What is Node-RED

Node-RED is a browser-based programming tool for wiring together hardware devices, APIs and online services in new and interesting ways. It is based on Node.js. It provides an editor with which you can wire together flows using the wide range of nodes in the palette that can be deployed to its runtime in a single click. Flows are individual programs. They consist of several nodes that perform a single task on a message object, which is passed down the flow. Flows are easy to create and there are a lot of free nodes and flows available. Find out more about Node-RED.


What you’ll learn

  • How to create a new user with the Registered E-mail API by triggering a Node-RED flow.
  • How to send an e-mail to an individual user with the Registered E-mail API by triggering a Node-RED flow.
  • How to install Node-RED locally or use it via the cloud.
  • How to configure and connect Node-RED flows.
  • How to obtain an access token (bearer token) from the KPN API Store.
  • How to debug flows to catch errors or success messages.


What you’ll need

You follow a slightly different route to get set up if you decide to use Node-RED via the cloud. Then step 1 and 2 are replaced by a single step in which you set up the Node-RED cloud solution. The rest of the steps are essentially the same, though the execution is slightly different. It will all become clear in the description of the tutorial steps below.


1. Getting set up

Running Node-RED locally


1. Install Node.js

If there is no version of Node.js already installed on your system, you need to install a version, preferably the latest.


2. Install Node-RED

There are many options on how to install or run Node-RED.


3. Start the Node-RED editor

After you have installed the necessary components, it is time to start the Node-RED editor:

  1. Open a terminal like GitBash, PowerShell, or the like.
  2. Type node-red and press Enter.


You should see an output similar to:

28 Aug 13:04:55 - [info]

Welcome to Node-RED
===================

28 Aug 13:04:56 - [info] Node-RED version: v1.1.1
28 Aug 13:04:56 - [info] Node.js  version: v12.18.2
28 Aug 13:04:56 - [info] Windows_NT 10.0.18363 x64 LE
28 Aug 13:04:57 - [info] Loading palette nodes
28 Aug 13:05:01 - [info] Settings file  : \Users\xxx\.node-red\settings.js
28 Aug 13:05:01 - [info] Context store  : 'default' [module=memory]
28 Aug 13:05:01 - [info] User directory : \Users\xxx\.node-red
28 Aug 13:05:01 - [warn] Projects disabled : editorTheme.projects.enabled=false
28 Aug 13:05:01 - [info] Flows file     : \Users\xxx\.node-red\flows_DESKTOP-NSQIT41.json
28 Aug 13:05:01 - [info] Server now running at http://127.0.0.1:1880/
28 Aug 13:05:01 - [warn]
28 Aug 13:05:01 - [info] Starting flows
28 Aug 13:05:01 - [info] Started flows

Now you can access the Node-RED editor at http://localhost:1880.


4. Install the credentials node

Install the node-red-contrib-credentials package to store your KPN API Store credentials securely.

  1. Once you have your Node-RED editor open, go to the Manage palette menu.
  2. Search for the node-red-contrib-credentials package.
  3. When you have found it, click Install.


Example: Import credentials node - local

Import credentials node


5. Import the tutorial flow

Node-RED makes it easy to save, share and move flows between computers using the export and import features. Import a flow by using the Import nodes dialog.

  1. Download the tutorial flow JSON code: Download from GitHub: Tutorial_Registered_Email_with_Node_RED.json.json.
  2. Right-click on the file and select Save link as.
  3. Save the file on your machine.
  4. In the Node-RED editor, click on the menu and select Import.
  5. Click Select file to import.
  6. Select the file you have downloaded from GitHub and click Open.
  7. Click Import.

The imported flow is visible in a new tab called Registered_Email. You can now go to the step Send API requests.


Example: Import of a generic Node-RED flow - local

Import Node-RED flow


Running Node-RED in the cloud

The cloud solution allows you to run Node-RED without any installation. Just sign up to a free demo account.

Note: This is an external solution and KPN API Store is not responsible for its availability.


1. Set up the cloud solution

  1. Create an account on FRED: Front End For Node-RED.
  2. Select the free FRED Short plan and sign up.
  3. Log in to the account. The Node-RED online editor will start up and display example flows on the tab Sheet1. You can ignore that.


2. Install the credentials node

  • Once you have your cloud Node-RED editor open, go to the Tools menu on the left.
  • Select Add or Remove Nodes.
  • In the field Search nodes search for Credentials.
  • When you have found it, click Install.
  • After the node has been installed, click Restart Instance.

Now you can import the tutorial flow (see the next step below).


Example: Import credentials node - cloud

Import credentials node


3. Import the tutorial flow

Node-RED makes it easy to save, share and move flows between computers using the export and import feature. You can import a flow by using the Import nodes dialog.

  1. Download the tutorial flow JSON code: Download from GitHub: Tutorial_Registered_Email_with_Node_RED.json.
  2. Right-click on the file and select Save link as.
  3. Save the file on your machine.
  4. In the Node-RED editor, click on the menu on the right and select Import.
  5. Click Select file to import.
  6. Select the file you have downloaded from GitHub and click Open.
  7. Click Import.

The imported flow is visible in a new tab called WeeSeeDo Direct v1. You can now go to the step Send API requests.


Example: Import of a generic Node-RED flow - cloud

Import Node-RED flow


The tutorial flow appears in a new tab. As you can see, the flow is divided into sections:

  • The first flow on the left obtains the access token from the KPN API Store by invoking an Authorization API using a POST method.
  • The other flows on the right are the actual Registered E-mail requests.


Tutorial flow with Registered E-mail endpoints

Registered E-mail flow


Have a look at the different nodes in the flow:

  • Input nodes are used to input data into a Node-RED application or flow. They have at least one output endpoint, which is shown in the small grey square on their right side. Input nodes allow you to connect data from other services, such as Twitter or temperature sensors, to manually input data into a flow using the blue Trigger request node.

  • Output nodes are used to send data outside of a Node-RED flow. They have a single input endpoint on their left side. Output nodes allow you to send data to other services such as Twitter, or to send data to the debug messages window in the sidebar. You can use green debug nodes to display the success and error messages. Switch them off and on by clicking on the button on the right side.

  • Processing nodes are used to process data. They have one input endpoint on their left side and one or more output endpoints on their right side. You can use them to do stuff, such as creating random numbers, and use the data to trigger a message and to write custom code as we do with the orange function nodes.

  • Security nodes such as the red credentials node are used to store sensitive data that is passed on in the API request, such as API keys, telephone numbers, user credentials, and so on. If you copy or export the credentials node, the data stored in the node will not be copied or exported. https://developer.kpn.com/user/logout


2. Send API requests

Now that have added your credentials to the flow, you are ready to make a few API requests.

Note: We will cover only a few API requests so you get a feeling how Node-RED works. You can see detailed instructions in the Readme: xxx nodes next to the individual flows.

If you need more information about the API endpoints and request parameters please refer to the API reference on SwaggerHub.


1. Add your KPN API Store credentials

In order to interact with the Registered E-mail API, you’ll need to do a couple of things. Log into your KPN API Store account, and go to the Sandbox to find your client ID and client secret. Copy them or make a note of them. Then add these credentials to the secure Set credentials node:

  1. Double-click on the Set credentials node.
  2. Copy and paste your client ID into the field on the right of az, above msg.client_id.
  3. Copy and paste your client secret into the field on the right of az, above msg.client_secret.
  4. Click Done.
  5. Click Deploy to save the changes to the flow.

Note: Protect your KPN API Store credentials like you protect your passwords.


2. Create new user

First lets start with creating a new user. You need to add the user details into a JSON template.

Note: Make sure that the Debug messages window is visible in the sidebar, so you can see the success and error messages.

  1. Connect the Access token request node with the If access token received node of this flow.
  2. Double-click the node Set request body.
  3. Double-click the three dots to open the JSON template.
  4. Enter the e-mail of the new user. See example below.
  5. Click Done.
  6. Now click Deploy to save the changes to the flow.
  7. Trigger the API request by clicking on the blue button on the Trigger request node.
  8. Check the response in the Debug messages pane.

JSON example

{
    "email": "new.user@email.com",
}


3. Send e-mail request

Now we can retrieve that user we have just created.

Note: Make sure that the Debug messages window is visible in the sidebar, so you can see the success and error messages.

  1. Disconnect any other flows.
  2. Connect the Access token request node with the If access token received node of this flow.
  3. Double-click the node Set request body.
  4. Double-click on the three dots to open the JSON and enter the e-mail address of the recipient. See example below.
  5. Click Done.
  6. Now click Deploy to save the changes to the flow.
  7. Trigger the API request by clicking on the blue button on the Trigger request node.
  8. Check the response in the Debug messages pane.

JSON example

{
  "message_body": "this is the e-mail body",
  "sender_email": "sender@email.com",
  "sender_real_name": "Jane Doe",
  "subject": "this is the subject",
  "x-own-id": "id",
  "x-own-guid": "guid",
  "x-own-campaign": "campaign",
  "recipient_email": "recipient@email.com",
  "recipient_language": "en",
  "attachments": [
    {
      "attachment": "BAse64E=",
      "attachment_name": "attachment.pdf",
      "attachment_type": "application/pdf"
    }
  ]
}


Success message

Success message in Debug window


Receipt of e-mail

Success message in Debug window


Congratulations

Congratulations, you have successfully created an agent user with the Registered E-mail API and Node-RED.

You have learned how to import flows into Node-RED and how to add your credentials and the payload of the API call.


Get help

Don't hesitate to contact us if you have any questions about this tutorial.


What’s next?


Check out some of these tutorials:

Mopinion feedback