Skip to content

Legacy FTP API

Deprecation Warning

This API is deprecated and customers are currently being migrated away from it.

For this API you need a set of credentials. These are different from the OAuth API the Rest API uses. You will find them in the dashboard, under Settings.

We created this API after requests from our valued customers, but we strongly encourage all customers to use the REST API. You can also batch many SMS messages together in one REST call.

Access to this API is controlled by our support staff, so if you require access please contact our live support and help us understand your use case so we can provide you with the best solution.

We have two active FTP servers, a.ftp.gatewayapi.com and b.ftp.gatewayapi.com. Both use the same files. If you cannot connect to one, try the other server. Ideally have your solution automatically failover if one is temporarily unavailable.

Flow

  • After uploading your file, you send the file by renaming it and adding .ready to the end of the file. If the file is in Excel format, add .excel.ready.
  • The moment you rename the file, we start sending it and .ready is changed to a timestamped (YYYYMMDD'T'HHMMSS) .processing. Beware that most FTP clients cache the file listing, so you might need to click refresh in your FTP client to see this change.
  • If the file could not be processed, it will be renamed to .rejected. The cause of the failure will be added to the bottom of the file.
  • When the file is processed and queued for delivery it will be renamed to .success.

If processing fails due to internal errors, the file batch will be retried up to 5 times, with 30 minutes between each attempt.

Format

The first row in the CSV must ALWAYS be a list of column names. We understand the following column names, which must match exactly.

column Description
msisdn MSISDN aka the full mobile phone number of the recipient
message The message to send. If longer than 160 normal characters, it will be split into parts of 153 normal characters.
sender Optional. Up to 11 alphanumeric characters, or 15 digits, that will be shown as the sender of the SMS.
class Optional. Default “standard”. The message class to use for this request. If specified it must be the same for all messages in the file.
userref Optional. A transparent string reference, you may set to keep track of the message in your own systems.

We will attempt to auto detect the file encoding (ie. UTF-8 or Windows-1252/cp1252). You can override this by adding .utf8 or .cp1252 to the file. Keep in mind the file must end with .ready in order for processing to start, so to override auto detected and force utf-8, call it e.g. .utf8.ready. UTF-16/32 is supported too, but only with auto detection.

Example of a unix encoded file

1
2
3
"userref","msisdn","sender","class",message"
"test","4510203040","MyCompany","standard","I'm John Doe, who ""randomly"" quote things."
,"4512345678",,"standard","Optional fields"

If you added .excel to the file name, Excel’s format is used. The target is what Excel outputs on windows, running a Western Language and using the Save As “CSV (Semicolon Delimited)”.

1
2
userref;msisdn;sender;class;message
"test";"4510203040";"MyCompany";"standard";"I'm John Doe, who ""randomly"" quote things."

We do not support escaping double quotes by adding backslashes. Double quotes must be escaped by adding an extra double quote, which is the most widely used convention.

You can terminate each row with CR+LF (\r\n) or LF (\n). We recommend LF for unix and CR+LF for Excel format, as is the standard on the respective platforms. Tab delimited files are not supported.

Caveats

  • You cannot upload Excel .xls(x) files. Save the file as “CSV (Semicolon delimited)”, and remember to add .excel.ready when sending the file.
  • The encoding/charset of the file is auto detected, consider adding explicit encoding to the file name. Although auto detection is very good, there are a few rare edge cases.
  • We recommend you do not create the CSV yourself, but have some standard software do it.
  • You can use newlines (ie. \n) as normal, as long as the text is in double quotes "<text>". Remember that CR+LF (\r\n) is two characters in the SMS (unless you have the new SMS optimization feature enabled which can remove the CR (\r).
  • The FTP has a strongly limited feature set compared the the REST API, this is by design.
  • Many FTP clients cache the directory listing, so they do not show the subsequent .processing and .success steps unless you force refresh the client.
  • You cannot delete or rename files in the .processing stage. You can however delete .success or .rejected files.
  • You cannot create new directories.
  • You cannot modify the file permissions.
  • Due to FTP protocol design, it is not trivial to implement load balancing, so you may experience an outage of one FTP server during maintenance windows. If possible automatically try the other server if one fails.
  • The timestamp added to the files is in UTC
  • Existing files will be overwritten, but due to the timestamp this is unlikely.
  • Files larger than 30 MB will not be processed, we recommend you split very large batches into smaller files of 10.000 rows each.