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