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
For running Node-RED locally, you'll need to:
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.
For running Node-RED in the cloud, you'll need to:
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.
- Go to Download Node.js to find the appropriate version for your system.
2. Install Node-RED
There are many options on how to install or run Node-RED.
- Go to Running Node-RED locally to pick your favorite and follow the steps.
3. Start the Node-RED editor
After you have installed the necessary components, it is time to start the Node-RED editor:
- Open a terminal like GitBash, PowerShell, or the like.
- Type
node-red
and pressEnter
.
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.
- Once you have your Node-RED editor open, go to the
Manage palette
menu. - Search for the
node-red-contrib-credentials
package. - When you have found it, click
Install
.
Example: Import credentials node - local
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.
- Download the tutorial flow JSON code: Download from GitHub:
Tutorial_Registered_Email_with_Node_RED.json.json
. - Right-click on the file and select
Save link as
. - Save the file on your machine.
- In the Node-RED editor, click on the menu and select
Import
. - Click
Select file to import
. - Select the file you have downloaded from GitHub and click
Open
. - 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
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
- Create an account on FRED: Front End For Node-RED.
- Select the free
FRED Short plan
and sign up. - 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 forCredentials
. - 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
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.
- Download the tutorial flow JSON code: Download from GitHub:
Tutorial_Registered_Email_with_Node_RED.json
. - Right-click on the file and select
Save link as
. - Save the file on your machine.
- In the Node-RED editor, click on the menu on the right and select
Import
. - Click
Select file to import
. - Select the file you have downloaded from GitHub and click
Open
. - 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
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
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 thecredentials
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:
- Double-click on the
Set credentials
node. - Copy and paste your client ID into the field on the right of
az
, abovemsg.client_id
. - Copy and paste your client secret into the field on the right of
az
, abovemsg.client_secret
. - Click
Done
. - 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.
- Connect the
Access token request
node with theIf access token received
node of this flow. - Double-click the node
Set request body
. - Double-click the three dots to open the JSON template.
- Enter the e-mail of the new user. See example below.
- Click Done.
- Now click Deploy to save the changes to the flow.
- Trigger the API request by clicking on the blue button on the
Trigger request
node. - 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.
- Disconnect any other flows.
- Connect the
Access token request
node with theIf access token received
node of this flow. - Double-click the node
Set request body
. - Double-click on the three dots to open the JSON and enter the e-mail address of the recipient. See example below.
- Click Done.
- Now click Deploy to save the changes to the flow.
- Trigger the API request by clicking on the blue button on the
Trigger request
node. - 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
Receipt of e-mail
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: