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)
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

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”

Email

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
Note: Must be later than Start Delivery UTC, if provided.

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.


Did this page help you?