SFTP to SMS

📘

Important: API Channel Activation for New Accounts and Sub-Accounts

When you create a new Account or Sub-Account, please be aware that by default, no API channels will be active. To enable API access and manage your Accounts and Sub-Accounts' API credentials and settings, please follow the steps outlined in the "API Keys" page.

Note for Accounts Created Before 6 June 2023: If you have an Account that was created before 6 June 2023, the API channels would have been automatically enabled. However, if you wish to switch to an alternative API or use additional APIs, you will need to create an API Key for the desired API.

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 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 TypesJSON formatted files are supported with either the .txt or .json file extensions. Correctly formatted data is expected to process uploaded files.
Unique File NamesFile 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 name uniqueness is only checked for 48 hours.
File ExtensionsOnly .zip .txt .json file extensions are allowed.
File EncodingFiles should be encoded using UTF-8
Zipped FilesWe 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 SetsBefore 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: @@value1@@. 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 @@value1@@",
    
    "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 @@value1@@,  Welcome @@value2@@ @@value3@@ @@value4@@",
    
    "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
InsufficientCreditsNot enough Credits are available to fulfill the request.
IncorrectScheduledDateThe specified End Date is earlier than the Start Date.
MSISDN.NoNetworkFoundThe MSISDN specified has no network associated with it. The send to this number could not be completed.
MSISDN.OptoutThe MSISDN has Opted Out of your service. The message will not be sent to this address.
RequiredParameter.MissingA required parameter was either not specified or was empty.
File.InvalidVersionThe file version was not specified or is invalid. Consult the API documentation for valid version numbers and formats.
File.ParseErrorSome fields within the file could not be processed. Please view fault report.
File.DuplicateFoundA file with the same name has already been processed. The duplicate will not be processed to prevent duplicate sends.
File.CorruptThe file was unparsable.
EmptySend.NoValidMessagesThe file either contained no valid messages or the supplied messages could not be sent (eg. all numbers have already opted out).
InternalServerErrorAn internal error has occurred. If the error persists, please contact support.