BellEquip Email to SMS e-2-s Gateway User Manual

: June 13, 2024
: BellEquip

Table of Contents

Email to SMS e-2-s Gateway
Quick start
Global settings
Recipients
API Users (HTTP-Rest)
Alarming
Status
SIM card switching (failure safety redundancy)
Additional interfaces for sending SMS
References
Read User Manual Online (PDF format)
Download This Manual (PDF format)

USER MANUAL
Email-to-SMS (e-2-s) Gateway

Email to SMS e-2-s Gateway

This manual describes how to use the Email-2-SMS (e-2-s) Gateway v2.
Generally, the e-2-s gateway is able to convert Emails to SMS.
There are 2 working modes, which are able to work simultaneously:

Email-Server mode
In this working mode, the e-2-s gateway acts like an email-server. The e-2-s gateway can be contacted from any email-client and get emails from the client. After getting the email, the e-2-s gateway evaluates the email-subject or/and the email-body and processes that information to create SMS, according to the user-specific configuration (details see points 5.1. and 5.2.).
Email-Client mode
In this working mode, the e-2-s gateway collects emails from an existing mailbox (for example mailbox on MS Exchange server) via POP3 or POP3-SSL in definable intervals. After collecting the email, the e-2-s gateway evaluates the email-subject or/and the emailbody and processes that information to create SMS, according to the user-specific configuration (details see points 5.1. and 5.2.).

Additionally, the e-2-s gateway is able to convert SMS to Email.
It is also possible to send Heart-Beat SMS, to regularly monitor the e-2-s gateway itself, the sim-card and the provider.
It is possible to send Multipart-SMS with the e-2-s gateway.
The e-mail-subject and the email-body can be used for the analyses. The only requirement for using the email-body is, that the e-mail body needs to be in plain text, otherwise the e-2-s gateway is not able to analyse the text in the e-mail body.

Quick start

Insert the SIM-card into Sim-slot 1.
Connect the delivered antennas to port “ANT” & “DIV”.
Connect the power-supply to port “PWR”.
Connect your PC via Ethernet cable on port “ETH0”.
Change the network settings on your PC to 192.168.1.2 (255.255.255.0).
The routing settings can be configured via WEB browser, using the following access parameters:
Address: https://192.168.1.1
Username: root
Password: P<last 8 digits of the serial number>
Enter the PIN of the SIM-card (in the e-2-s gateway menu “Configuration“ → “Mobile WAN” → “PIN”). If the PIN is disabled, leave the field empty.
If necessary, change the IP-address of the e-2-s gateway according to your local network (in the e-2-s gateway menu “Configuration“ → “Ethernet” → ”ETH0”).
Choose the right pre-configuration for your use-case in the menu “Administration” → “Change Profile”:
- Profile: Standard (default) e-2-s gateway works via LAN, without 2G/3G/4G mobile-data-connection.
  The e-2-s gateway connects to the POP3 mailbox via the Ethernet/LAN.
- Profile: Alternative 1
  e-2-s gateway connects to the POP3 mailbox via 2G/3G/4G mobile-connection of your SIM card. Attention, data-traffic of your SIM card must be activated.

The “Email to SMS” settings can be configured via WEB browser, using the following access parameters:
Address: https://192.168.1.1:8000
Username: root
Password: P<last 8 digits of the serial number>h
This page is also accessible using Port 80 at “Customization” → “User Modules” → “Email To SMS Gateway”.

Global settings

Special characters like ü, €, &, … can be read by the e-2-s gateway and also sending of SMS with special characters is supported (UTF-8 character-set).
The e-2-s gateway is able to send about 20 SMS per Minute. This value depends on some other circumstances as well (telco-provider, time for getting emails, …).
2.1. Common settings 2.1.1. Common admin and security settings

Enable Module:
The e-2-s gateway functionality will be enabled if the checkbox is checked. Auth Token :
There can be a security token (4 numbers) within the email-subject, which will be checked by the e-2-s gateway. If this token is not present in the email- subject, the SMS will not be sent. If the field “Auth Token” is empty or set it to 0, the feature is deactivated and the e-2-s gateway will not check for a token in the email-subject. If the token is active (4 digits) then the feature works in both alarming modes (rule-based and keyword-based).

Admin Email:
Email address, where the information about failure in SMS sending will be sent to. The e-2-s gateway will try 3 times to send the SMS. If the third try also fails, e-2-s gateway will send an email to the predefined Email address (defined in the field “SMS-Error email”). Leave the field empty to deactivate the feature.
Note: If the used SMS-receive-telephone-number is wrong, the e-2-s gateway is not able to detect this situation and so there will no SMSError-email be sent. The e-2-s gateway is only able to detect problems in the communication with the telco-provider!
Notify of SMS Errors:
Enable if you wish to get notified of SMS error. Notification will be sent to Admin Email
Send LogFiles:
Admin Email address, receives the history log files.
The history-log-file will be created automatically and it stores every SMS- activity which will be done by the e-2-s gateway.
The file will be sent automatically, if it reaches 60 kilobytes in size.
The file will reside in the gateway (/var/data/email2sms/history.log) until it reaches the file size limit – then it will be sent to the given email address. Leave the field empty to deactivate the feature (in this case, the log file resides on the e-2-s gateways file system and will get reset when the file reaches 60 kilobytes in size).
SMTP Configuration:
To be able to send out emails, you need to configure a SMTPServer. By using the link “Configure Email SMTP Server” you will be redirected to the page for entering the SMTP-Server information. Alternatively, you can access these settings using the menu “Configuration“ → “Services” → ”SMTP”.
2.1.2. Sender settings
The e-2-s gateway is able to analyse the email-subject and the email-body.
Email-body only works, if the email-body is in plain text format, otherwise the e-2-s gateway can’t analyse the text.
In the following settings you can define, if you want to use the email-subject or the email-body for analysis. Also, the maximum SMS length can be defined.

Subject Parsing Enabled:
Activate this checkbox, if you want to analyse the email subject
Body Parsing Enabled:
Activate this checkbox, if you want to analyse the email body
Max individual SMS (Multipart):
The value for the maximum parts of the Multipart SMS. The value must be between 1 and 9. Each single SMS-part has a maximum of 140 characters. So the maximum length of a multipart-SMS is 1260 characters!
Attention: Multipart uses multiple SMS! Keep in mind, when calculating the sim-contract and the SMS cost!
2.1.3. Heartbeat message settings
The e-2-s gateway is able to send periodic SMS (heartbeat SMS) to one recipient number, to check that the device is still powered up and working correctly. Heartbeat Interval:
It is possible to send heartbeat SMS periodically:

daily
weekly
monthly

Hour of Day & Minute of Hour:
Define the time for receiving heartbeat SMS.
Day of Week / Month:
Define the day-of-week / day-of-month for receiving heartbeat SMS.
Mobile Number:
Define the recipient number for heartbeat SMS.
SMS Text:
Define the text for heartbeat SMS.
System-Time of e2s:
The current system-time of e-2-s gateway can be seen under “Status” → “General” → “System Information“ → ”Time“.
The e-2-s gateway can synchronize its own system-time with external NTP- servers, which can be configured under “Configuration” → “Services” → “NTP” → “Synchronize clock with NTP server”. Automatic switching for Daylight-Saving- Time is implemented in the e-2-s gateway.
2.2. Email to SMS: Server Mode Settings for the e-2-s gateway to act like an email-server.
The e-2-s gateway can be contacted from any email-client via SMTP protocol and get emails from the client. After getting the email, the e-2-s gateway evaluates the email-subject or/and the email-body and processes that information to create SMS.

Enable Server Mode:
The Email-Server functionality will be enabled if the checkbox is checked. We recommend using the Email-Server-Mode in your internal network only. Using Email-Server-Mode on a public IPnetwork requires the activation of the Email-2-SMS Gateway firewall.
Email Server Port:
The IP-port, on which the e-2-s gateway listens for incoming SMTP-connections from email-clients.
Email Server Debug Enabled:
If enabled, more detailed information can be found in the systemlog of the e-2-s gateway (“Status” → “System Log”). Enable this feature only in case of communication problems with the emailclient. The e-2-s gateway can not only get emails, but also send emails for the following 3 reasons:

Send alarm emails, if the e-2-s gateway was not able to send out an alarm SMS
Send log-file emails with the historic SMS-sending activities
Convert SMS to email

2.2.1. Configure email-settings of your device (PLC) in “Server Mode”
Email-FROM:
The email-sender-address in your email-client (for example PLC) needs to be in the following format: e2s@e2s.at
Email-TO:
The email-recipient-address in your email-client (for example PLC) needs to be in one of the following formats:
a) Dynamic SMS Recipient: Email subject/body will get sent to the given number in the email-recipient-address, which needs to be in the form of +4367612345678@e2s.at . Chose this version, if you want to push the sms-recipient-number dynamically to the e-2-s gateway, already within the Email-TO address.
b) Static SMS Recipient: If Keyword-Based- or Rule-Based-Alarming should be used, the email-recipient-address needs to be in the form of e2s@e2s.at . Chose this version, if you want to use the smsrecipient-number from the phone-book using “Rule based
alarming” or “Keyword Based Alarming” – see point 5.
Example email-settings from any email-client (PLC, …): 2.3. Email to SMS: Client Mode In this working mode, the e-2-s gateway collects emails from an existing mailbox (for example mailbox on MS Exchange server) via POP3 or POP3-SSL in definable intervals. After collecting the email, the e-2-s gateway evaluates the email-subject or/and the email-body and processes that information to create SMS.
Settings for the email account, where e-2-s gateway gets emails from:

Enable Client Mode:
The Email-Client functionality will be enabled, if the checkbox is checked.
If disabled, no emails will be collected from the mailbox.
Server Protocol:
Defines the protocol of the connection to your email server:
POP3:
unsecured plain text connection
POP3-SSL:
ssl secured connection
Email Server URL:
The URL of your email server.
Email Server Port:
The used port of your email server.
Email Username:
The username to log into the email server.
Email Password:
The password to log into the email server.
To initially set or change the password, type a new password in the input field. The password will not be visible in the input field after saving with “Apply” button.
Retrieval Interval:
Polling interval for the POP3 Mailbox, to define how often the emails will be collected.
Important:
If you use a huge number of emails together with a lot of recipients, you have to set a higher interval. The minimum interval is 30 seconds.
Email-Error SMS number:
This phone-number gets notified via SMS, in case of problems with getting the emails from the email-server. If this field is empty, the feature will be disabled.
Email-Error threshold:
This value defines how many email-errors need to occur, before the SMS alarming will be triggered. Value “0” disables the feature.
2.4. SMS to Email Mode In some applications, it might be necessary to convert incoming SMS to Email. For example, if you want to provide TAN-SMS to a group of people via Email.

SMS to Email:
Email address, where the information about incoming SMS will be sent to. The email contains the full content of the SMS and the sender-mobile-number (within the email-subject and the emailbody). Leave the field empty, to deactivate the feature.
Dynamic recipient parsing:
If this checkbox is enabled, the SMS text will be scanned for an email address (word containing the “@” sign). If a valid email address will be found within the SMS, the email will be sent to this email-address too. Write the sign “@” into the field “SMS to Email”, if you want to use dynamic recipient parsing only.
SMTP Configuration:
To be able to send out emails, you need to configure a SMTPServer.
By using the link “Configure Email SMTP Server” you will be redirected to the page for entering the SMTP-Server information.
Alternatively, you can access these settings using the menu “Configuration“ → “Services” → ”SMTP”.

Recipients

In the recipients tab you find a list, which acts as a phone-book. Recipients:
Enter the name and the phone-number of the different SMS recipients.
Format of the number needs to be with international code: +4366412345678.
These defined recipients can be used in the “Rule Based Alarming” and “Keyword Based Alarming” configuration-pages.

API Users (HTTP-Rest)

Before using the http-rest API, you need to add an API-User for your application.
The according API-keys will be generated automatically when saving the settings.
It is recommended, to use a separate user for each client-application.
Your client application can use the following 2 different authentication modes:
4.1. Authentication via Link

https://router:8000/api/sms/key?to=&text=&api_user=&api_key=
Red Parts need to be adapted.
Programming example in CURL:
curl -X GET –location
“https://192.168.1.1:8000/api/sms/key?to=+43123456789&text_HelloWorld&api_user_apiuser2&api_key_9F2BD606ECE29EE1CC486EED2F55CED4F00A820A”\-H “Accept.application/json”
4.2. Authentication via “Basic Auth Header”
https://router.8000/api/sms/basic?to=&text=
Red Parts need to be adapted.
The Basic Auth Header must contain the rule of Basic Auth specification with a API User
and Key.
Programming example in CURL:
curl -X GET –location
“https://192.168.1.1:8000/api/sms/basic?to=+43123456789&text=HelloWorld” \-H “Accept: application/json” \–basic –user apiuser2:9F2BD606ECE29EE1CC486EED2F55CED4F00A820A
4.3. Implementation PRTG
The e-2-s gateway also supports the implementation in PRTG via http-rest API.
First, there needs to be an API Key/User in e-2-s gateway (see point 4).
Secondly, select „Konfiguration“ → „Systemverwaltung“ → „Versand von Benachrichtigungen aufrufen“ and at „Versand per SMS“ configure following points: Follow the steps from point 4.1. “Authentication via Link” to configure the entry „Benutzerdefinierte URL“.
In PRTG, numbers and texts within this link, will be replaced by the following macros:
Recipient number: %SMSNUMBER
SMS text: %SMSTEXT
Example URL:
https://192.168.1.1:8000/api/sms/key?to=%SMSNUMBER&text=%SMSTEXT&api_user=prtg&api_key=C978BFACD22C02E10EED574184AD9668DC445946
You can check the functionality of dispatching SMS via the button „SMS- Einstellungen testen“.

Alarming

5.1 Rule based alarming
Rule-Based-Alarming is recommended for alarming to single, or only a few telephone numbers.
In this method the telephone-number of the recipient and also the SMS-text can be a part of the email subject. For Rule-Based-Alarming it is necessary, to be able to create your own email subject. If your system can only send predefined emails, it’s recommended to use KeywordBased-Alarming (see point 5).

Enable Rule Based Alarming:
The Rule-Based-Alarming functionality will be enabled if the checkbox is checked.
If disabled, the email-subjects of incoming emails will not be checked against the rules of Rule-based-alarming.
Recipient:
The recipient, to which a SMS will be sent if the rule matches. The recipient can be deleted by pressing the |x| Button next to the input field. Add recipients as described adding them to the recipient’s directory. Afterwards select here the recipient.
default:
Marks the current recipient as default recipient. There can be more than one default recipients at the same time. The default recipient will be chosen, if there is no recipient defined in the email subject.

Text 1-10 : The predefined SMS texts 1-10, which can be used for the rules (T1 – T10).
default: Marks the current text as default text. The default text will be chosen, if there is no text defined in the email subject. There can only one default text at the same time.
5.1.1. Email Subject Definition
The email subject defines the recipient and the text of the SMS.
Keep in mind: In “Email Server Mode”, the recipient number can already be defined, using the email-recipient-address in your email-client, for example +43676123456@e2s.at.
There are 2 working-methods of the Rule-Based-Alarming: static and dynamic
In the static mode you can define recipients that are pre-configured (see 5.1) by inserting R(number, …) where number refers to a configured recipient.
You can define a text which is configured in the settings (see 5.1) by its number Tnumber.
If you don’t include any recipient definition in the email subject then the SMS will be sent to all configured default recipients.
If you don’t include any text definition in the email subject then the SMS will contain the configured default text.
In the dynamic mode you can use a text TDtext and a recipient RD(phonenumber) in your email-subject that doesn’t have to be configured in the settings.
Both methods are working parallel and can be used together. 5.1.2. Valid email subject examples

static:

A1234˽R(1,2)˽T1…………. send text 1 to recipients 1 and 2 if auth token is 1234
A1234˽R(4)˽T5…………… send text 5 to recipient 4 if auth token is 1234
A1234˽R(1,2)……………. send default text to recipient 1 and 2 if auth token is 1234
R(1,2)…………………… send default tex.t to recipient 1 and 2 if auth token is 0
A1234˽T3…………………… send text 3 to default recipients if auth token is 1234
A1234…………………… send default text to default recipients if auth token is 1234
any……… send default text to default recipients if auth token is 0

dynamic:

A1234˽RD(+43123456)˽TDhello world………… send „hello world “ to +43123456 if auth token is 1234
• ANY˽RD(+43123456)˽TDhello world ………..send „hello world “ to +43123456 if auth token is 0

static & dynamic:

ANY˽R(1)˽TDhello world ………….send „hello world “ to recipient 1 if auth token is 0

5.2 Keyword Based Alarming
Keyword-Based-Alarming is recommended for alarming to a group of telephone numbers.
In this method, it is only necessary to find a match between a keyword in the email subject and the predefined keyword in the group settings. For the Keyword-Based-Alarming it’s NOT necessary to define your own email subject. You only need to know one keyword from your email subject. Enable Keyword Based Alarming:
The Keyword-Based-Alarming functionality will be enabled if the checkbox is checked.
If disabled, the email-subjects of incoming emails will not be checked against the keywords, which are defined in the groups of Keyword-based-alarming (see point 5.2.1.).
5.2.1. Group overview It is possible to define 20 different keyword- groups, with 5 keywords for each group.
If the email-subject contains one of these keywords, the subject (its first 160 characters) will be sent as SMS to the recipients of this particular group. If the auth token is configured as a 4-digit number then the auth token must part of the email. If the auth token is configured as 0, only the keyword has to match.
5.2.2. Group Settings 1-20
By clicking on the group-line, you are entering the detailed settings for each individual keywordgroup:

Group Name:
The name of the group, which will be shown at the overview-page. It does not have any effect on the functionality.
Keywords 1-5:
Define the keywords that needs to be within the email-subject or body.
The keyword is case sensitive!
It is possible to use ## as wildcard for 1 or more characters. So, it is also possible to separate 2 words by ## in one keyword.
If you want to convert all incoming emails into SMS (without any keywordchecking), then you can use only ## as the keyword.
If all keywords are empty, the group is deactivated and no SMS will be sent.
Recipient 1-15:
On the left side of the page “Assigned Recipients”, the SMS-recipients will be defined. The recipients can be selected from the list of “Available Recipients” on the right side of the page, via drag-and-drop. The “Available Recipients” list matches the entries of the phone-book (main-menu “Recipients”). The recipients can be deleted by pressing the |x| button or via drag-and-drop.

Status

6.1. SysLog
For reasons of problem-diagnosis, it might be helpful to have a look into the recent SysLog.
Choose how many SysLog lines you want to see and refresh the page manually by using the “Refresh” button.

6.2. Return
Via “Return” button you can enter the Web-UI, which is containing all necessary routingfunctionality and further settings (SIM-card, Ethernet, VPN, …) of your e-2-s gateway.

SIM card switching (failure safety redundancy)

For reasons of high availability and redundancy, you can use both SIM slots of your e-2-s gateway.
If the default SIM-card loses registration/connection to the cellular network, the second SIM card gets active.
Therefore, you have to enable the feature “Switch to other SIM card when connection fails” in “Configuration” → “Mobile WAN”: It might make sense for your application, to think about switching back to the default SIM card, after a certain timeout. Initial Timeout:
Time that the router waits before the first attempt to switch back to the default SIM card (from 1 to 10000 minutes).
Subsequent Timeout:
Time that the router waits after an unsuccessful attempt to switch back to the default SIM card (from 1 to 10000 minutes).
Additive Constant:
Time that the router waits for any further attempts to revert to the default SIM card. This time is the sum of the time specified in the “Subsequent Timeout” and the time specified in this parameter (from 1 to 10000 minutes).

Additional interfaces for sending SMS

Besides the functionality of converting emails to SMS and using the http-rest- API, there are some other possibilities to trigger the sending of SMS.
The following interfaces are provided:
8.1. SMS via Webinterface
For testing purpose (to try if your SIM card is able to send SMS) it is the best to use the Web-GUI of e-2-s gateway.
This can be done at the main-menu under “Administration” → “Send SMS”. 8.2. SMS via Telnet- or SSH-session
It is possible to use a simple command inside a Telnet- or SSH-Session for sending SMS.
A description can be downloaded here:
https://download.bellequip.at/Anleitung_SMS_over_IP_Telnet_e2s_eng.pdf
8.3. SMS via AT-commands over TCP-session
It is possible to use AT-commands over TCP-session for sending SMS.
A description can be found here:
http://download.bellequip.at/SMS_AT_commands_over_TCP_session.pdf
8.4. SMS via AT-commands over virtual COM interface
A very similar way to point 8.3. is to use AT-commands over virtual COM interface.
A description can be found here:
http://download.bellequip.at/SMS_AT_commands_over_TCP_session_virtual_COM.pdf