Transfers - API - Filemail

/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&notify=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"
}

Transfer APIs

/api/transfer/initialize

Example Request

Example Response

Uploading files (savefile.ashx)

Chunking

Query string parameters:

Example Request (without body)

Example Response

.NET code snippet - chunked upload

/api/transfer/get

Example Request

Example Response

/api/transfer/complete

Example Request

Example Response

/api/transfer/forward

Example Request

Example Response

/api/transfer/cancel

Example Request

Example Response

/api/transfer/delete

Example Request

Example Response

/api/transfer/file/rename

Example Request

Example Response

/api/transfer/file/delete

Example Request

Example Response

/api/transfer/update

Example Request

Example Response

/api/transfer/sent/get

Example Request

Example Response

/api/transfer/received/get

Example Request

Example Response