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&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"
}