SFTP to SMS
Overview
SFTP to SMS is ideal for high volume message sending that is not time sensitive, such as promotions. The SFTP upload facility allows users to securely transfer files to a SFTP server. These files get processed and messages are dispatched to all intended recipients.
Folder Structure
File Process Diagram
Folder Name | Details |
|---|---|
Send_SMS | The folder to which files should be uploaded to for processing. |
Processed | The folder where files that have been successfully processed are placed. |
Errors | The folder where files that failed to process are placed. |
Limitations
SFTP is a push only mechanism for sending messages. Incoming data such as replies and delivery statuses can be retrieved via legacy webhooks or the control panel website.
It’s not easy to implement load balancing for the SFTP protocol, so you may experience
downtime during maintenance windows.Although extremely simple to implement, SFTP to SMS has fewer features than the REST API. This is by design.
The SFTP to SMS processes new files every 5 seconds. A faster alternative would be via our RESTful API.
Only GSM encoding/charset is supported.
Only DOS/Windows, Mac and Unix line endings are supported.
Login & Authentication
Login to one of the SFTP servers with an SFTP client such as FileZilla SFTP Client. Use the following details to login:
Host | ftp.smsportal.com |
|---|---|
Port | 22 for SFTP (recommended) |
Username | Your SMSPortal username |
Password | Your SMSPortal password |
In case you have forgotten your password, you can request a reminder here:
Sending Messages
Sending messages is very simple. First, create your files in the correct file format and then transfer them to the SFTP server.
File Format
File Types | JSON formatted files are supported with either the .txt or .json file extensions. Correctly formatted data is expected to process uploaded files. |
|---|---|
Unique File Names | File names should be unique. This prevents against duplicate files as only unique file names are processed. The .zip file names don’t need to be unique. |
File Extensions | Only .zip .txt .json file extensions are allowed. |
File Encoding | Files should be encoded using UTF-8 |
Zipped Files | We recommend zipping all .txt and .json files for size reduction and CRC checks. This is a great way to ensure that the complete file is uploaded and processed correctly. |
Character Sets | Before creating your files, please view our supported SFTP to SMS Character set. |
File Upload
1. Log in to the SFTP Server.
2. Transfer your file to the “Send_SMS” folder.
3. Within 5 seconds, the file will be processed by SFTP to SMS automatically.
4. A file upload status will be sent to the email address specified in the file. If no email address is
specified, the account email is used.
Main Body Parameters
Parameter | Default value | Required | Description |
|---|---|---|---|
Version | Yes | Version number of the API to use. This allows for backwards compatibility as we update the API over time and allow for older API users to gracefully switch over to the new version. Latest Version value is “7” | |
No | Email address for receiving notifications regarding whether or not the file was processed, and info if errors have occurred. | ||
Start | Current Time | No | Start date and time when messages should be sent, in the format: 'YYYY-MM-DD hh:mm'. E.g: 2016-07-19 11:05 in UTC |
End | null | No | End date and time when messages should complete sending, in the format: 'YYYY-MM-DD hh:mm'. E.g: 2016-07-19 11:25 in UTC |
SenderID | Fixed | No | The MSISDN the message will appear from (only available on certain accounts). Up to 11 alphanumeric characters, or 15 digits, that will be shown as the sender of the SMS. Fixed FixedR |
Check_OptOuts | True | No | If set to 'False', numbers will not be scrubbed against your opt-out list. |
Message_Template | Yes, unless every contact object contains the Message field. | The message template to be used for sending SMSes. The template text may contain custom fields, which are enclosed by AT signs, e.g: @@[email protected]@. This custom field will be replaced by the value in each contact object provided. The keywords value1 to value6 can be used. | |
Contacts | Yes | A collection of contacts. | |
Max_Errors | Unlimited | No | Maximum number of errors allowed during parsing phase before the whole Send is aborted |
Code Examples
version: 7
{
"message_template": "Hello to the SMS world.",
"contacts": [
{"msisdn": "1111111111"},
{"msisdn": "2222222222"},
{"msisdn": "3333333333"},
{"msisdn": "4444444444"}
]
}
version: 7
{
"start": "2017-11-02 06:19",
"end": "2017-11-02 06:34",
"senderId": "Fixed",
"check_optouts": true,
"email": "[email protected]",
"max_errors": "1",
"message_template": "Message sent to @@[email protected]@",
"contacts": [
{"msisdn": "1111111111", "customerId": "AccJohn237", "values" : { "value1" : "John"}},
{"msisdn": "3333333333", "customerId": "TempAcc1032","message" : "Specific message for msisdn 3333333333"}
]
}
version: 7
{
"message_template": "Message sent to 1111111111, 2222222222 and 4444444444",
"contacts": [
{"msisdn": "1111111111"},
{"msisdn": "2222222222"},
{"msisdn": "3333333333", "message": "Specific message for msisdn 3333333333"},
{"msisdn": "4444444444"}
]
}
version: 7
{
"message_template": "Message sent to @@[email protected]@, Welcome @@[email protected]@ @@[email protected]@ @@[email protected]@",
"contacts": [
{"msisdn": "1111111111", "values" : { "value1" : "1111111111", "value2" : "Title", "value3" : "1stName", "value4" : "Surname"}},
{"msisdn": "2222222222", "values" : { "value1" : "2222222222", "value3" : "Jane", "value4" : "Doe" }},
{"msisdn": "3333333333", "message" : "Specific message for msisdn 3333333333"}
]
}
Error Codes
Error Code | Description |
|---|---|
InsufficientCredits | Not enough Credits are available to fulfill the request. |
IncorrectScheduledDate | The specified End Date is earlier than the Start Date. |
MSISDN.NoNetworkFound | The MSISDN specified has no network associated with it. The send to this number could not be completed. |
MSISDN.Optout | The MSISDN has Opted Out of your service. The message will not be sent to this address. |
RequiredParameter.Missing | A required parameter was either not specified or was empty. |
File.InvalidVersion | The file version was not specified or is invalid. Consult the API documentation for valid version numbers and formats. |
File.ParseError | Some fields within the file could not be processed. Please view fault report. |
File.DuplicateFound | A file with the same name has already been processed. The duplicate will not be processed to prevent duplicate sends. |
File.Corrupt | The file was unparsable. |
EmptySend.NoValidMessages | The file either contained no valid messages or the supplied messages could not be sent (eg. all numbers have already opted out). |
InternalServerError | An internal error has occurred. If the error persists, please contact support. |
Updated 8 months ago