1.3.8 • Published 3 years ago

ws-smtp-api v1.3.8

Weekly downloads
-
License
ISC
Repository
github
Last release
3 years ago

ws-smtp-api

WinSMS SMTP API

Deployment Guide

Overview

The Docker image can be deployed as a container to any host offering Docker hosting, or a simple Ubuntu install with Docker. I cannot detail a deployment guide for every possible Docker hosting environment, but will provide the neccessary details on ENVIRONMENT VARIABLES, VOLUMES, and PORTS.

Environment Variables

Application Specific

NAMETYPEDEFAULTDESCRIPTION
REQUIRED_ROLESSTRINGApiServiceSmtpA comma separated list of roles that all users must satisfy in order to use the API. Should be set to blank for SA instance, to ensure that users do not need the SMTP API flag enabled.
ENABLE_SUBJECT_AUTHBOOLEANfalseInstructs the WS-SMTP-API to use subject-line provided user credentials - BUT ONLY as a fallback, if email address authentication fails. Should be set to true for SA instance.
VALID_DOMAINSSTRINGmail2sms.io,email2sms.ioA comma-separated list of domains that the WS-SMTP-API will process. Any incoming emails not addressed to any of the listed domains will NOT be processed. For the SA server, simply replace mail2sms.io,email2sms.io with e-mail2sms.co.za

Database Specific

NAMETYPEDEFAULTDESCRIPTION
MSSQL_SERVER_IPSTRING20.77.42.40The IP Address of the MS SQL Server
MSSQL_DATABASESTRINGSmsServerThe NAME of the database on the MS SQL Server
MSSQL_USERSTRINGIwNodeTestJan2021The Login Name of a user that has access to public SPs on the database.
MSSQL_PASSWORDSTRING****The Password for the above user
MSSQL_TIME_OFFSETINT0The offset, in hours, that the server is from GMT. This will be 0 for the international server, as it uses GMT, but 2 for the SA server, as it is 2 hours ahead of GMT.
MSSQL_NORMALISE_MOBILE_NUMBERSBOOLEANfalseNot currently used. Currently handled by the SPs on the different servers On the SA DB: Recipient mobile numbers have a default dial code of 27 appended if none is present. On the International DB: SA dial codes are NOT appended if not present - causing them to fail if not in proper international format.

PaperTrail Logs Specific

NAMETYPEDEFAULTDESCRIPTION
PAPERTRAIL_HOSTSTRINGlogs.papertrailapp.comThe host name of the PaperTrail account that these logs will be sent to. Can be retrieved from the PaperTrail account dashboard.
PAPERTRAIL_PORTINT37666The PORT of the PaperTrail account that the logs will be sent to. Can be retrieved from the PaperTrail account dashboard.
PAPERTRAIL_PROGRAMSTRINGWS-SMTP-APIA name, that will be displayed in the logs, of the application that generated the logs. This can be any valid text, and is for reference purposes only. Having an application name attached to the log entry makes searching much easier.
PAPERTRAIL_HOSTNAMESTRINGDOCKER-LON1A name, that will be displayed in the logs, of the host (Server) that generated the logs. This can be any valid text, and is for reference purposes only. Having a host name attached to the log entry makes searching much easier.
PAPERTRAIL_MIN_LEVELSTRINGdebugThe minimum level of events to log. debug = lots of information in the log - useful for finding niggly errors - bloats your log, which ultimately costs money. info = ONLY important, warn and error information in the log - keeps logs concise, small, and cheaper. warn = ONLY warn and error information in the log error = ONLY error information in the log - smallest

Testing Documentation

Client Requirements

  1. Email Client - This can be anything from a text based email client to MS Outlook to Gmail

    OR

  2. Automated internal or SaaS system capable of sending emails to a specified email address FROM a CONSISTENT email address.

  3. Working internet connection

WinSMS Account Requirements

  1. Ensure you have a username and password for your WinSMS Accounts on WINSMS4 and WSMSINT1. I currently cannot see WinSMS User Accounts for Jaun, Evan and Dawie on WSMSINT1 - You can try creating these accounts yourself using the AZ on winsms.io, or ask Jeremy to copy your User Accounts across from WINSMS4.

  2. Ensure that your test email address/es are added for Sender E-mail Address Authentication in the CZ on both winsms.co.za and winsms.io.

  3. Ensure that you enable the SMTP API for the test Accounts in the AZ on both winsms.co.za and winsms.io - see image:

alt text

Method of Testing

**Note:**

The domains @mail2sms.io and @email2sms.io both point to the same WS-SMTP-API connected to WSMSINT1 (International Server).
So both domains use the exactly the same processing logic.
Once you've tested emails to both domains a single time, you can pick one and stick with it.
**Note**
Ensure you've set up your International Accounts before starting to test.
**Note***
The DB on WSMSINT1 DOES NOT automatically normalise SA numbers to add their international dial code if not supplied.

eg.
0826520938@mail2sms.io WILL NOT WORK
27826520938@mail2sms.io WILL WORK

ALWAYS ADD A DIAL CODE to numbers before sending, when dealing with winsms.io

Standard - Unscheduled

  1. Send an email to yournumber@mail2sms.io and yournumber@email2sms.io with
  • Nothing in the subject line
  • A simple email body of 160 characters or less

  1. Ensure you receive an SMS containing the body of the email you sent to yournumber.

  2. Ensure that the SMS you sent reflects in the CZ on winsms.io, under Sent Message Log. Don't worry about the timestamps on winsms.io, the international CZ needs a code upgrade.

Testing multiple recipeints

  1. Send an email to multiple addresses at once, using @mail2sms.io, @email2sms.io, and external addresses eg. 27826520938@google.com and iwatson@inkey.tech.

  2. Verify in your log that only valid numbers (international format) at the two valid domains were accepted.

Testing Authorization Methods

  1. Delete your email address from the list of Sender E-mail Address Authentication addresses in the CZ on the E-mail to SMS tab of My Profile (winsms.io).

  2. Attempt to send the same email you did in the Standard test, to the same number.

  3. Expect this to fail, as you didn't provide a username and password in the subject line.

  4. Send another email, the same as before, but add #username,password# to the subject line of the email.

  5. Expect the SMS to be delivered to you, and verify in your logs on winsms.io.

Testing Long Message Support

  1. Add your mobile number back to the list of Sender E-mail Address Authentication addresses. This is just to make testing easier and faster.

  2. Ensure Enable Long Messages is DISABLED in the CZ on the E-mail to SMS tab of My Profile (winsms.io).

  3. Send a long message to your test number using email. I use: 1234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890ABCDEFGHIJKLMN

  4. Ensure that you receive an SMS containing only the first 160 characters of the email body.

  5. Verify the message in your Sent Logs on winsms.io

  6. Ensure Enable Long Messages is ENABLED in the CZ on the E-mail to SMS tab of My Profile (winsms.io).

  7. Send the same long message from above to your mobile number.

  8. Ensure that your SMS contains the first 918 characters of your email body. If you use my test string, your message should cut off at the letter H.

  9. Verify message in your logs

Testing Scheduled Messages - Subject Authentication

  1. Remove your email address from the list of Sender E-mail Address Authentication addresses in the CZ on winsms.io.

  2. Send an email to your number with the following subject line: #username,password,202112251200#

  3. Ensure the message appears in your Scheduled Message Log in the CZ on winsms.io, with a Scheduled For date of: 2021-12-25 10:00. You'll notice the time is displayed in GMT time in the Scheduled Log on winsms.io - hence 10 AM instead of 12PM (SA time). If you wait patiently, your SMS will be delivered at noon on Christmas day this year, please verify :)

Testing Scheduled Messages - Sender Authentication

  1. Add your email address back to the list of Sender E-mail Address Authentication addresses in the CZ on winsms.io.

  2. Send an email to your number with the following subject line: 202112251200

  3. Ensure the message appears in your Scheduled Message Log in the CZ on winsms.io, with a Scheduled For date of: 2021-12-25 10:00.

Sundry Testing

  1. Try and break the API - send attachments, HTML emails with inline images, blank messages, extra long messages etc.

  2. If you break the API, you win a prize! )

@inkeytech/ws-db@inkeytech/ws-loggerasynccrondotenvlodashmailparserpublic-ipsmtp-serveruuid
1.3.8

3 years ago