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

446
Folder NameDetails
Send_SMSThe folder to which files should be uploaded to for processing.
ProcessedThe folder where files that have been successfully processed are placed.
ErrorsThe 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)
21 for FTP
Username Your SMSPortal username
Password Your SMSPortal password

📘

In case you have forgotten your password, you can request a reminder here:

Password Reminder

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

ParameterDefault valueRequiredDescription
Version -YesVersion 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”
Email -NoEmail address for receiving notifications regarding whether or not the file was processed, and info if errors have occurred.
StartCurrent TimeNoStart 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
EndnullNoEnd 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
Note: Must be later than Start Delivery UTC, if provided.
SenderID FixedNoThe 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 TrueNoIf 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 -YesA collection of contacts.
Max_Errors UnlimitedNoMaximum 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 CodeDescription
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.