Transfer APIs
/api/transfer/initialize
Initiates and prepares a new transfer. TransferId, TransferKey and fileserver
information is returned.
logintoken
- Text - Retrieved by former invocation of /api/authentication/login in order to identify user. Skip this if the user does not have a Filemail Account. Optional.
to
- Text - Comma separated list of recipients (email addresses). Or name of ContactGroup to send to. Optional.
from
- Text - Email address of the person sending the files. Optional.
subject
- Text - Subject of email that is delivered to the recipient(s). Optional. Max 200 chars.
message
- Text - The message inserted in the email to the recipient(s). Optional.
notify
- True/False - Indicates whether you would like a email notification every time a file is downloaded. Optional.
confirmation
- True/False -Indicates whether you would like a email notification after the files have been successfully sent. Optional.
days
- Number - How many days the transfer can be downloaded. Set to default value of account if not specified. Optional.
password
- Text - Sets an additional password on the transfer which is required to download the files. Optional.
transfersize
- Number - Expected size of the entire transfer in bytes (i.e. how many bytes the client expects to upload). Optional.
-
source
- Text - Devicetype. Optional. Web = Default. Valid alternatives: Web
, Iphone
, Ipad
, WindowsPhone
, WindowsTab
, AndroidPhone
, AndroidTab
, Outlook
, Desktop
Example Request
API Address: https://www.filemail.com
POST /api/transfer/initialize?logintoken=2ac1241817fb4285aa0a1dbd00a21dad
&to=recipient@email.com&subject=Hi&message=Look%20at%20this¬ify=true&confirmation=true&days=10
&password=MySecretPass
Example Response
{
"transferid": "YSEVQIGGNLJFVFP",
"transferkey": "62612b1d95794a87a87e0d6cd4f65a0e",
"transferurl": "http://sl21.filemail.com/api/file/add",
"responsestatus": "ok"
}
Uploading files (savefile.ashx)
Files can be added to a transfer after it has been initialized with /api/transfer/initialize
.
Follow these guidelines to send files effecitvley:
- Use POST method.
- Use
Content-Type: application/octet-stream
request header and send binary file data directly in the POST body. E.g. in .NET use ByteArrayContent
together with PostAsync
method of a HttpClient
.
- Specify upload parameters in the request URL as query string (you can find list of parameters later in this section) - POST body is reserved for file contents.
- File upload URL is returned in the
transferurl
field of the JSON response after calling /api/transfer/initialize
e.g. https://8888.filemail.com/savefile.ashx
- In case the server returns 406 or 449 HTTP status - retry the request.
Chunking
When sending files larger than 50MB it is strongly recommended to perform upload in chunks - every chunk in a separate HTTPS request. It is not guaranteed that savefile.ashx
will accept requests larger than 50MB.
- Chunking allows to keep HTTP requests small and in turn makes retrying failed chunks easy. In case of a non-chunked upload a network failure at e.g. 90% of a 1GB file makes the retry-logic very inefficient.
- Pick a chunk size in the range of 5...50MB and add its value in bytes as query string parameter e.g. for 5MB chunks use
...&chunksize=5000000&...
. Note: this value should be constant for all chunks for a given file, even for the last chunk of a file (which is usually smaller than all the other chunks).
- Calculate total number of chunks as
Math.Ceiling(FileSize/ChunkSize)
and add it to every chunk request e.g. ...&chunks=13&...
- Note: when uploaded file is empty (size = 0 bytes) provide value
1
as the number of chunks.
- For every chunk specify
chunk
parameter - this is the chunk index (0-based).
- It is possible to upload multiple chunks in parallel - this may improve upload overall performance. We recommend to upload not more than 4 chunks in parallel.
Query string parameters:
transferid
- Text - Retrieved by former invocation of /api/transfer/initialize. Required.
transferkey
- Text - Retrieved by former invocation of /api/transfer/initialize. Required.
thefilename
- Text - the name of the file as it will appear in the transfer. Make sure this value is properly URL-encoded. Required.
chunksize
- Number - The expected number of bytes in every chunk. This value must be constant for all chunks of a given file - even for the last chunk. When a file contains 2 chunks, first chunk is 1MB and the second is 700kB - in the second chunk request specify the same chunksize as in the firsrt chunk request (i.e. chunksize=1000000
). Required when using chunking, otherwise optional.
chunks
- Number - The total number of chunks in the file. When file size is 0 bytes this value should be set to 1. Required when using chunking, otherwise optional.
chunk
- Number - Index of the current chunk being uploaded (0-based). Required when using chunking, otherwise optional.
md5
- Text - Base64-encoded MD5 hash of bytes sent in current HTTP request. When using chunking calculate this value for every chunk. E.g. 'MmdYzU+gCb+g/PqavfGttA=='. If the calculated hash on our server is different, then HTTP Status 449 is returned - meaning that the chunk must be uploaded again. Optional.
compressed
- True/False - Set to true if the data being sent is a compressed (zipped) stream. If this parameter is true our servers will unzip file contents on the fly before they are stored on our servers. Optional.
retry
- Number - 0-based index of the current retry attempt (if retries are used). This value is used only for tracking/logging purposes. Optional.
<POST BODY>
- Raw file data. Required.
Example Request (without body)
POST https://8888.filemail.com/savefile.ashx?
transferid=JIRPAXTDQMVAJZB&
transferkey=5812ea4388e24035abe5ba7cb06b3b47&
thefilename=big%20file.jpg&
chunksize=10000000&
chunks=13&
chunk=7&
retry=2
Host: 8888.filemail.com
Content-Type: application/octet-stream
Example Response
HTTP 200 OK (empty response body)
.NET code snippet - chunked upload
// WARNING: example code, not production-ready
public async Task UploadFile(string filePath)
{
/// ----- values obtained from /api/transfer/initialize
var transferid = "...";
var transferkey = "...";
var transferurl = "...";
/// -----
const int chunkSize = 5000000;
var chunk = -1;
var fi = new FileInfo(filePath);
var chunks = (int)Math.Ceiling((double)fi.Length / chunkSize);
var query = System.Web.HttpUtility.ParseQueryString(string.Empty);
query["transferid"] = transferid;
query["transferkey"] = transferkey;
query["thefilename"] = fi.Name;
query["chunks"] = chunks.ToString();
query["chunksize"] = chunkSize.ToString();
var buffer = new byte[chunkSize];
var httpClient = new HttpClient();
var uriBuilder = new UriBuilder(transferurl);
using (var fs = fi.OpenRead())
{
int read;
while ((read = await fs.ReadAsync(buffer, 0, buffer.Length)) > 0)
{
chunk += 1;
query["chunk"] = chunk.ToString();
uriBuilder.Query = query.ToString();
var request = new HttpRequestMessage(HttpMethod.Post, uriBuilder.ToString());
request.Content = new ByteArrayContent(buffer, 0, read);
request.Content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue(System.Net.Mime.MediaTypeNames.Application.Octet);
var response = await httpClient.SendAsync(request);
// a single chunk is uploaded now
// TODO: do something with the chunk response
}
}
// entire file is uploaded now - move on to next file in the transfer
}
/api/transfer/get
Returns files (with urls to retrieve files through HTTP GET) and other information related to the transfer.
transferid
- Text - Id of the transfer. Required.
logintoken
- Text - Retrieved by former invocation of /api/authentication/login in order to identify user. Skip this if the user does not have a Filemail Account. Optional.
filesLimit
- Number - maximum amount of files to return. Optional.
Example Request
API Address: https://www.filemail.com
GET /api/transfer/get?transferid=HGTUIJBGTRFGJPO&
Example Response
{
"transfer": {
"from": "sender@example.com",
"message": "Hey Tim, here are the files. Give me a holler when you have looked at them.",
"expiredate": 1354138194677,
"downloads": 20,
"sentdate": 1353878994677,
"files": [
{
"filename": "180x500_4_2.swi",
"filesize": 484095,
"downloadurl": "https://www.filemail.com/api/file/get?file...",
"fileid": "d9e234e17c0d49cf872e0f863ec6d87b",
"smallpreview": "https://www.filemail.com/images/icons/...png",
"largepreview": "https://www.filemail.com/images/icons/...png"
},
{
"filename": "test.mp3",
"filesize": 5922685,
"downloadurl": "https://www.filemail.com/api/file/get?file...",
"fileid": "d49e3f6d458343ab93dd64067686acf3",
"smallpreview": "https://www.filemail.com/images/icons/...png",
"largepreview": "https://www.filemail.com/images/icons/...png"
},
{
"filename": "63300102_Østbanebygn_M1etg_MIDL.dwg",
"filesize": 3678804,
"downloadurl": "https://www.filemail.com/api/file/get?file...",
"fileid": "972d75d29a55435480082d3ab2a5d50f",
"smallpreview": "https://www.filemail.com/images/icons/...png",
"largepreview": "https://www.filemail.com/images/icons/...png"
}
],
"notify": true,
"status": "STATUS_COMPLETE",
"id": "qxrfkirjzwjvwbp",
"url": "https://www.filemail.com/d/qxrfkirjzwjvwbp",
"size": 110093096
},
"responsestatus": "OK"
}
/api/transfer/complete
Marks the transfer as Complete and sends out email(s) to receivers. /api/transfer/get can now be invoked and the files can be downloaded.
transferid
- Text - ID of the transfer. Required.
transferkey
- Text - Key of the transfer. Required.
Example Request
API Address: https://www.filemail.com
POST /api/transfer/complete?logintoken=KDJF9JDF7JFN754H&transferid=HGTUIJBGTRFGJPO
&transferkey=3783hf73h783jhdf83j93k
Example Response
{
"responsestatus": "ok"
"downloadurl": "https://www.filemail.com/d/HGTUIJBGTRFGJPO"
}
/api/transfer/forward
Sends the original email to the given email address(es) and adds the given email address to the list of recipients for the transfer.
transferid
- Text - ID of the transfer. Required.
logintoken
- Text - Retrieved by former invocation of /api/authentication/login in order to identify user. Required.
to
- Text - Comma separated list of recipients (email addresses). Required.
Example Request
API Address: https://www.filemail.com
POST /api/transfer/forward?logintoken=203rj9apgu9ka3fq0lap43igvn4ak&transferid=HGTUIJBGTRFGJPO
&transferkey=3783hf73h783jhdf83j93k&to=test@asfasf.no
Example Response
{
"responsestatus": "ok"
}
/api/transfer/cancel
Cancels an unfinished transfer
transferid
- Text - ID of the transfer. Required.
transferkey
- Text - Key of the transfer. Required.
Example Request
API Address: https://www.filemail.com
POST /api/transfer/cancel?logintoken=KDJF9JDF7JFN754H&transferid=HGTUIJBGTRFGJPO
&transferkey=3783hf73h783jhdf83j93k
Example Response
{
"responsestatus": "ok"
}
/api/transfer/delete
Deletes transfer
transferid
- Text - ID of the transfer. Required.
logintoken
- Text - Retrieved by former invocation of /api/authentication/login in order to identify user. Required.
Example Request
API Address: https://www.filemail.com
POST /api/transfer/delete?logintoken=KDJF9JDF7JFN754H&transferid=HGTUIJBGTRFGJPO
Example Response
{
"responsestatus": "ok"
}
/api/transfer/file/rename
Renames file in a transfer
logintoken
- Text - Retrieved by former invocation of /api/authentication/login in order to identify user. Required.
fileid
- Text - ID of file to rename. Required.
filename
- Text - New filename. Avoid the characters <
>
:
"
/
\
|
?
*
Required.
Example Request
API Address: https://www.filemail.com">https://www.filemail.com
POST /api/transfer/file/rename?logintoken=KDJF9JDF7JFN754H&fileid=8H6GHn6GBD65290J&filename=NewFile.txt
Example Response
{
"responsestatus": "ok"
}
/api/transfer/file/delete
Removes file from transfer. Remember to also update the ZIP file by invoking /api/ziptransfer after removing files
logintoken
- Text - Retrieved by former invocation of /api/authentication/login in order to identify user. Required.
fileid
- Text - Id of file to delete. Required.
Example Request
API Address: https://fileserver926.filemail.com
POST /api/transfer/file/delete?logintoken=KDJF9JDF7JFN754H&fileid=8H6GHn6GBD65290J
Example Response
{
"responsestatus": "ok"
}
/api/transfer/update
Updates properties for a transfer
logintoken
- Text - Retrieved by former invocation of /api/authentication/login in order to identify user. Required.
transferid
- Text - Id of the transfer. Required.
message
- Text - Updates the message field of the transfer. Optional.
subject
- Text - Updates the subject field of the transfer. Optional.
days
- Number - How many days the transfer can be downloaded. Optional.
notify
- True/False - Indicates whether you would like a email notification every time a file is downloaded. Optional.
Example Request
API Address: https://www.filemail.com
POST /api/transfer/update?logintoken=KDJF9JDF7JFN754H&transferidid=HGTUIJBGTRFGJPO
&message=This%20is%20the%20new%20message&days=30
Example Response
{
"responsestatus": "ok"
}
/api/transfer/sent/get
Returns list of transfers sent by user. If the user is Administrator of a
Filemail Business account - then transfers for all users in the company can be
returned.
InputParameters:
-
logintoken
- Text - The logintoken of the authenticated user. Required.
-
getexpired
- True/False - Option to include expired transfers. Optional. Default: false
-
getforallusers
- True/False - Option to include transfers sent by all users in a company. Only works for an admin of a Filemail Business account. Optional. Default: false
Example Request
API Address: https://www.filemail.com
GET /api/transfer/sent/get?&logintoken=2ac1241817fb4285aa0a1dbd00a21dad
Example Response
{
"transfers": [
{
"from": "sender4@filemail.com",
"subject": "s2",
"message": "m2",
"expiredate": 1350314399,
"downloads": 22,
"sentdate": 1350055199,
"files": [], //Invoke /api/transfer/get in order to get filelist for this transfer.
"notify": false,
"responsestatus": "STATUS_COMPLETE",
"id": "JZGRNCULDOIMIVL"
}
],
"responsestatus": "OK"
}
/api/transfer/received/get
Returns list of transfers sent to the user's email address. If the user is an Administrator of a Filemail Business account - then transfers sent to all of the company users can be returned.
InputParameters:
-
logintoken
- Text - The logintoken of the authenticated user. Required.
-
getForAllUsers
- True/False - Option to include transfers received by all users in a company. Only works for an admin of a Filemail Business or Enterprise account and when the admin is configured to access other users' files. Optional. Default: false.
-
from
- Number (unixtime in milliseconds since 1970.1.1) - Retrieves transfers received only after this date. When not specified all long-term transfers are returned and regular transfers not older than 90 days. Optional.
Example Request
API Address: https://www.filemail.com
GET /api/transfer/received/get?logintoken=2ac1241817fb4285aa0a1dbd00a21dad
Example Response
{
"transfers": [
{
"subject": "s1",
"message": "m1",
"expiredate": 1350564097,
"downloads": 20,
"sentdate": 1350304897,
"files": [], //Invoke /api/transfer/get in order to get filelist for this transfer.
"notify": false,
"responsestatus": "STATUS_COMPLETE",
"id": "WHVAYVYMFCGUNMT"
}
],
"responsestatus": "OK"
}