The Filetransfer appliance has an XML API to facilitate automated filetransfers.

There's currently three API requests that can be made

• Account request - used to get an api-key, validate account details and getting user configuration.
• File Uploads - used to upload files, this request has to be performed once for every file to send
• Message request - used to send uploaded files

Typically, these three requests happens in order. First get the api key. Then upload the files, this request can be performed as many times as needed. Then finally the message request to send the uploaded file(s).

Request URL's

To send these requests, please use a http POST (as opposed to a http GET) request to the following URL's.

Response status codes

In the header of the response, there will be a couple of possible status codes. In case of a 4XX error, please see the response body for an error description.

URL: The request needs to be posted to /account, i.e. https://filetransfer.example.com/account.

Request

Example Request

<?xml version="1.0" encoding="UTF-8"?>
<account>
  <email>user@example.com</email>
  <password>password</password>
</account>

Response

In case the user is presented with an interface (email client plugin, …) these responses dictates what should be visible to the end user. If the user is allowed to change the file expiration, show the control with the listed default parameters. If the user isn't allowed to change file expiration, either grey out or remove those controls.

The account request should be made before each file transfer to refresh the api_key. The api key expires after two days to make sure that any long file transfer is not interrupted, but should still be called before each transfer.

Example Response

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <api_key>DyTMSdfCduO5l6vfU823AA</api_key>
  <api_key_expires_at>Thu May 28 19:32:23 +1000 2009</api_key_expires_at>
  <max_file_size type="integer">2000</max_file_size>
  <change_expiration type="boolean">true</change_expiration>
  <default_file_expiration type="integer">2</default_file_expiration>
  <default_file_expiration_format>weeks</default_file_expiration_format>
  <blocked_extensions>exe, vbs, pif, scr, bat, cmd, com, cpl</blocked_extensions>
  <require_authentication type="boolean">true</require_authentication>
  <allow_users_to_change_require_authentication type="boolean">true</allow_users_to_change_require_authentication>
  <default_bcc_myself type="boolean">true</default_bcc_myself>
</user>

The file upload is a standard part/multipart file upload post (not xml), with the following request parameters.

URL: The request needs to be posted to /attachments, i.e. https://filetransfer.example.com/attachments.

Example Request Your code that sends files to the Filetransfer appliance must match the following html:

<form action="https://filetransfer.example.com/attachments" enctype="multipart/form-data" method="post">
  <input name="api_key" value="DyTMSdfCduO5l6vfU823AA" />
  <input type="file" name="Filedata" filename="filename.ext" />
</form>

which would lead to the following raw upload data

Content-type: multipart/form-data, boundary=AaB03x

--AaB03x
content-disposition: form-data; name="api_key"

DyTMSdfCduO5l6vfU823AA
--AaB03x
content-disposition: form-data; name="Filedata"; filename="filename.ext"
Content-Type: text/plain

... contents of filename.ext ...
--AaB03x--

Example Response

123456

The message request is the final piece used to send the actual message.

URL: The request needs to be posted to /message, i.e. https://filetransfer.example.com/message.

Example Message request

<?xml version="1.0" encoding="UTF-8"?>
<message>
  <api_key>DyTMSdfCduO5l6vfU823AA</api_key>
  <recipients type="array">
    <recipient>user1@company1.com</recipient>
    <recipient>user2@company2.com</recipient>
  </recipients>
  <cc type="array">
    <cc>user3@company3.com</cc>
    <cc>user4@company4.com</cc>
  </cc>
  <bcc type="array">
    <bcc>user@example.com</bcc>
    <bcc>boss@example.com</bcc>
  </bcc>
  <expires_in_format>weeks</expires_in_format>
  <expires_in>2</expires_in>
  <subject>test subject</subject>
  <message>test message</message>
  <attachments type='array'>
    <attachment>123456</attachment>
    <attachment>123457</attachment>
  </attachments>
  <send_email>true</send_email>
  <require_login>true</require_login>
  <bcc_myself>false</bcc_myself>
</message>

Example Message Response

<?xml version="1.0" encoding="UTF-8"?>
<message>
  <plain>
The following files are attached to this message:
  - secret_data.xls (11.04 KB)

Please visit the following url to download the attachments:
https://filetransfer.example.com/message/Ofm7B0AD059OC31THvMH3z

The attachments are available until Wed Apr 22 21:09:38 +0100 2009.


--
You have received attachment sent via an AllardSoft Secure File Transfer Appliance.
  </plain>
</message>

curl is a very handy tool for testing file uploads, api's and the like.

Using a simple unix shell script and curl, we're sending a file bigfile.zip to joe@customer.com:

#!/bin/sh

# Some nice variables
email="user@example.com"
password="password"
filetransfer="https://filetransfer.example.com"

# Get API key
api_key=`cat <<EOF | curl -s -X POST -H 'Content-Type: text/xml' -d @- $filetransfer/account | grep api_key\> | sed 's/.*api_key\>\(.*\)\<.*/\1/'
<?xml version="1.0" encoding="UTF-8"?>
<account>
  <email>$email</email>
  <password>$password</password>
</account>
EOF`

# Uploading the actual file and get attachment id for each file
attachment_id=`curl -X POST -F Filedata=@bigfile.zip -F api_key=$api_key $filetransfer/attachments`


# And finally send it
cat <<EOF | curl -s -X POST -H 'Content-Type: text/xml' -d @- $filetransfer/message
<?xml version="1.0" encoding="UTF-8"?>
<message>
  <api_key>$api_key</api_key>
  <recipients type="array">
    <recipient>joe@customer.com</recipient>
  </recipients>
  <bcc type="array">
    <bcc>$email</bcc>
  </bcc>
  <expires_in_format>weeks</expires_in_format>
  <expires_in>2</expires_in>
  <subject>Here's bigfile.zip you've been asking for</subject>
  <message>Please let me know what you think!</message>
  <attachments type='array'>
    <attachment>$attachment_id</attachment>
  </attachments>
  <send_email>true</send_email>
  <require_login>true</require_login>
</message>
EOF

Some times it's desirable to delete an attachment that has already been uploaded, to delete an attachment, send a http DELETE command to $filetransfer/attachments/$id?api_key=$api_key where $id is the attachment id and the $api_key is the api key.

An example using curl:

curl -s -X DELETE -H 'Content-Type: text/xml' https://test.host/attachments/123?api_key=DyTMSdfCduO5l6vfU823AA

this will delete attachment with id 123 if the api_key DyTMSdfCduO5l6vfU823AA is valid for the owner or attachment with id 123.

To list available attachments, send a http GET like below

An example using curl:

curl -s -X GET -H 'Content-Type: text/xml' https://test.host/attachments?api_key=DyTMSdfCduO5l6vfU823AA

<?xml version="1.0" encoding="UTF-8"?>
<attachments type="array">
  <attachment>
    <content-type>image/png</content-type>
    <filename>invoice-1.png</filename>
    <id type="integer">64</id>
    <size type="integer">147874</size>
  </attachment>
</attachments>

In this example, there's one available attachment.

The following plugin has been provided be external parties. Please post questions in the Support forum instead of opening tickets as unfortunately they can't be officially supported even though they are greatly appreciated. Thank you!

• C# Visual Studio 2008 Filetransfer API provided by Tino Hager from adrom.net