Getting started

This area will help you get started with Filemail API. Learn more about obtaining your API key, authentication, versioning, rate limits and more.

API Overview

The Filemail API is accessible through an HTTP interface.

Base URL of the API: https://api-public.filemail.com

All endpoints accept JSON-encoded (Content-Type: application/json) request bodies, and return JSON-encoded responses.

One exception regarding content type is the /savefile.ashx endpoint used for file uploads. You can find more details about it here: Upload files

API Keys

Accessing the Filemail API requires an API key. Log in to your Filemail account and head to the API Key section. You can create, delete and rotate your API key there.

If you don't have an account yet, you can create it here: https://www.filemail.com/price-plans-comparison. Note that only Personal, Pro, Business and Enterprise accounts have access to our API.

The API key is linked directly to your Filemail user. Anyone in possession of your API key is able to authenticate with Filemail (same as if they had your login and password) and perform operation. on behalf of your Filemail user account.

For this reason you should secure your account key. Do not expose it to public, don't embed it in any client-side JavaScript code and don't store it in code repositories.

Authentication with the API Key

Every request to Filemail API must include an x-api-key header containing a valid API key:

x-api-key: mJE5v1zHs....

Any request without an API key will be rejected with a 401 HTTP status. As mentioned in the previous section, an API key automatically authenticates requests as the Filemail user who owns the API key.

Custom authentication

It is possible to act on behalf of other users as well. Please refer to Custom authentication article and learn how to obtain a logintoken and a refreshtoken. These two combined will allow making requests on behalf of other users. This functionality can be used for building standalone apps which integrate with Filemail file sharing infrastructure. Once obtained, the logintoken must be appendedas a request header, together with an API key. The request will be authenticated with logintoken which is taking precedence before x-api-key .

x-api-key: mJE5v1zHs....
logintoken: r9BPAFW.....

Versioning

All requests to the Filemail API must include an x-api-version header. This header determines which version-specific logic will be executed by the Filemail server. This approach makes it very clear to API consumers what version of the API endpoint they are using. This in turn provides consistent behavior and eliminates any unexpected changes in API processing logic, validation, and response formats.

• Default Requirement: If an endpoint does not specify versioning details in its documentation, it only supports version 2.0. This value must be used in the x-api-version header.

• Multiple Versions: If an endpoint supports multiple versions, the documentation will list them. You must specify either 2.0 or one of the listed custom versions in the header accordingly.

Example request header for an endpoint which has no versioning specification:

x-api-key: mJE5v1zHs....
x-api-version: 2.0

Rate limits

Filemail API employs a protective rate limit to ensure stability and prevent abuse. Specifically, the API is limited to 20 requests every 10 seconds.

Exceeding the rate limit will result in request rejection with HTTP status 429 .

Daily quotas

In addition to the protective rate limit every Filemail subscription plan is assigned with a daily quota of API requests. The quota is refilled constantly using a leaky-bucket algorithm. This means that once you exhaust your daily quota, it starts refilling soon after. E.g. when the quota is 2400 requests per day, then you'll get 100 requests available 1 hour after quota has been exhausted.

Exceeding your daily quota will result in request rejection with HTTP status 429 .

More information on specific quotas per subscription plan will be announced soon. Stay tuned. 📻