The FTP API is provided for clients who want to upload large batches of individual messages in an automated way, for instance via a script. It is limited to message submissions: you will not be able to get status reports or incoming messages via FTP. Nor is such functionality planned - you should be looking at the other APIs for such functionality.
Access to this API has to be specifically enabled for your account, or you will be unable to authenticate. Please contact Support to enable access.
Briefly, you will need to log in, upload a file in (the relatively standard) CSV (comma-separated value) format, and rename it. Note that you will have to FTP to port 7022 - firewall users will need to take extra steps in this regard. Most users will want to use passive mode. If you can log in, but don't get a response to most commands, e.g. directory listings, try switching to passive mode.
|CSV file format|
If you are a programmer automating uploads, you should probably start by obtaining a CSV encoder for your programming language - look on Google. Otherwise, you should be using some application to generate the file. We do not recommend that you generate the file yourself without the aid of some such tool, as you could make mistakes in escaping characters. Nonetheless, for your information, here is a sample CSV file:
msisdn,sender,routing_group,message "4477123123","John","2","I'm John, who likes to \"randomly quote things\"." "4477123124",,,"Hi there"
The first line is a compulsory header line. Notice the escapes on the second like. Notice also how the third line specifies no values for sender and routing_group.
Only the msisdn and message columns are compulsory. The columns can be in any order.
|Server & authentication|
Log in, and upload your file with any filename that you want. However:
Your file will now have a timestamp appended (in the GMT+2 time zone), as well as the extention .process.
If fatal errors are encountered during processing (e.g. incorrect file format) or submission (e.g. you have insufficient credits), the file will have the extension .rejected appended, and the file will be filled with a textual description of the error encountered.
If no fatal errors are encountered, the file will have the extension .succeeded appended.
Note that the parsing of your file will be on a best-effort basis: we will try to find as many messages as we can in your file, strip out invalid characters, truncate messages which are too long, ignore or rewrite invalid sender ids and routing groups, etc. Therefore you would be well advised to validate your file properly before uploading.
A trap for the unwary: remember that many FTP clients (e.g. ncftp) cache directory listings to improve responsiveness for the average FTP user. So, if you log in, upload your file and rename it, and then request a directory listing immediately (or for that matter, your client may have automatically requested a listing by now), you may be creating a cached listing. Thereafter, you could carry on and on listing the directory, but may never be shown the renamed file which has just been created.