The most common function of the API is to send files. This page covers how to achieve that.
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.
| Parameter | Description |
|---|---|
| Filedata | The actual file data |
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 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="Filedata"; filename="filename.ext" Content-Type: text/plain ... contents of filename.ext ... --AaB03x--
| Response | Description |
|---|---|
| attachment id | The unique attachment id for the uploaded file, this needs to be added to the message later |
Example Response
123456
The message request is the final piece used to send the actual message.
URL: The POST request needs to be sent to /message, i.e. https://filetransfer.example.com/message.
| Parameter | Type | Description |
|---|---|---|
| recipients | array | an array of recipients i.e. To in the email header |
| cc | array | an array of cc's i.e. cc in the email header |
| bcc | array | an array of bcc's i.e. bcc in the email header |
| subject | string | the email subject |
| message | string | the body of the email |
| expires_at | string | when the file is expiring in iso format (YYYY-mm-dd) |
| attachments | array | an array of uploaded attachments, these values comes from the upload function above |
| send_email | boolean | true means that the Filetransfer appliance will send the email, false means that the API client has to send the email with the message itself |
| require_login | boolean | true means that only listed recipients (to, cc and bcc and the sender) can download the files and will be prompted for authentication, false means that anyone who has the link can download the files and will not be prompted for authentication |
| bcc_myself | boolean | true will send a copy to the sender. It defaults to true if not present. |
Example Message request
<?xml version="1.0" encoding="UTF-8"?>
<message>
<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_at>2011-01-29</expires_at>
<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>
| Response | Type | Description |
|---|---|---|
| plain | Text | If the Filetransfer appliance is not sending the email, this footer in plain text needs to be appended to the final message to point the user to the files for download |
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:
Please note the ”@” in @bigfile.zip in the example below. This is what tells curl to read the data and include the content from bigfile.zip instead of adding bigfile.zip as text string.
#!/bin/sh
# Some nice variables
api_key="Y9fdTmZdv0THButt5ZONIY"
filetransfer="https://filetransfer.example.com"
# Uploading the actual file and get attachment id for each file
attachment_id=`curl -X POST --user "$api_key:x" -F Filedata=@bigfile.zip $filetransfer/attachments`
# And finally send it
cat <<EOF | curl -s -X POST --user "$api_key:x" -H 'Content-Type: text/xml' -d @- $filetransfer/message
<?xml version="1.0" encoding="UTF-8"?>
<message>
<recipients type="array">
<recipient>joe@customer.com</recipient>
</recipients>
<bcc type="array">
<bcc>$email</bcc>
</bcc>
<expires_at type="date">2011-04-02</expires_at>
<subject>Here's the secret image we talked about.</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