# Filemail API 2.0 We’re excited to introduce you to the Filemail API v2 — a powerful and flexible interface designed to let you build custom integrations with Filemail’s file transfer services. #### What Is the Filemail API? The Filemail API v2 offers a modern, streamlined approach to programmatically interact with the Filemail platform. Whether you’re looking to automate transfers, build custom workflows, or embed Filemail capabilities into your own software, this API gives you full control and adaptability. #### Getting Access Access to the API will be available **soon**. We’re putting the final touches on a seamless onboarding experience. When ready, developers will be able to request API credentials directly from their Filemail account dashboard. Stay tuned for updates — we’ll notify you here when access becomes available. #### What You’ll Find Here This documentation includes everything you need to get started: * **Authentication** – Secure access using API tokens. * **Endpoints** – Clear, categorized reference for all available operations. * **Examples** – Real-world usage examples to speed up development. * **Error Handling** – Consistent and predictable response patterns. * **Best Practices** – Recommendations to ensure robust and efficient integrations. #### Built for Customization From simple automation scripts to full-scale enterprise solutions, Filemail API v2 is built to adapt to your needs. Whether you're sending massive files, tracking downloads, or building end-to-end client portals, this API enables it. # 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/sending-files/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](https://app.filemail.com/settings#apikeys). You can create, delete and rotate your API key there. If you don't have an account yet, you can create it here: . Note that only Personal, Pro, Business and Enterprise accounts have access to our API. {% hint style="warning" %} 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. {% endhint %} ## 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](/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. :radio: # Error handling Find out how Filemail API notifies about errors. When the API returns HTTP code greater or equal to `400` then the request must be treated as failed. Here are a few typical HTTP status codes you might expect: * `400 Bad request` - your request was incorrectly formatted, the content type was incorrect, some parameters were missing, the parameters provided were not correct. * `401 Unauthorized` - missing or incorrect api key or logintoken. * `404 Not found` - misspelled endpoint name. * `409 Conflict` - the operation could not be performed due to invalid state of your account or transfer. This code also covers cases related to infected files, blocked content and storage limits reached. * `429 Too many requests` - rate limit or daily quota exceeded. * `500 Internal server error` - an unexpected server error occurred. This usually means you'll need to contact support so we can investigate the problem. When you encounter any of the error codes be ready to parse the response to figure out the error details and act upon it. Here is the schema for a typical error response and a validation error (error responses usually include an array of validation errors under `validationerrors` field): ## The FilemailErrorResponse object ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"components":{"schemas":{"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"}}}} ``` ## The ValidationError object ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"components":{"schemas":{"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"}}}} ``` # Fetching user information This short article explains how you can fetch information about current user. To use this endpoint, ensure that authentication is performed beforehand. Refer to the [Getting Started guide](/filemail-api-2.0/getting-started#authentication-with-the-api-key) for detailed instructions. This endpoint provides all details about current user. ## GET /user/me > ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"User"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/user/me":{"get":{"tags":["User"],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/UserBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/UserBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/UserBaseResponse"}}}},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"text/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"UserBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/User"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"User":{"type":"object","properties":{"maxdownloads":{"type":"integer","format":"int32"},"maxdays":{"type":"integer","format":"int32"},"maxtransfersize":{"type":"integer","format":"int64"},"membershipname":{"type":"string"},"istrial":{"type":"boolean"},"defaultnotify":{"type":"boolean"},"defaultdays":{"type":"integer","format":"int32"},"defaultconfirmation":{"type":"boolean"},"defaultdownloads":{"type":"integer","format":"int32"},"id":{"type":"string"},"dlc":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"intercomhash":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"mobilephone":{"type":"string","nullable":true},"signature":{"type":"string","nullable":true},"defaultsubject":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"newsletter":{"type":"boolean","nullable":true},"allowCommunicationEmails":{"type":"boolean","nullable":true},"startpage":{"type":"string","nullable":true},"created":{"type":"integer","format":"int64"},"ssoPlatform":{"type":"string","nullable":true},"cansend":{"type":"boolean"},"expired":{"type":"boolean"},"emailverifiedforsending":{"type":"boolean"},"freelimitreached":{"type":"boolean"},"companyname":{"type":"string","nullable":true},"companyid":{"type":"string","nullable":true},"admin":{"type":"boolean","nullable":true},"role":{"type":"integer","format":"int32"},"forcepasswordonincoming":{"type":"boolean","nullable":true},"canreceivefiles":{"type":"boolean","nullable":true},"buttonscolor":{"type":"string","nullable":true},"buttonstextcolor":{"type":"string","nullable":true},"companylogo":{"type":"string","nullable":true},"showallrecipients":{"type":"boolean"},"canstorefilesforever":{"type":"boolean"},"enforcepasswordpolicy":{"type":"boolean"},"udpenabled":{"type":"boolean"},"allowunlimiteddays":{"type":"boolean"},"allow3months":{"type":"boolean"},"canAccessOthersFiles":{"type":"boolean","nullable":true},"subscription":{"$ref":"#/components/schemas/Subscription"},"storageinuse":{"type":"integer","format":"int64","nullable":true},"storagelimit":{"type":"integer","format":"int64","nullable":true},"passwordMinLength":{"type":"integer","format":"int32","nullable":true},"contactgroups":{"type":"array","items":{"$ref":"#/components/schemas/ContactGroup"}},"twoFactorEnabled":{"type":"boolean","nullable":true},"loglevel":{"type":"string","nullable":true},"maxrecipients":{"type":"integer","format":"int32","nullable":true},"maxrecipientsaftertrial":{"type":"integer","format":"int32","nullable":true},"allowautodownloads":{"type":"boolean"},"allowpasswordprotection":{"type":"boolean"},"allowdownloadtracking":{"type":"boolean"},"allowe2ee":{"type":"boolean"},"allowfilesdb":{"type":"boolean","nullable":true},"allowPortals":{"type":"boolean"},"allowMultiplePortals":{"type":"boolean"},"canManageSubscription":{"type":"boolean"},"requireE2EEwhenSending":{"type":"boolean","nullable":true},"requireE2EEwhenReceiving":{"type":"boolean","nullable":true}},"additionalProperties":false},"Subscription":{"type":"object","properties":{"active":{"type":"boolean"},"expireDate":{"type":"integer","format":"int64","nullable":true},"currency":{"type":"string"},"interval":{"type":"string"},"membershipname":{"type":"string"},"showExVatLabelOnPrices":{"type":"boolean"},"allowMultipleUsers":{"type":"boolean"},"licenseCount":{"type":"integer","format":"int32"},"licensePrice":{"type":"number","format":"double"},"pricePerTBPerUser":{"type":"number","format":"double"},"subscriptionPrice_Users":{"type":"number","format":"double"},"subscriptionPrice_Storage":{"type":"number","format":"double"},"subscriptionPrice_Total":{"type":"number","format":"double"},"paymentGateway":{"$ref":"#/components/schemas/PaymentGateways"},"licensesInUse":{"type":"integer","format":"int32"},"canChangePlan":{"$ref":"#/components/schemas/SettingsFeatureDto"},"canUpdatePaymentMethod":{"$ref":"#/components/schemas/SettingsFeatureDto"},"changeSubscriptionMobileAppLink":{"type":"string","nullable":true},"canChangeInterval":{"$ref":"#/components/schemas/SettingsFeatureDto"},"canManageLicenses":{"$ref":"#/components/schemas/SettingsFeatureDto"},"canChangeLicenseCount":{"$ref":"#/components/schemas/SettingsFeatureDto"},"canCancel":{"$ref":"#/components/schemas/SettingsFeatureDto"},"canUpgrade":{"$ref":"#/components/schemas/SettingsFeatureDto"},"isTrial":{"type":"boolean"},"nextPaymentDate":{"type":"integer","format":"int64","nullable":true},"paymentMethod":{"$ref":"#/components/schemas/PaymentMethodDto"},"storageBytesInUse":{"type":"integer","format":"int64"},"storageBytesLimit":{"type":"integer","format":"int64"},"storageBytesIncludedInMembership":{"type":"integer","format":"int64"},"storageBytesAdditional":{"type":"integer","format":"int64"}},"additionalProperties":false},"PaymentGateways":{"enum":["PayPal","PayEx","Chargify","None","PowerOffice","Braintree","AppStore","PlayStore","Stripe"],"type":"string"},"SettingsFeatureDto":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/SettingsFeatureState"},"reason":{"type":"string","nullable":true},"link":{"type":"string","nullable":true}},"additionalProperties":false},"SettingsFeatureState":{"enum":["active","hidden","blocked"],"type":"string"},"PaymentMethodDto":{"type":"object","properties":{"paymentMethod":{"$ref":"#/components/schemas/PaymentMethod"},"creditCardBrand":{"type":"string","nullable":true},"creditCardLast4":{"type":"string","nullable":true},"creditCardName":{"type":"string","nullable":true},"creditCardExpireYear":{"type":"integer","format":"int32","nullable":true},"creditCardExpireMonth":{"type":"integer","format":"int32","nullable":true},"payPalEmail":{"type":"string","nullable":true},"paymentMethodTextInfo":{"type":"string","nullable":true}},"additionalProperties":false},"PaymentMethod":{"enum":["PayPal","CreditCard","Invoice","AppStore","GooglePay","Uknown","Digital"],"type":"string"},"ContactGroup":{"type":"object","properties":{"numberofcontacts":{"type":"integer","format":"int32","nullable":true},"contactgroupid":{"type":"string"},"contactgroupname":{"type":"string"},"corp_shared":{"type":"boolean"},"allow_edit":{"type":"boolean"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/Contact"},"nullable":true}},"additionalProperties":false},"Contact":{"type":"object","properties":{"contactid":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"mobile":{"type":"string"},"corp_shared":{"type":"boolean"},"allow_edit":{"type":"boolean"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/ContactGroup"}}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true},"extensions":{"type":"object","additionalProperties":{"nullable":true}}},"additionalProperties":false}}}} ``` # Sending files This will show you the flow of how to send files with the Filemail API This is the typical flow on how you would send files using the Filemail API: {% stepper %} {% step %} ### Call Initialize You [Initialize](/api/sending-files/initialize) the transfer with all meta data so you get the information you need in order to start uploading the files. {% endstep %} {% step %} ### Add files/folders to the Transfer The call to Initialize will return URL and credentials which you will use to upload actual files. You can find more information about this process on the [Upload files](/api/sending-files/upload-files) page. {% endstep %} {% step %} ### Finalize the Transfer by calling Complete When all files has finished uploading, you activate the transfer by calling [Complete](/api/sending-files/complete). {% endstep %} {% endstepper %} The specification for each step and how to do this is described in the sub pages. Remember to first read the section about [Custom authentication](/custom-authentication) # Initialize ## POST /transfer/initialize > Creates a new transfer, returns upload URL and credentials. This operation must be performed before any files can be uploaded to Filemail. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Transfer"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/transfer/initialize":{"post":{"tags":["Transfer"],"description":"Creates a new transfer, returns upload URL and credentials. This operation must be performed before any files can be uploaded to Filemail.","requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/InitializeTransferRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/InitializeTransferRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/InitializeTransferRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/InitializeTransferRequest"}}}},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/TransferInitializeResultBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/TransferInitializeResultBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/TransferInitializeResultBaseResponse"}}}},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"409":{"description":"Conflict","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"InitializeTransferRequest":{"required":["subject"],"type":"object","properties":{"to":{"type":"array","items":{"type":"string"},"description":"List of recipients (email addresses). After transfer is complete we will send out download URL to every email in this list. Every specified recipient will receiving a unique download link, which allows the sender to track who and when downloaded the files. When this value is not specified - we will not send any emails and the transfer will be available only by sharing a common private link.","nullable":true},"subject":{"maxLength":200,"minLength":1,"type":"string","description":"Transfer subject. This value will be used on download pages as the main title, and as the subject of emails that are sent to recipients."},"message":{"maxLength":5000,"type":"string","description":"Transfer message. We will use this text as the introductory paragraph on download pages, and as the main body of emails that are sent to recipients.","nullable":true},"password":{"type":"string","description":"Optional password that protects the transfer. When specified: access to download page, downloading the files and fetching transfer details will be possible only after providing the password.","nullable":true},"confirmation":{"type":"boolean","description":"When set to `true` we will send out a confirmation email to the sender after transfer is complete.","nullable":true},"notify":{"type":"boolean","description":"When set to `true` we will send out a confirmation email to the sender after transfer is downloaded. When recipients have been specified in the `to` field, the notification email will include information about a specific recipient who performed a particular download. Note: we will send one email after first download, and a final summary email after the second download.","nullable":true},"days":{"type":"integer","description":"The number of days until the transfer expires. Expiration is counted since the date of transfer creation. Use `-1` to create a permanent transfer (one that never expires). Note: permanent transfers is a feature available only for specific Filemail plans. Please refer to our plan comparison page at https://www.filemail.com/price-plans-comparison.","format":"int32","nullable":true},"transfersize":{"type":"integer","description":"Informational field - expected size of the transfer in bytes. For classic uploads this value is persisted at initialize time. For FilesDB uploads this value is treated only as an initialize-time estimate; the actual reserved size is recalculated from registered or attached items.","format":"int64","nullable":true},"filesdb":{"type":"boolean","nullable":true},"sourcedetails":{"type":"string","description":"Informational field - you can use it to mark the code library or user-agent used to create the transfer.","nullable":true},"companyid":{"type":"string","description":"Identifier of a corporation when creating an 'Incoming' transfer. In this case transfer will belong to the receiving company, not the sender.","nullable":true},"fileRequestId":{"type":"string","description":"When creating an 'Incoming' transfer - id of the associated file request. Using this value will link the transfer to a 'File request'. Must match the provided `companyid`.","nullable":true},"fileRequestShareId":{"type":"string","description":"When creating an 'Incoming' transfer - id of the associated file request share. Using this value will link the transfer to a specific person, with whom a 'File request' has been shared. Must match the provided `companyid`.","nullable":true},"incomingpageid":{"type":"string","description":"When creating an 'Incoming' transfer - id of the associated incoming page. Using this value will link the transfer to a specific incoming page and allows to use the page-specific custom fields.","nullable":true},"incomingpassword":{"type":"string","description":"When the page specified via `incomingpageid` is password protected - you must provide the password to be able to create transfer linked to that page.","nullable":true},"customfields":{"type":"array","items":{"$ref":"#/components/schemas/CustomFieldValue"},"description":"When creating an 'Incoming' transfer - list of objects that will become custom fields of the transfer. Look up the term `custom fields` in the documentation to learn more.","nullable":true}},"additionalProperties":false},"CustomFieldValue":{"required":["id","value"],"type":"object","properties":{"id":{"minLength":1,"type":"string"},"value":{"maxLength":5000,"minLength":1,"type":"string"}},"additionalProperties":false},"TransferInitializeResultBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/TransferInitializeResult"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"TransferInitializeResult":{"type":"object","properties":{"transferid":{"type":"string"},"transferkey":{"type":"string"},"transferurl":{"type":"string"},"region":{"type":"string","nullable":true},"alternate_urls":{"type":"array","items":{"type":"string"}},"transferip":{"type":"string"},"udpport":{"type":"integer","format":"int32","nullable":true},"udpthreshold":{"type":"integer","format":"int32","nullable":true},"customfields":{"type":"object","additionalProperties":{"type":"string"}},"filesdb":{"$ref":"#/components/schemas/TransferInitializeFilesDbResult"}},"additionalProperties":false},"TransferInitializeFilesDbResult":{"type":"object","properties":{"enabled":{"type":"boolean"},"uploadurl":{"type":"string"},"ackurl":{"type":"string"}},"additionalProperties":false},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` # Upload files Here you can find all the detailed information and API specification for uploading files to a transfer. Files can be added to a transfer after it has been initialized with [Initialize](/api/sending-files/initialize). It is also possible to add files to existing transfers after they are completed (after calling [Complete](/api/sending-files/complete)). 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`](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.bytearraycontent?view=net-8.0) together with [`PostAsync`](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient.postasync?view=net-8.0#system-net-http-httpclient-postasync\(system-string-system-net-http-httpcontent-system-threading-cancellationtoken\)) method of a [`HttpClient`](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient?view=net-8.0). * Specify [upload parameters](#query-string-parameters) in the request query string. Please note that the request body is reserved for file binary data. * File upload URL is returned in the `data.transferurl` field of the JSON response after calling [Initialize](/api/sending-files/initialize). Expect a value similar to `https://8888.filemail.com/savefile.ashx` . * In case the server returns HTTP status `406` or `449` during file upload - retry the request. * If you are uploading lots of smaller files you will benefit from uploading a few files in parallel. Keep the number of parallel files on a reasonably low level (2 ... 4) in order to prevent bandwidth saturation. ### Chunking {% hint style="info" %} When sending files larger than 50MB it is strongly recommended to perform upload in chunks. Send each chunk in a separate HTTPS request. It is not guaranteed that Filemail Fileservers will accept requests larger than 50MB. {% endhint %} Key points around chunking: * 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 the number of bytes as query string parameter e.g. for a 5MB chunk 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 uploading an empty (zero-byte) file - specify `chunks=1`. * For every chunk specify `chunk` parameter - this is the 0-based chunk index. * It is possible to upload multiple chunks in parallel - this may improve upload overall performance. We recommend to upload at most 4 chunks in parallel. ### Query string parameters: * `transferid` - Text - retrieved from [Initialize](/api/sending-files/initialize) -> `data.transferid` * `transferkey` - Text - retrieved from [Initialize](/api/sending-files/initialize)-> `data.transferkey` * `thefilename` - Text - name of the file as it will appear in the transfer. Make sure this value is properly URL-encoded. * `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 one (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 - Zero-based index of the current chunk being uploaded. 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` - Bool - 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 - Zero-based index of the current retry attempt (if retries are in use). This value is used only for tracking/logging purposes. Optional. ### 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 Below code illustrates how you can upload a single file with chunking, but without any parallelism. Here we use 5 MB chunks. ``` // WARNING: example code, not production-ready public async Task UploadFile(string filePath) { /// ----- values obtained from /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 } ``` {% hint style="info" %} The above code loads every chunk into memory (see the `buffer` variable and `fs.ReadAsync` method call). If you absolutely need to minimize memory pressure you can upload entire file using streaming. This might not work for large files though. Check out .NETs [`StreamContent`](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.streamcontent?view=net-9.0): ``` var request = new HttpRequestMessage(HttpMethod.Post, uri); request.Content = new StreamContent(fs); ``` {% endhint %} # Cancel ## PUT /transfer/cancel > Cancels a pending transfer. This operation can be performed only if the transfer has not been completed yet. After cancellation the transfer is not available and any uploaded files are scheduled for removal from our servers. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Transfer"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/transfer/cancel":{"put":{"tags":["Transfer"],"description":"Cancels a pending transfer. This operation can be performed only if the transfer has not been completed yet. After cancellation the transfer is not available and any uploaded files are scheduled for removal from our servers.","requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/CancelTransferRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/CancelTransferRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/CancelTransferRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/CancelTransferRequest"}}}},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/BaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"CancelTransferRequest":{"required":["transferid","transferkey"],"type":"object","properties":{"transferid":{"minLength":1,"type":"string","description":"ID of the transfer to be cancelled (retrevied in the 'Initialize' response)."},"transferkey":{"minLength":1,"type":"string","description":"Secret key of the transfer to be cancelled (retrevied in the 'Initialize' response)."}},"additionalProperties":false},"BaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` # Complete ## PUT /transfer/complete > Completes a transfer after all files have been uploaded. This operation makes the transfer available for downloads and sends out emails to recipients, and optionally to the sender. The response also includes a common (non-tracked) URL to the download page for this transfer. Downloading files at this URL will record downloads, but not linked to any recipient. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Transfer"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/transfer/complete":{"put":{"tags":["Transfer"],"description":"Completes a transfer after all files have been uploaded. This operation makes the transfer available for downloads and sends out emails to recipients, and optionally to the sender. The response also includes a common (non-tracked) URL to the download page for this transfer. Downloading files at this URL will record downloads, but not linked to any recipient.","requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/CompleteTransferRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/CompleteTransferRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/CompleteTransferRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/CompleteTransferRequest"}}}},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/TransferCompleteResultBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/TransferCompleteResultBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/TransferCompleteResultBaseResponse"}}}},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"409":{"description":"Conflict","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"CompleteTransferRequest":{"required":["transferid","transferkey"],"type":"object","properties":{"transferid":{"minLength":1,"type":"string","description":"ID of the transfer to be completed (retrieved in the 'Initialize' response)."},"transferkey":{"type":"string","description":"Secret key of the transfer to be completed (retrieved in the 'Initialize' response).","format":"uuid"}},"additionalProperties":false},"TransferCompleteResultBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/TransferCompleteResult"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"TransferCompleteResult":{"required":["downloadurl"],"type":"object","properties":{"downloadurl":{"minLength":1,"type":"string","description":"URL of the download page for the completed transfer. This URL is valid for as long as the transfer is not expired. Using this URL to download files will register downloads, but the download data will only include the IP of the end user, but will not link any recipient data. I.e. this URL is not a tracked-url (as opposed to URLs included in emails which are sent to transfer recipients)."},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/TransferRecipient"},"description":"The final list of transfer recipients including their transfer URLs with tracking IDs included.","nullable":true},"confirmationUrl":{"type":"string","description":"Optional. The resolved custom confirmation URL for this portal upload, with placeholder tokens substituted. Only present when the portal has a configured custom confirmation URL and that URL passes safety validation.","nullable":true}},"additionalProperties":false},"TransferRecipient":{"type":"object","properties":{"email":{"type":"string","nullable":true},"downloadlink":{"type":"string","nullable":true},"delivered":{"type":"boolean"},"deliveryerror":{"type":"string","nullable":true}},"additionalProperties":false},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` # Getting received files Learn about listing all files received by one or more accounts within an organization using the Filemail API. Use the [#get-transfer-inbox](#get-transfer-inbox "mention") endpoint to list all transfers received by a user, or received by any user in an organization (Admin role is required in this case). The response will provide details about each transfer, including transfer IDs needed to fetch the transfer details using [Getting transfer details](/getting-transfer-details). ## GET /transfer/inbox > Returns a list of transfers received by currently authenticated user, or received by all users in the authenticated user's organization. Optionally allows to filter transfers received only after specified date. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Transfer"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/transfer/inbox":{"get":{"tags":["Transfer"],"description":"Returns a list of transfers received by currently authenticated user, or received by all users in the authenticated user's organization. Optionally allows to filter transfers received only after specified date.","parameters":[{"name":"from","in":"query","description":"The start date for filtering received transfer. Only transfers received after this date will be returned. Expected format: unix time in milliseconds.","schema":{"type":"integer","format":"int64"}},{"name":"getForAllUsers","in":"query","description":"When set to true the response will include also transfers received by other users in the organization. In case current user is not an organization administrator - this flag will be ignored.","schema":{"type":"boolean"}},{"name":"portalId","in":"query","description":"Specify a list of portal IDs to get only transfers sent to those portals.","schema":{"type":"array","items":{"type":"string"}}},{"name":"getexpired","in":"query","description":"When set to true the response will include also expired transfers.","schema":{"type":"boolean"}},{"name":"limit","in":"query","description":"Optional amount of inbox items to fetch (paging). Defaults to custom max page size specified for a company account, or system default (1000).","schema":{"type":"integer","format":"int32"}},{"name":"skip","in":"query","description":"Optional amount of inbox items to skip (paging). Defaults to 0.","schema":{"type":"integer","format":"int32"}},{"name":"search","in":"query","description":"Optional search phrase, which will filter transfers by ID, subject, message, sender, recipients and custom fields.","schema":{"type":"string"}},{"name":"ignoreDeletedPortals","in":"query","description":"Optional boolean flag. Set to true if you want the API to ignore case, when some of provided portal IDs are deleted. When this flag is not set, it defaults to false, and then this endpoint will throw a 409 error if any of provided portals has been deleted.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/TransferListDtoBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/TransferListDtoBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/TransferListDtoBaseResponse"}}}},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"TransferListDtoBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/TransferListDto"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"TransferListDto":{"type":"object","properties":{"transfers":{"type":"array","items":{"$ref":"#/components/schemas/Transfer"},"description":"The list of transfers that match the request specification."},"portal":{"$ref":"#/components/schemas/PortalLeftMenuDto"},"inboxOwner":{"$ref":"#/components/schemas/User"}},"additionalProperties":false},"Transfer":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string"},"description":"This property is obsolete. Use 'recipients' property instead.","deprecated":true},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/TransferRecipient"},"description":"List of transfer recipients."},"failedRecipients":{"type":"integer","format":"int32"},"from":{"type":"string","description":"The sender's email address.","nullable":true},"subject":{"type":"string"},"message":{"type":"string"},"expiredate":{"type":"integer","description":"Transfer expiration date, as unix time, in milliseconds. To check if a transfer is permanent use the 'permanent' property.","format":"int64"},"extendedexpiredate":{"type":"integer","description":"Extended transfer expiration date, as unix time, in milliseconds. This value is only available if transfer was successfully recovered.","format":"int64"},"sentdate":{"type":"integer","description":"Date when the transfer has been created/initialized, as unix time, in milliseconds.","format":"int64"},"notify":{"type":"boolean","nullable":true},"status":{"type":"string","description":"Transfer status: STATUS_STARTED, STATUS_COMPLETE, STATUS_CANCELLED, STATUS_DELETED."},"id":{"type":"string","description":"Transfer unique identifier. Use it to fetch transfer details."},"trackid":{"type":"string","nullable":true},"url":{"type":"string","description":"Url to a web page where the transfer can be previewed and where files can be downloaded manually."},"size":{"type":"integer","description":"Transfer size in bytes.","format":"int64","nullable":true},"customlogourl":{"type":"string","nullable":true},"compressedfileurl":{"type":"string","description":"Url that allows to download the entire transfer directly as a ZIP archive."},"compressedfilestatus":{"type":"string"},"compressedfileformat":{"type":"string"},"torrentstatus":{"type":"string"},"torrenturl":{"type":"string"},"days":{"type":"integer","format":"int32"},"isexpired":{"type":"boolean","description":"Indicates whether the transfer is expired. False if expiredate or extendedexpiredate is in the future. True if expiredate is in the past and no extension exists, or if both expiredate and extendedexpiredate are in the past."},"source":{"type":"string","nullable":true},"key":{"type":"string","nullable":true},"fileserver":{"type":"string"},"fileserverurl":{"type":"string"},"fileserverurl_main":{"type":"string"},"footertext":{"type":"string"},"containsmorefiles":{"type":"integer","format":"int32","nullable":true},"customfields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"},"description":"List of transfer custom fields. These fields are only available if the transfer has been recevied by an organization via 'Receive files' page or via 'File request'. Available custom fields are configured by the organization administrator."},"files":{"type":"array","items":{"$ref":"#/components/schemas/FileDto"},"description":"List of files contained in this transfer. Preview URLs provide small thumbnails for identifying files; mediumpreview and largepreview return the same URL as smallpreview. Use each file's downloadurl to retrieve the original file."},"filesdb":{"type":"boolean","description":"Indicates when a transfer uses the FilesDB data model."},"hasfilesonotherfileserver":{"type":"boolean","description":"Indicates that at least one uploaded FilesDB file is stored on a physical fileserver different from the transfer main fileserver."},"fileExplorer":{"$ref":"#/components/schemas/FilesDbExplorerView"},"numberoffiles":{"type":"integer","format":"int32"},"numberofdownloads":{"type":"integer","format":"int32"},"downloads":{"type":"array","items":{"$ref":"#/components/schemas/Download"}},"antivirusscanstatus":{"type":"string"},"passwordprotected":{"type":"boolean"},"iconcolor":{"type":"string"},"iconletter":{"type":"string"},"ftphost":{"type":"string"},"region":{"type":"string","nullable":true},"protocol":{"type":"string","nullable":true},"e2ee":{"type":"boolean","nullable":true},"kind":{"type":"string","nullable":true},"ftpcorppasswordrequired":{"type":"boolean"},"udpthreshold":{"type":"integer","format":"int32"},"permanent":{"type":"boolean"},"maxdays":{"type":"integer","format":"int32"},"allowediting":{"type":"boolean"},"allowforwarding":{"type":"boolean"},"alloweditingexpiredate":{"type":"boolean"},"blockdownloads":{"type":"boolean","nullable":true},"infected":{"type":"boolean"},"infected_deleted":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"TransferRecipient":{"type":"object","properties":{"email":{"type":"string","nullable":true},"downloadlink":{"type":"string","nullable":true},"delivered":{"type":"boolean"},"deliveryerror":{"type":"string","nullable":true}},"additionalProperties":false},"CustomField":{"type":"object","properties":{"customfieldid":{"type":"string"},"defaultvalue":{"type":"string"},"description":{"type":"string"},"label":{"type":"string"},"customLabel":{"type":"string","nullable":true},"listitems":{"type":"string"},"required":{"type":"boolean","nullable":true},"visible":{"type":"boolean","nullable":true},"type":{"type":"string"},"rendertype":{"type":"integer","format":"int32"},"sortorder":{"type":"integer","format":"int32","nullable":true},"length":{"type":"integer","format":"int32","nullable":true},"startValue":{"type":"integer","format":"int64","nullable":true},"placeholder":{"type":"string"},"removable":{"type":"boolean"},"editableType":{"type":"boolean"},"editableRequired":{"type":"boolean"},"value":{"type":"string"},"barcodeimage":{"type":"string"}},"additionalProperties":false},"FileDto":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"filesize":{"type":"integer","format":"int64","nullable":true},"downloadurl":{"type":"string","description":"Url to one of Filemail fileservers - use it to download this individual file directly."},"fileid":{"type":"string","nullable":true},"thumbid":{"type":"string"},"previewurl":{"type":"string","description":"Url to a small thumbnail, or a file icon when a thumbnail is unavailable. Previews are intended for identifying files in a transfer. Use downloadurl to retrieve the original file.","nullable":true},"hascustompreview":{"type":"boolean","nullable":true},"videopreview":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Video"},"nullable":true},"downloads":{"type":"array","items":{"$ref":"#/components/schemas/Download"},"nullable":true},"filetype":{"type":"string","nullable":true},"filetypedescription":{"type":"string","nullable":true},"category":{"type":"string"},"smallpreview":{"type":"string","description":"Url to the same small thumbnail or file icon as previewurl.","nullable":true},"mediumpreview":{"type":"string","description":"Returns the same URL as smallpreview. Retained for compatibility; does not provide a medium-sized image.","nullable":true,"deprecated":true},"largepreview":{"type":"string","description":"Returns the same URL as smallpreview. Retained for compatibility; does not provide a large-sized image.","nullable":true,"deprecated":true},"hascustomthumbnail":{"type":"boolean","nullable":true},"transferid":{"type":"string"},"md5":{"type":"string","nullable":true},"suspecteddamage":{"type":"boolean","nullable":true}},"additionalProperties":false},"Video":{"type":"object","properties":{"size":{"type":"integer","format":"int64"},"resolution":{"type":"integer","format":"int32"},"downloadUrl":{"type":"string","nullable":true}},"additionalProperties":false},"Download":{"type":"object","properties":{"downloaddate":{"type":"integer","format":"int64"},"ip":{"type":"string"},"email":{"type":"string"},"location":{"type":"string"},"locationurl":{"type":"string"},"locationflag":{"type":"string","nullable":true},"kBps":{"type":"integer","format":"int32","nullable":true},"filename":{"type":"string","nullable":true},"filesize":{"type":"integer","format":"int64","nullable":true},"downloadtype":{"$ref":"#/components/schemas/DownloadType"}},"additionalProperties":false},"DownloadType":{"enum":["SingleFile","MultipleFiles","EntireTransfer"],"type":"string"},"FilesDbExplorerView":{"type":"object","properties":{"filesToken":{"type":"string","nullable":true},"parentItemId":{"type":"string","nullable":true},"offset":{"type":"integer","format":"int32"},"limit":{"type":"integer","format":"int32"},"total":{"type":"integer","format":"int32"},"itemsLeft":{"type":"integer","format":"int32"},"hasMore":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/FilesDbExplorerItem"}}},"additionalProperties":false},"FilesDbExplorerItem":{"type":"object","properties":{"uploadItemId":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","nullable":true},"filesize":{"type":"integer","format":"int64","nullable":true},"downloadurl":{"type":"string","nullable":true},"smallpreview":{"type":"string","nullable":true},"md5":{"type":"string","nullable":true}},"additionalProperties":false},"PortalLeftMenuDto":{"type":"object","properties":{"portalId":{"type":"string"},"friendlyName":{"type":"string"},"uploadCount":{"type":"integer","format":"int32","nullable":true},"isDefault":{"type":"boolean"}},"additionalProperties":false},"User":{"type":"object","properties":{"maxdownloads":{"type":"integer","format":"int32"},"maxdays":{"type":"integer","format":"int32"},"maxtransfersize":{"type":"integer","format":"int64"},"membershipname":{"type":"string"},"istrial":{"type":"boolean"},"defaultnotify":{"type":"boolean"},"defaultdays":{"type":"integer","format":"int32"},"defaultconfirmation":{"type":"boolean"},"defaultdownloads":{"type":"integer","format":"int32"},"id":{"type":"string"},"dlc":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"intercomhash":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"mobilephone":{"type":"string","nullable":true},"signature":{"type":"string","nullable":true},"defaultsubject":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"newsletter":{"type":"boolean","nullable":true},"allowCommunicationEmails":{"type":"boolean","nullable":true},"startpage":{"type":"string","nullable":true},"created":{"type":"integer","format":"int64"},"ssoPlatform":{"type":"string","nullable":true},"cansend":{"type":"boolean"},"expired":{"type":"boolean"},"emailverifiedforsending":{"type":"boolean"},"freelimitreached":{"type":"boolean"},"companyname":{"type":"string","nullable":true},"companyid":{"type":"string","nullable":true},"admin":{"type":"boolean","nullable":true},"role":{"type":"integer","format":"int32"},"forcepasswordonincoming":{"type":"boolean","nullable":true},"canreceivefiles":{"type":"boolean","nullable":true},"buttonscolor":{"type":"string","nullable":true},"buttonstextcolor":{"type":"string","nullable":true},"companylogo":{"type":"string","nullable":true},"showallrecipients":{"type":"boolean"},"canstorefilesforever":{"type":"boolean"},"enforcepasswordpolicy":{"type":"boolean"},"udpenabled":{"type":"boolean"},"allowunlimiteddays":{"type":"boolean"},"allow3months":{"type":"boolean"},"canAccessOthersFiles":{"type":"boolean","nullable":true},"subscription":{"$ref":"#/components/schemas/Subscription"},"storageinuse":{"type":"integer","format":"int64","nullable":true},"storagelimit":{"type":"integer","format":"int64","nullable":true},"passwordMinLength":{"type":"integer","format":"int32","nullable":true},"contactgroups":{"type":"array","items":{"$ref":"#/components/schemas/ContactGroup"}},"twoFactorEnabled":{"type":"boolean","nullable":true},"loglevel":{"type":"string","nullable":true},"maxrecipients":{"type":"integer","format":"int32","nullable":true},"maxrecipientsaftertrial":{"type":"integer","format":"int32","nullable":true},"allowautodownloads":{"type":"boolean"},"allowpasswordprotection":{"type":"boolean"},"allowdownloadtracking":{"type":"boolean"},"allowe2ee":{"type":"boolean"},"allowfilesdb":{"type":"boolean","nullable":true},"allowPortals":{"type":"boolean"},"allowMultiplePortals":{"type":"boolean"},"canManageSubscription":{"type":"boolean"},"requireE2EEwhenSending":{"type":"boolean","nullable":true},"requireE2EEwhenReceiving":{"type":"boolean","nullable":true}},"additionalProperties":false},"Subscription":{"type":"object","properties":{"active":{"type":"boolean"},"expireDate":{"type":"integer","format":"int64","nullable":true},"currency":{"type":"string"},"interval":{"type":"string"},"membershipname":{"type":"string"},"showExVatLabelOnPrices":{"type":"boolean"},"allowMultipleUsers":{"type":"boolean"},"licenseCount":{"type":"integer","format":"int32"},"licensePrice":{"type":"number","format":"double"},"pricePerTBPerUser":{"type":"number","format":"double"},"subscriptionPrice_Users":{"type":"number","format":"double"},"subscriptionPrice_Storage":{"type":"number","format":"double"},"subscriptionPrice_Total":{"type":"number","format":"double"},"paymentGateway":{"$ref":"#/components/schemas/PaymentGateways"},"licensesInUse":{"type":"integer","format":"int32"},"canChangePlan":{"$ref":"#/components/schemas/SettingsFeatureDto"},"canUpdatePaymentMethod":{"$ref":"#/components/schemas/SettingsFeatureDto"},"changeSubscriptionMobileAppLink":{"type":"string","nullable":true},"canChangeInterval":{"$ref":"#/components/schemas/SettingsFeatureDto"},"canManageLicenses":{"$ref":"#/components/schemas/SettingsFeatureDto"},"canChangeLicenseCount":{"$ref":"#/components/schemas/SettingsFeatureDto"},"canCancel":{"$ref":"#/components/schemas/SettingsFeatureDto"},"canUpgrade":{"$ref":"#/components/schemas/SettingsFeatureDto"},"isTrial":{"type":"boolean"},"nextPaymentDate":{"type":"integer","format":"int64","nullable":true},"paymentMethod":{"$ref":"#/components/schemas/PaymentMethodDto"},"storageBytesInUse":{"type":"integer","format":"int64"},"storageBytesLimit":{"type":"integer","format":"int64"},"storageBytesIncludedInMembership":{"type":"integer","format":"int64"},"storageBytesAdditional":{"type":"integer","format":"int64"}},"additionalProperties":false},"PaymentGateways":{"enum":["PayPal","PayEx","Chargify","None","PowerOffice","Braintree","AppStore","PlayStore","Stripe"],"type":"string"},"SettingsFeatureDto":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/SettingsFeatureState"},"reason":{"type":"string","nullable":true},"link":{"type":"string","nullable":true}},"additionalProperties":false},"SettingsFeatureState":{"enum":["active","hidden","blocked"],"type":"string"},"PaymentMethodDto":{"type":"object","properties":{"paymentMethod":{"$ref":"#/components/schemas/PaymentMethod"},"creditCardBrand":{"type":"string","nullable":true},"creditCardLast4":{"type":"string","nullable":true},"creditCardName":{"type":"string","nullable":true},"creditCardExpireYear":{"type":"integer","format":"int32","nullable":true},"creditCardExpireMonth":{"type":"integer","format":"int32","nullable":true},"payPalEmail":{"type":"string","nullable":true},"paymentMethodTextInfo":{"type":"string","nullable":true}},"additionalProperties":false},"PaymentMethod":{"enum":["PayPal","CreditCard","Invoice","AppStore","GooglePay","Uknown","Digital"],"type":"string"},"ContactGroup":{"type":"object","properties":{"numberofcontacts":{"type":"integer","format":"int32","nullable":true},"contactgroupid":{"type":"string"},"contactgroupname":{"type":"string"},"corp_shared":{"type":"boolean"},"allow_edit":{"type":"boolean"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/Contact"},"nullable":true}},"additionalProperties":false},"Contact":{"type":"object","properties":{"contactid":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"mobile":{"type":"string"},"corp_shared":{"type":"boolean"},"allow_edit":{"type":"boolean"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/ContactGroup"}}},"additionalProperties":false},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` # Getting sent files Learn about listing all files sent from one or more accounts within an organization using the Filemail API. Use the [Getting sent files](/getting-sent-files#get-transfer-sent) endpoint to list all transfers sent by a user, or sent by all users in an organization (Admin role is required in this case). The response will provide details about each transfer, including transfer IDs needed to fetch the transfer details using [Getting transfer details](/getting-transfer-details). ## GET /transfer/sent > Returns a list of transfers sent by currently authenticated user, or sent by all users in the authenticated user's organization. Optionally allows to include expired transfers. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Transfer"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/transfer/sent":{"get":{"tags":["Transfer"],"description":"Returns a list of transfers sent by currently authenticated user, or sent by all users in the authenticated user's organization. Optionally allows to include expired transfers.","parameters":[{"name":"getexpired","in":"query","description":"When set to true the response will include also expired transfers.","schema":{"type":"boolean"}},{"name":"getforallusers","in":"query","description":"When set to true the response will include also transfers sent by other users in the organization. In case current user is not an organization administrator - this flag will be ignored.","schema":{"type":"boolean"}},{"name":"search","in":"query","description":"Optional search phrase, which will filter transfers by ID, subject, message, sender, recipients and custom fields.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Optional amount of sent items to fetch (paging). Defaults to custom max page size specified for a company account, or system default (1000).","schema":{"type":"integer","format":"int32"}},{"name":"skip","in":"query","description":"Optional amount of sent items to skip (paging). Defaults to 0.","schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/TransferListDtoBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/TransferListDtoBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/TransferListDtoBaseResponse"}}}},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"TransferListDtoBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/TransferListDto"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"TransferListDto":{"type":"object","properties":{"transfers":{"type":"array","items":{"$ref":"#/components/schemas/Transfer"},"description":"The list of transfers that match the request specification."},"portal":{"$ref":"#/components/schemas/PortalLeftMenuDto"},"inboxOwner":{"$ref":"#/components/schemas/User"}},"additionalProperties":false},"Transfer":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string"},"description":"This property is obsolete. Use 'recipients' property instead.","deprecated":true},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/TransferRecipient"},"description":"List of transfer recipients."},"failedRecipients":{"type":"integer","format":"int32"},"from":{"type":"string","description":"The sender's email address.","nullable":true},"subject":{"type":"string"},"message":{"type":"string"},"expiredate":{"type":"integer","description":"Transfer expiration date, as unix time, in milliseconds. To check if a transfer is permanent use the 'permanent' property.","format":"int64"},"extendedexpiredate":{"type":"integer","description":"Extended transfer expiration date, as unix time, in milliseconds. This value is only available if transfer was successfully recovered.","format":"int64"},"sentdate":{"type":"integer","description":"Date when the transfer has been created/initialized, as unix time, in milliseconds.","format":"int64"},"notify":{"type":"boolean","nullable":true},"status":{"type":"string","description":"Transfer status: STATUS_STARTED, STATUS_COMPLETE, STATUS_CANCELLED, STATUS_DELETED."},"id":{"type":"string","description":"Transfer unique identifier. Use it to fetch transfer details."},"trackid":{"type":"string","nullable":true},"url":{"type":"string","description":"Url to a web page where the transfer can be previewed and where files can be downloaded manually."},"size":{"type":"integer","description":"Transfer size in bytes.","format":"int64","nullable":true},"customlogourl":{"type":"string","nullable":true},"compressedfileurl":{"type":"string","description":"Url that allows to download the entire transfer directly as a ZIP archive."},"compressedfilestatus":{"type":"string"},"compressedfileformat":{"type":"string"},"torrentstatus":{"type":"string"},"torrenturl":{"type":"string"},"days":{"type":"integer","format":"int32"},"isexpired":{"type":"boolean","description":"Indicates whether the transfer is expired. False if expiredate or extendedexpiredate is in the future. True if expiredate is in the past and no extension exists, or if both expiredate and extendedexpiredate are in the past."},"source":{"type":"string","nullable":true},"key":{"type":"string","nullable":true},"fileserver":{"type":"string"},"fileserverurl":{"type":"string"},"fileserverurl_main":{"type":"string"},"footertext":{"type":"string"},"containsmorefiles":{"type":"integer","format":"int32","nullable":true},"customfields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"},"description":"List of transfer custom fields. These fields are only available if the transfer has been recevied by an organization via 'Receive files' page or via 'File request'. Available custom fields are configured by the organization administrator."},"files":{"type":"array","items":{"$ref":"#/components/schemas/FileDto"},"description":"List of files contained in this transfer. Preview URLs provide small thumbnails for identifying files; mediumpreview and largepreview return the same URL as smallpreview. Use each file's downloadurl to retrieve the original file."},"filesdb":{"type":"boolean","description":"Indicates when a transfer uses the FilesDB data model."},"hasfilesonotherfileserver":{"type":"boolean","description":"Indicates that at least one uploaded FilesDB file is stored on a physical fileserver different from the transfer main fileserver."},"fileExplorer":{"$ref":"#/components/schemas/FilesDbExplorerView"},"numberoffiles":{"type":"integer","format":"int32"},"numberofdownloads":{"type":"integer","format":"int32"},"downloads":{"type":"array","items":{"$ref":"#/components/schemas/Download"}},"antivirusscanstatus":{"type":"string"},"passwordprotected":{"type":"boolean"},"iconcolor":{"type":"string"},"iconletter":{"type":"string"},"ftphost":{"type":"string"},"region":{"type":"string","nullable":true},"protocol":{"type":"string","nullable":true},"e2ee":{"type":"boolean","nullable":true},"kind":{"type":"string","nullable":true},"ftpcorppasswordrequired":{"type":"boolean"},"udpthreshold":{"type":"integer","format":"int32"},"permanent":{"type":"boolean"},"maxdays":{"type":"integer","format":"int32"},"allowediting":{"type":"boolean"},"allowforwarding":{"type":"boolean"},"alloweditingexpiredate":{"type":"boolean"},"blockdownloads":{"type":"boolean","nullable":true},"infected":{"type":"boolean"},"infected_deleted":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"TransferRecipient":{"type":"object","properties":{"email":{"type":"string","nullable":true},"downloadlink":{"type":"string","nullable":true},"delivered":{"type":"boolean"},"deliveryerror":{"type":"string","nullable":true}},"additionalProperties":false},"CustomField":{"type":"object","properties":{"customfieldid":{"type":"string"},"defaultvalue":{"type":"string"},"description":{"type":"string"},"label":{"type":"string"},"customLabel":{"type":"string","nullable":true},"listitems":{"type":"string"},"required":{"type":"boolean","nullable":true},"visible":{"type":"boolean","nullable":true},"type":{"type":"string"},"rendertype":{"type":"integer","format":"int32"},"sortorder":{"type":"integer","format":"int32","nullable":true},"length":{"type":"integer","format":"int32","nullable":true},"startValue":{"type":"integer","format":"int64","nullable":true},"placeholder":{"type":"string"},"removable":{"type":"boolean"},"editableType":{"type":"boolean"},"editableRequired":{"type":"boolean"},"value":{"type":"string"},"barcodeimage":{"type":"string"}},"additionalProperties":false},"FileDto":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"filesize":{"type":"integer","format":"int64","nullable":true},"downloadurl":{"type":"string","description":"Url to one of Filemail fileservers - use it to download this individual file directly."},"fileid":{"type":"string","nullable":true},"thumbid":{"type":"string"},"previewurl":{"type":"string","description":"Url to a small thumbnail, or a file icon when a thumbnail is unavailable. Previews are intended for identifying files in a transfer. Use downloadurl to retrieve the original file.","nullable":true},"hascustompreview":{"type":"boolean","nullable":true},"videopreview":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Video"},"nullable":true},"downloads":{"type":"array","items":{"$ref":"#/components/schemas/Download"},"nullable":true},"filetype":{"type":"string","nullable":true},"filetypedescription":{"type":"string","nullable":true},"category":{"type":"string"},"smallpreview":{"type":"string","description":"Url to the same small thumbnail or file icon as previewurl.","nullable":true},"mediumpreview":{"type":"string","description":"Returns the same URL as smallpreview. Retained for compatibility; does not provide a medium-sized image.","nullable":true,"deprecated":true},"largepreview":{"type":"string","description":"Returns the same URL as smallpreview. Retained for compatibility; does not provide a large-sized image.","nullable":true,"deprecated":true},"hascustomthumbnail":{"type":"boolean","nullable":true},"transferid":{"type":"string"},"md5":{"type":"string","nullable":true},"suspecteddamage":{"type":"boolean","nullable":true}},"additionalProperties":false},"Video":{"type":"object","properties":{"size":{"type":"integer","format":"int64"},"resolution":{"type":"integer","format":"int32"},"downloadUrl":{"type":"string","nullable":true}},"additionalProperties":false},"Download":{"type":"object","properties":{"downloaddate":{"type":"integer","format":"int64"},"ip":{"type":"string"},"email":{"type":"string"},"location":{"type":"string"},"locationurl":{"type":"string"},"locationflag":{"type":"string","nullable":true},"kBps":{"type":"integer","format":"int32","nullable":true},"filename":{"type":"string","nullable":true},"filesize":{"type":"integer","format":"int64","nullable":true},"downloadtype":{"$ref":"#/components/schemas/DownloadType"}},"additionalProperties":false},"DownloadType":{"enum":["SingleFile","MultipleFiles","EntireTransfer"],"type":"string"},"FilesDbExplorerView":{"type":"object","properties":{"filesToken":{"type":"string","nullable":true},"parentItemId":{"type":"string","nullable":true},"offset":{"type":"integer","format":"int32"},"limit":{"type":"integer","format":"int32"},"total":{"type":"integer","format":"int32"},"itemsLeft":{"type":"integer","format":"int32"},"hasMore":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/FilesDbExplorerItem"}}},"additionalProperties":false},"FilesDbExplorerItem":{"type":"object","properties":{"uploadItemId":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","nullable":true},"filesize":{"type":"integer","format":"int64","nullable":true},"downloadurl":{"type":"string","nullable":true},"smallpreview":{"type":"string","nullable":true},"md5":{"type":"string","nullable":true}},"additionalProperties":false},"PortalLeftMenuDto":{"type":"object","properties":{"portalId":{"type":"string"},"friendlyName":{"type":"string"},"uploadCount":{"type":"integer","format":"int32","nullable":true},"isDefault":{"type":"boolean"}},"additionalProperties":false},"User":{"type":"object","properties":{"maxdownloads":{"type":"integer","format":"int32"},"maxdays":{"type":"integer","format":"int32"},"maxtransfersize":{"type":"integer","format":"int64"},"membershipname":{"type":"string"},"istrial":{"type":"boolean"},"defaultnotify":{"type":"boolean"},"defaultdays":{"type":"integer","format":"int32"},"defaultconfirmation":{"type":"boolean"},"defaultdownloads":{"type":"integer","format":"int32"},"id":{"type":"string"},"dlc":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"intercomhash":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"mobilephone":{"type":"string","nullable":true},"signature":{"type":"string","nullable":true},"defaultsubject":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"newsletter":{"type":"boolean","nullable":true},"allowCommunicationEmails":{"type":"boolean","nullable":true},"startpage":{"type":"string","nullable":true},"created":{"type":"integer","format":"int64"},"ssoPlatform":{"type":"string","nullable":true},"cansend":{"type":"boolean"},"expired":{"type":"boolean"},"emailverifiedforsending":{"type":"boolean"},"freelimitreached":{"type":"boolean"},"companyname":{"type":"string","nullable":true},"companyid":{"type":"string","nullable":true},"admin":{"type":"boolean","nullable":true},"role":{"type":"integer","format":"int32"},"forcepasswordonincoming":{"type":"boolean","nullable":true},"canreceivefiles":{"type":"boolean","nullable":true},"buttonscolor":{"type":"string","nullable":true},"buttonstextcolor":{"type":"string","nullable":true},"companylogo":{"type":"string","nullable":true},"showallrecipients":{"type":"boolean"},"canstorefilesforever":{"type":"boolean"},"enforcepasswordpolicy":{"type":"boolean"},"udpenabled":{"type":"boolean"},"allowunlimiteddays":{"type":"boolean"},"allow3months":{"type":"boolean"},"canAccessOthersFiles":{"type":"boolean","nullable":true},"subscription":{"$ref":"#/components/schemas/Subscription"},"storageinuse":{"type":"integer","format":"int64","nullable":true},"storagelimit":{"type":"integer","format":"int64","nullable":true},"passwordMinLength":{"type":"integer","format":"int32","nullable":true},"contactgroups":{"type":"array","items":{"$ref":"#/components/schemas/ContactGroup"}},"twoFactorEnabled":{"type":"boolean","nullable":true},"loglevel":{"type":"string","nullable":true},"maxrecipients":{"type":"integer","format":"int32","nullable":true},"maxrecipientsaftertrial":{"type":"integer","format":"int32","nullable":true},"allowautodownloads":{"type":"boolean"},"allowpasswordprotection":{"type":"boolean"},"allowdownloadtracking":{"type":"boolean"},"allowe2ee":{"type":"boolean"},"allowfilesdb":{"type":"boolean","nullable":true},"allowPortals":{"type":"boolean"},"allowMultiplePortals":{"type":"boolean"},"canManageSubscription":{"type":"boolean"},"requireE2EEwhenSending":{"type":"boolean","nullable":true},"requireE2EEwhenReceiving":{"type":"boolean","nullable":true}},"additionalProperties":false},"Subscription":{"type":"object","properties":{"active":{"type":"boolean"},"expireDate":{"type":"integer","format":"int64","nullable":true},"currency":{"type":"string"},"interval":{"type":"string"},"membershipname":{"type":"string"},"showExVatLabelOnPrices":{"type":"boolean"},"allowMultipleUsers":{"type":"boolean"},"licenseCount":{"type":"integer","format":"int32"},"licensePrice":{"type":"number","format":"double"},"pricePerTBPerUser":{"type":"number","format":"double"},"subscriptionPrice_Users":{"type":"number","format":"double"},"subscriptionPrice_Storage":{"type":"number","format":"double"},"subscriptionPrice_Total":{"type":"number","format":"double"},"paymentGateway":{"$ref":"#/components/schemas/PaymentGateways"},"licensesInUse":{"type":"integer","format":"int32"},"canChangePlan":{"$ref":"#/components/schemas/SettingsFeatureDto"},"canUpdatePaymentMethod":{"$ref":"#/components/schemas/SettingsFeatureDto"},"changeSubscriptionMobileAppLink":{"type":"string","nullable":true},"canChangeInterval":{"$ref":"#/components/schemas/SettingsFeatureDto"},"canManageLicenses":{"$ref":"#/components/schemas/SettingsFeatureDto"},"canChangeLicenseCount":{"$ref":"#/components/schemas/SettingsFeatureDto"},"canCancel":{"$ref":"#/components/schemas/SettingsFeatureDto"},"canUpgrade":{"$ref":"#/components/schemas/SettingsFeatureDto"},"isTrial":{"type":"boolean"},"nextPaymentDate":{"type":"integer","format":"int64","nullable":true},"paymentMethod":{"$ref":"#/components/schemas/PaymentMethodDto"},"storageBytesInUse":{"type":"integer","format":"int64"},"storageBytesLimit":{"type":"integer","format":"int64"},"storageBytesIncludedInMembership":{"type":"integer","format":"int64"},"storageBytesAdditional":{"type":"integer","format":"int64"}},"additionalProperties":false},"PaymentGateways":{"enum":["PayPal","PayEx","Chargify","None","PowerOffice","Braintree","AppStore","PlayStore","Stripe"],"type":"string"},"SettingsFeatureDto":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/SettingsFeatureState"},"reason":{"type":"string","nullable":true},"link":{"type":"string","nullable":true}},"additionalProperties":false},"SettingsFeatureState":{"enum":["active","hidden","blocked"],"type":"string"},"PaymentMethodDto":{"type":"object","properties":{"paymentMethod":{"$ref":"#/components/schemas/PaymentMethod"},"creditCardBrand":{"type":"string","nullable":true},"creditCardLast4":{"type":"string","nullable":true},"creditCardName":{"type":"string","nullable":true},"creditCardExpireYear":{"type":"integer","format":"int32","nullable":true},"creditCardExpireMonth":{"type":"integer","format":"int32","nullable":true},"payPalEmail":{"type":"string","nullable":true},"paymentMethodTextInfo":{"type":"string","nullable":true}},"additionalProperties":false},"PaymentMethod":{"enum":["PayPal","CreditCard","Invoice","AppStore","GooglePay","Uknown","Digital"],"type":"string"},"ContactGroup":{"type":"object","properties":{"numberofcontacts":{"type":"integer","format":"int32","nullable":true},"contactgroupid":{"type":"string"},"contactgroupname":{"type":"string"},"corp_shared":{"type":"boolean"},"allow_edit":{"type":"boolean"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/Contact"},"nullable":true}},"additionalProperties":false},"Contact":{"type":"object","properties":{"contactid":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"mobile":{"type":"string"},"corp_shared":{"type":"boolean"},"allow_edit":{"type":"boolean"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/ContactGroup"}}},"additionalProperties":false},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` # Getting transfer details This article explains how to get transfer details, including all files in a transfer through the Filemail API. When you know the ID of a transfer, you can get all details about this transfer as well as recipients and files belonging to it. Please note that the amount of received data will depend on the authenticated user's relation to the transfer. {% hint style="warning" %} For **non-administrator** users of the Filemail account:\ If the transfer was sent by a different user than yourself, you will not have access to transfer key, recipients and download tracking. {% endhint %} {% hint style="warning" %} For **administrator** users of the Filemail account:\ If the transfer was not sent or received by a user in your organization, you will not have access to transfer key, recipients and download tracking. {% endhint %} ### Recipients The Recipients object will return a list of recipients of the transfer. For each recipient, you can see their e-mail address, the unique trackable download link, if e-mail delivery was successful and any error that might have been returned from mail server in case e-mail delivery failed. ### Custom fields Depending on how your inboxes have been set up, you might have received transfers with some custom data attached to them. The list of all configured custom fields are available in the transfer details and you will be able to get their values along many other properties. ### Files The list of files contained in the transfer is attached. Every file includes `downloadurl` that can be used to download that specific file. The is also other metadata available for each file. ### Downloads Each file will have a list of downloads attached to it. This is information about who downloaded the files together with other useful information about the download. ## Retrieve an existing transfer by ID. > This endpoint retrieves transfer details, file list, recipients, download tracking information and other transfer meta data. Image previews are small thumbnails intended for identifying files in a transfer. The mediumpreview and largepreview fields return the same URL as smallpreview. Use each file's downloadurl to retrieve the original file. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Transfer"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/transfer/{transferid}":{"get":{"tags":["Transfer"],"summary":"Retrieve an existing transfer by ID.","description":"This endpoint retrieves transfer details, file list, recipients, download tracking information and other transfer meta data. Image previews are small thumbnails intended for identifying files in a transfer. The mediumpreview and largepreview fields return the same URL as smallpreview. Use each file's downloadurl to retrieve the original file.","parameters":[{"name":"transferid","in":"path","description":"The transfer ID - unique transfer identifier. It is returned after initializing a transfer, also it is available in transfer list responses (sent and received). This parameter is optional, since transfers can also be fetched by providing `trackid`. When `transferid` is not used, then `trackid` must be specified.","required":true,"schema":{"type":"string"}},{"name":"trackid","in":"query","description":"The unique tracking identifier of a transfer. Use this parameter as an alternative to transfer ID. Tracking identifiers are included in emails sent out to transfer recipients, and they are unique for each recipient.","schema":{"type":"string","description":"The unique tracking identifier of a transfer. Use this parameter as an alternative to transfer ID. Tracking identifiers are included in emails sent out to transfer recipients, and they are unique for each recipient."}},{"name":"filesLimit","in":"query","description":"Limit the number of files included in the response. Specify -1 to get all files.","schema":{"type":"integer","description":"Limit the number of files included in the response. Specify -1 to get all files.","format":"int32"}},{"name":"withDetails","in":"query","description":"Controls whether all transfer details should be returned. When set to `false` the response will not include files, download tracking and other more advanced details. When not specified - it defaults to `true`.","schema":{"type":"boolean","description":"Controls whether all transfer details should be returned. When set to `false` the response will not include files, download tracking and other more advanced details. When not specified - it defaults to `true`."}},{"name":"excludeFiles","in":"query","description":"When set to true the response will not include transfer files. Defaults to `false`. Note: this flag is effective only when `withDetails` is true.","schema":{"type":"boolean","description":"When set to true the response will not include transfer files. Defaults to `false`. Note: this flag is effective only when `withDetails` is true."}},{"name":"excludeDownloads","in":"query","description":"When set to true the response will not include download tracking information. Defaults to `false`. Note: this flag is effective only when `withDetails` is true.","schema":{"type":"boolean","description":"When set to true the response will not include download tracking information. Defaults to `false`. Note: this flag is effective only when `withDetails` is true."}},{"name":"password","in":"query","description":"Password is required when a transfer has been password-proteced by the sender.","schema":{"type":"string","description":"Password is required when a transfer has been password-proteced by the sender."}},{"name":"captcha","in":"query","description":"Required in case wrong transfer password has been specified too many times.","schema":{"type":"string","description":"Required in case wrong transfer password has been specified too many times."}},{"name":"fprops","in":"query","description":"A comma-separated list of property names to include in every file on the file list. This can help reduce the total response size when fetching transfers with a large number of files. E.g. 'filename,downloadurl'","schema":{"type":"string","description":"A comma-separated list of property names to include in every file on the file list. This can help reduce the total response size when fetching transfers with a large number of files. E.g. 'filename,downloadurl'"}}],"responses":{"200":{"description":"OK - Returned when transfer is found and successfully retrieved.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/TransferBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/TransferBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/TransferBaseResponse"}}}},"401":{"description":"Unauthorized - for password protected transfers - returned when wrong password or no password has been provided.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"404":{"description":"Not found - returned in case of an invalid transfer ID.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"409":{"description":"Conflict","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"TransferBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/Transfer"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"Transfer":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string"},"description":"This property is obsolete. Use 'recipients' property instead.","deprecated":true},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/TransferRecipient"},"description":"List of transfer recipients."},"failedRecipients":{"type":"integer","format":"int32"},"from":{"type":"string","description":"The sender's email address.","nullable":true},"subject":{"type":"string"},"message":{"type":"string"},"expiredate":{"type":"integer","description":"Transfer expiration date, as unix time, in milliseconds. To check if a transfer is permanent use the 'permanent' property.","format":"int64"},"extendedexpiredate":{"type":"integer","description":"Extended transfer expiration date, as unix time, in milliseconds. This value is only available if transfer was successfully recovered.","format":"int64"},"sentdate":{"type":"integer","description":"Date when the transfer has been created/initialized, as unix time, in milliseconds.","format":"int64"},"notify":{"type":"boolean","nullable":true},"status":{"type":"string","description":"Transfer status: STATUS_STARTED, STATUS_COMPLETE, STATUS_CANCELLED, STATUS_DELETED."},"id":{"type":"string","description":"Transfer unique identifier. Use it to fetch transfer details."},"trackid":{"type":"string","nullable":true},"url":{"type":"string","description":"Url to a web page where the transfer can be previewed and where files can be downloaded manually."},"size":{"type":"integer","description":"Transfer size in bytes.","format":"int64","nullable":true},"customlogourl":{"type":"string","nullable":true},"compressedfileurl":{"type":"string","description":"Url that allows to download the entire transfer directly as a ZIP archive."},"compressedfilestatus":{"type":"string"},"compressedfileformat":{"type":"string"},"torrentstatus":{"type":"string"},"torrenturl":{"type":"string"},"days":{"type":"integer","format":"int32"},"isexpired":{"type":"boolean","description":"Indicates whether the transfer is expired. False if expiredate or extendedexpiredate is in the future. True if expiredate is in the past and no extension exists, or if both expiredate and extendedexpiredate are in the past."},"source":{"type":"string","nullable":true},"key":{"type":"string","nullable":true},"fileserver":{"type":"string"},"fileserverurl":{"type":"string"},"fileserverurl_main":{"type":"string"},"footertext":{"type":"string"},"containsmorefiles":{"type":"integer","format":"int32","nullable":true},"customfields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"},"description":"List of transfer custom fields. These fields are only available if the transfer has been recevied by an organization via 'Receive files' page or via 'File request'. Available custom fields are configured by the organization administrator."},"files":{"type":"array","items":{"$ref":"#/components/schemas/FileDto"},"description":"List of files contained in this transfer. Preview URLs provide small thumbnails for identifying files; mediumpreview and largepreview return the same URL as smallpreview. Use each file's downloadurl to retrieve the original file."},"filesdb":{"type":"boolean","description":"Indicates when a transfer uses the FilesDB data model."},"hasfilesonotherfileserver":{"type":"boolean","description":"Indicates that at least one uploaded FilesDB file is stored on a physical fileserver different from the transfer main fileserver."},"fileExplorer":{"$ref":"#/components/schemas/FilesDbExplorerView"},"numberoffiles":{"type":"integer","format":"int32"},"numberofdownloads":{"type":"integer","format":"int32"},"downloads":{"type":"array","items":{"$ref":"#/components/schemas/Download"}},"antivirusscanstatus":{"type":"string"},"passwordprotected":{"type":"boolean"},"iconcolor":{"type":"string"},"iconletter":{"type":"string"},"ftphost":{"type":"string"},"region":{"type":"string","nullable":true},"protocol":{"type":"string","nullable":true},"e2ee":{"type":"boolean","nullable":true},"kind":{"type":"string","nullable":true},"ftpcorppasswordrequired":{"type":"boolean"},"udpthreshold":{"type":"integer","format":"int32"},"permanent":{"type":"boolean"},"maxdays":{"type":"integer","format":"int32"},"allowediting":{"type":"boolean"},"allowforwarding":{"type":"boolean"},"alloweditingexpiredate":{"type":"boolean"},"blockdownloads":{"type":"boolean","nullable":true},"infected":{"type":"boolean"},"infected_deleted":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"TransferRecipient":{"type":"object","properties":{"email":{"type":"string","nullable":true},"downloadlink":{"type":"string","nullable":true},"delivered":{"type":"boolean"},"deliveryerror":{"type":"string","nullable":true}},"additionalProperties":false},"CustomField":{"type":"object","properties":{"customfieldid":{"type":"string"},"defaultvalue":{"type":"string"},"description":{"type":"string"},"label":{"type":"string"},"customLabel":{"type":"string","nullable":true},"listitems":{"type":"string"},"required":{"type":"boolean","nullable":true},"visible":{"type":"boolean","nullable":true},"type":{"type":"string"},"rendertype":{"type":"integer","format":"int32"},"sortorder":{"type":"integer","format":"int32","nullable":true},"length":{"type":"integer","format":"int32","nullable":true},"startValue":{"type":"integer","format":"int64","nullable":true},"placeholder":{"type":"string"},"removable":{"type":"boolean"},"editableType":{"type":"boolean"},"editableRequired":{"type":"boolean"},"value":{"type":"string"},"barcodeimage":{"type":"string"}},"additionalProperties":false},"FileDto":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"filesize":{"type":"integer","format":"int64","nullable":true},"downloadurl":{"type":"string","description":"Url to one of Filemail fileservers - use it to download this individual file directly."},"fileid":{"type":"string","nullable":true},"thumbid":{"type":"string"},"previewurl":{"type":"string","description":"Url to a small thumbnail, or a file icon when a thumbnail is unavailable. Previews are intended for identifying files in a transfer. Use downloadurl to retrieve the original file.","nullable":true},"hascustompreview":{"type":"boolean","nullable":true},"videopreview":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Video"},"nullable":true},"downloads":{"type":"array","items":{"$ref":"#/components/schemas/Download"},"nullable":true},"filetype":{"type":"string","nullable":true},"filetypedescription":{"type":"string","nullable":true},"category":{"type":"string"},"smallpreview":{"type":"string","description":"Url to the same small thumbnail or file icon as previewurl.","nullable":true},"mediumpreview":{"type":"string","description":"Returns the same URL as smallpreview. Retained for compatibility; does not provide a medium-sized image.","nullable":true,"deprecated":true},"largepreview":{"type":"string","description":"Returns the same URL as smallpreview. Retained for compatibility; does not provide a large-sized image.","nullable":true,"deprecated":true},"hascustomthumbnail":{"type":"boolean","nullable":true},"transferid":{"type":"string"},"md5":{"type":"string","nullable":true},"suspecteddamage":{"type":"boolean","nullable":true}},"additionalProperties":false},"Video":{"type":"object","properties":{"size":{"type":"integer","format":"int64"},"resolution":{"type":"integer","format":"int32"},"downloadUrl":{"type":"string","nullable":true}},"additionalProperties":false},"Download":{"type":"object","properties":{"downloaddate":{"type":"integer","format":"int64"},"ip":{"type":"string"},"email":{"type":"string"},"location":{"type":"string"},"locationurl":{"type":"string"},"locationflag":{"type":"string","nullable":true},"kBps":{"type":"integer","format":"int32","nullable":true},"filename":{"type":"string","nullable":true},"filesize":{"type":"integer","format":"int64","nullable":true},"downloadtype":{"$ref":"#/components/schemas/DownloadType"}},"additionalProperties":false},"DownloadType":{"enum":["SingleFile","MultipleFiles","EntireTransfer"],"type":"string"},"FilesDbExplorerView":{"type":"object","properties":{"filesToken":{"type":"string","nullable":true},"parentItemId":{"type":"string","nullable":true},"offset":{"type":"integer","format":"int32"},"limit":{"type":"integer","format":"int32"},"total":{"type":"integer","format":"int32"},"itemsLeft":{"type":"integer","format":"int32"},"hasMore":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/FilesDbExplorerItem"}}},"additionalProperties":false},"FilesDbExplorerItem":{"type":"object","properties":{"uploadItemId":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","nullable":true},"filesize":{"type":"integer","format":"int64","nullable":true},"downloadurl":{"type":"string","nullable":true},"smallpreview":{"type":"string","nullable":true},"md5":{"type":"string","nullable":true}},"additionalProperties":false},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` # Managing transfers In this section you can learn how to manage existing transfer through the Filemail API There is a set of operations you can do on an existing transfer: {% stepper %} {% step %} ### [Editing a transfer](/managing-transfers/editing-a-transfer) You can edit any meta data on a transfer {% endstep %} {% step %} ### [Deleting a transfer](/managing-transfers/deleting-a-transfer) You can delete a transfer {% endstep %} {% step %} ### [Forwarding a transfer](/managing-transfers/forwarding-a-transfer) You can forward a transfer, meaning that you add a new recipient to your transfer.. Read more about [#the-difference-between-forwarding-and-sharing-a-transfer](#the-difference-between-forwarding-and-sharing-a-transfer "mention") {% endstep %} {% step %} ### [Sharing a transfer](/managing-transfers/sharing-a-transfer) You can share a transfer, meaning that you share your received link with someone else. Read more about [#the-difference-between-forwarding-and-sharing-a-transfer](#the-difference-between-forwarding-and-sharing-a-transfer "mention") {% endstep %} {% step %} ### [Renaming a file in a transfer](/managing-transfers/renaming-a-file-in-a-transfer) Change the name of any file in your transfer {% endstep %} {% step %} ### [Deleting a file in a transfer](/managing-transfers/deleting-a-file-in-a-transfer) You can delete any file from a transfer {% endstep %} {% endstepper %} ### The difference between Forwarding and Sharing a transfer We use two different concepts when it comes to giving a transfer to someone else. > **Forwarding** > > Forwarding is possible on any transfer that you have sent or that you have received through any inbox in your organization. Forwarding meaning that you add new recipient to a transfer, generating a new trackable link which is sent to this new recipients e-mail address. > > #### Sharing > > Sharing is possible on any transfer and does not create a new recipient on the transfer. If you are the receiver of this transfer, you will simply share your trackable link, meaning if the person you share with download any files from it, you will be tracked as the downloader. If you share a transfer that you sent, you will simply share an untrackable link to the download page and it gets sent to their e-mail address. # Editing a transfer ## PUT /transfer/{transferid} > Updates basic properties of a transfer. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Transfer"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/transfer/{transferid}":{"put":{"tags":["Transfer"],"description":"Updates basic properties of a transfer.","parameters":[{"name":"transferid","in":"path","description":"The transfer ID - unique transfer identifier. It is returned after initializing a transfer, also it is available in transfer list responses (sent and received).","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/UpdateTransferRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTransferRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/UpdateTransferRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/UpdateTransferRequest"}}}},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/TransferBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/TransferBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/TransferBaseResponse"}}}},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"UpdateTransferRequest":{"type":"object","properties":{"days":{"type":"integer","description":"The number of days until the transfer expires. Expiration is counted since the date of transfer creation. Use `-1` to change make this transfer permanent (one that never expires).","format":"int32","nullable":true},"notify":{"type":"boolean","description":"Decides whether transfer sender receives email notifications when the transfer is downloaded.","nullable":true},"subject":{"maxLength":200,"type":"string","description":"Updates the transfer subject.","nullable":true},"message":{"maxLength":5000,"type":"string","description":"Updates the transfer message / description.","nullable":true},"password":{"maxLength":100,"type":"string","description":"Sets transfer password. Specify empty string in this field to remove existing password.","nullable":true}},"additionalProperties":false},"TransferBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/Transfer"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"Transfer":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string"},"description":"This property is obsolete. Use 'recipients' property instead.","deprecated":true},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/TransferRecipient"},"description":"List of transfer recipients."},"failedRecipients":{"type":"integer","format":"int32"},"from":{"type":"string","description":"The sender's email address.","nullable":true},"subject":{"type":"string"},"message":{"type":"string"},"expiredate":{"type":"integer","description":"Transfer expiration date, as unix time, in milliseconds. To check if a transfer is permanent use the 'permanent' property.","format":"int64"},"extendedexpiredate":{"type":"integer","description":"Extended transfer expiration date, as unix time, in milliseconds. This value is only available if transfer was successfully recovered.","format":"int64"},"sentdate":{"type":"integer","description":"Date when the transfer has been created/initialized, as unix time, in milliseconds.","format":"int64"},"notify":{"type":"boolean","nullable":true},"status":{"type":"string","description":"Transfer status: STATUS_STARTED, STATUS_COMPLETE, STATUS_CANCELLED, STATUS_DELETED."},"id":{"type":"string","description":"Transfer unique identifier. Use it to fetch transfer details."},"trackid":{"type":"string","nullable":true},"url":{"type":"string","description":"Url to a web page where the transfer can be previewed and where files can be downloaded manually."},"size":{"type":"integer","description":"Transfer size in bytes.","format":"int64","nullable":true},"customlogourl":{"type":"string","nullable":true},"compressedfileurl":{"type":"string","description":"Url that allows to download the entire transfer directly as a ZIP archive."},"compressedfilestatus":{"type":"string"},"compressedfileformat":{"type":"string"},"torrentstatus":{"type":"string"},"torrenturl":{"type":"string"},"days":{"type":"integer","format":"int32"},"isexpired":{"type":"boolean","description":"Indicates whether the transfer is expired. False if expiredate or extendedexpiredate is in the future. True if expiredate is in the past and no extension exists, or if both expiredate and extendedexpiredate are in the past."},"source":{"type":"string","nullable":true},"key":{"type":"string","nullable":true},"fileserver":{"type":"string"},"fileserverurl":{"type":"string"},"fileserverurl_main":{"type":"string"},"footertext":{"type":"string"},"containsmorefiles":{"type":"integer","format":"int32","nullable":true},"customfields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"},"description":"List of transfer custom fields. These fields are only available if the transfer has been recevied by an organization via 'Receive files' page or via 'File request'. Available custom fields are configured by the organization administrator."},"files":{"type":"array","items":{"$ref":"#/components/schemas/FileDto"},"description":"List of files contained in this transfer. Preview URLs provide small thumbnails for identifying files; mediumpreview and largepreview return the same URL as smallpreview. Use each file's downloadurl to retrieve the original file."},"filesdb":{"type":"boolean","description":"Indicates when a transfer uses the FilesDB data model."},"hasfilesonotherfileserver":{"type":"boolean","description":"Indicates that at least one uploaded FilesDB file is stored on a physical fileserver different from the transfer main fileserver."},"fileExplorer":{"$ref":"#/components/schemas/FilesDbExplorerView"},"numberoffiles":{"type":"integer","format":"int32"},"numberofdownloads":{"type":"integer","format":"int32"},"downloads":{"type":"array","items":{"$ref":"#/components/schemas/Download"}},"antivirusscanstatus":{"type":"string"},"passwordprotected":{"type":"boolean"},"iconcolor":{"type":"string"},"iconletter":{"type":"string"},"ftphost":{"type":"string"},"region":{"type":"string","nullable":true},"protocol":{"type":"string","nullable":true},"e2ee":{"type":"boolean","nullable":true},"kind":{"type":"string","nullable":true},"ftpcorppasswordrequired":{"type":"boolean"},"udpthreshold":{"type":"integer","format":"int32"},"permanent":{"type":"boolean"},"maxdays":{"type":"integer","format":"int32"},"allowediting":{"type":"boolean"},"allowforwarding":{"type":"boolean"},"alloweditingexpiredate":{"type":"boolean"},"blockdownloads":{"type":"boolean","nullable":true},"infected":{"type":"boolean"},"infected_deleted":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"TransferRecipient":{"type":"object","properties":{"email":{"type":"string","nullable":true},"downloadlink":{"type":"string","nullable":true},"delivered":{"type":"boolean"},"deliveryerror":{"type":"string","nullable":true}},"additionalProperties":false},"CustomField":{"type":"object","properties":{"customfieldid":{"type":"string"},"defaultvalue":{"type":"string"},"description":{"type":"string"},"label":{"type":"string"},"customLabel":{"type":"string","nullable":true},"listitems":{"type":"string"},"required":{"type":"boolean","nullable":true},"visible":{"type":"boolean","nullable":true},"type":{"type":"string"},"rendertype":{"type":"integer","format":"int32"},"sortorder":{"type":"integer","format":"int32","nullable":true},"length":{"type":"integer","format":"int32","nullable":true},"startValue":{"type":"integer","format":"int64","nullable":true},"placeholder":{"type":"string"},"removable":{"type":"boolean"},"editableType":{"type":"boolean"},"editableRequired":{"type":"boolean"},"value":{"type":"string"},"barcodeimage":{"type":"string"}},"additionalProperties":false},"FileDto":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"filesize":{"type":"integer","format":"int64","nullable":true},"downloadurl":{"type":"string","description":"Url to one of Filemail fileservers - use it to download this individual file directly."},"fileid":{"type":"string","nullable":true},"thumbid":{"type":"string"},"previewurl":{"type":"string","description":"Url to a small thumbnail, or a file icon when a thumbnail is unavailable. Previews are intended for identifying files in a transfer. Use downloadurl to retrieve the original file.","nullable":true},"hascustompreview":{"type":"boolean","nullable":true},"videopreview":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Video"},"nullable":true},"downloads":{"type":"array","items":{"$ref":"#/components/schemas/Download"},"nullable":true},"filetype":{"type":"string","nullable":true},"filetypedescription":{"type":"string","nullable":true},"category":{"type":"string"},"smallpreview":{"type":"string","description":"Url to the same small thumbnail or file icon as previewurl.","nullable":true},"mediumpreview":{"type":"string","description":"Returns the same URL as smallpreview. Retained for compatibility; does not provide a medium-sized image.","nullable":true,"deprecated":true},"largepreview":{"type":"string","description":"Returns the same URL as smallpreview. Retained for compatibility; does not provide a large-sized image.","nullable":true,"deprecated":true},"hascustomthumbnail":{"type":"boolean","nullable":true},"transferid":{"type":"string"},"md5":{"type":"string","nullable":true},"suspecteddamage":{"type":"boolean","nullable":true}},"additionalProperties":false},"Video":{"type":"object","properties":{"size":{"type":"integer","format":"int64"},"resolution":{"type":"integer","format":"int32"},"downloadUrl":{"type":"string","nullable":true}},"additionalProperties":false},"Download":{"type":"object","properties":{"downloaddate":{"type":"integer","format":"int64"},"ip":{"type":"string"},"email":{"type":"string"},"location":{"type":"string"},"locationurl":{"type":"string"},"locationflag":{"type":"string","nullable":true},"kBps":{"type":"integer","format":"int32","nullable":true},"filename":{"type":"string","nullable":true},"filesize":{"type":"integer","format":"int64","nullable":true},"downloadtype":{"$ref":"#/components/schemas/DownloadType"}},"additionalProperties":false},"DownloadType":{"enum":["SingleFile","MultipleFiles","EntireTransfer"],"type":"string"},"FilesDbExplorerView":{"type":"object","properties":{"filesToken":{"type":"string","nullable":true},"parentItemId":{"type":"string","nullable":true},"offset":{"type":"integer","format":"int32"},"limit":{"type":"integer","format":"int32"},"total":{"type":"integer","format":"int32"},"itemsLeft":{"type":"integer","format":"int32"},"hasMore":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/FilesDbExplorerItem"}}},"additionalProperties":false},"FilesDbExplorerItem":{"type":"object","properties":{"uploadItemId":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","nullable":true},"filesize":{"type":"integer","format":"int64","nullable":true},"downloadurl":{"type":"string","nullable":true},"smallpreview":{"type":"string","nullable":true},"md5":{"type":"string","nullable":true}},"additionalProperties":false},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` # Deleting a transfer ## DELETE /transfer/{transferid} > Removes a transfer, deactivates its download page and frees up storage space used by this transfer (for all users who had this transfer in their sent folder or inbox). Information about new occupied storage space for current user is contained in the response. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Transfer"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/transfer/{transferid}":{"delete":{"tags":["Transfer"],"description":"Removes a transfer, deactivates its download page and frees up storage space used by this transfer (for all users who had this transfer in their sent folder or inbox). Information about new occupied storage space for current user is contained in the response.","parameters":[{"name":"transferid","in":"path","description":"The transfer ID - unique transfer identifier. It is returned after initializing a transfer, also it is available in transfer list responses (sent and received).","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/TransferDeleteResultBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/TransferDeleteResultBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/TransferDeleteResultBaseResponse"}}}},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"TransferDeleteResultBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/TransferDeleteResult"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"TransferDeleteResult":{"type":"object","properties":{"storageinuse":{"type":"integer","description":"Deleting a transfer frees up some storage space in Filemail - this field provides information on the number of bytes still occuppied on the calling user's account.","format":"int64"}},"additionalProperties":false},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` # Forwarding a transfer ## POST /transfer/forward > Forwards an existing transfer to more recipients. Recipients may be specified using their email address or via contact group names (you need to have these groups defined in the contacts area first). Forwarding adds new recipients to an existing transfer and sends them download links (including tracking data) via email. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Transfer"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/transfer/forward":{"post":{"tags":["Transfer"],"description":"Forwards an existing transfer to more recipients. Recipients may be specified using their email address or via contact group names (you need to have these groups defined in the contacts area first). Forwarding adds new recipients to an existing transfer and sends them download links (including tracking data) via email.","requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/ForwardTransferRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/ForwardTransferRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/ForwardTransferRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/ForwardTransferRequest"}}}},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/TransferBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/TransferBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/TransferBaseResponse"}}}},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"ForwardTransferRequest":{"required":["to","transferid"],"type":"object","properties":{"transferid":{"minLength":1,"type":"string","description":"Unique identifier of the transfer that should be forwarded."},"to":{"type":"array","items":{"type":"string"},"description":"List of email addresses or contact group names which should receive this transfer."}},"additionalProperties":false},"TransferBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/Transfer"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"Transfer":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string"},"description":"This property is obsolete. Use 'recipients' property instead.","deprecated":true},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/TransferRecipient"},"description":"List of transfer recipients."},"failedRecipients":{"type":"integer","format":"int32"},"from":{"type":"string","description":"The sender's email address.","nullable":true},"subject":{"type":"string"},"message":{"type":"string"},"expiredate":{"type":"integer","description":"Transfer expiration date, as unix time, in milliseconds. To check if a transfer is permanent use the 'permanent' property.","format":"int64"},"extendedexpiredate":{"type":"integer","description":"Extended transfer expiration date, as unix time, in milliseconds. This value is only available if transfer was successfully recovered.","format":"int64"},"sentdate":{"type":"integer","description":"Date when the transfer has been created/initialized, as unix time, in milliseconds.","format":"int64"},"notify":{"type":"boolean","nullable":true},"status":{"type":"string","description":"Transfer status: STATUS_STARTED, STATUS_COMPLETE, STATUS_CANCELLED, STATUS_DELETED."},"id":{"type":"string","description":"Transfer unique identifier. Use it to fetch transfer details."},"trackid":{"type":"string","nullable":true},"url":{"type":"string","description":"Url to a web page where the transfer can be previewed and where files can be downloaded manually."},"size":{"type":"integer","description":"Transfer size in bytes.","format":"int64","nullable":true},"customlogourl":{"type":"string","nullable":true},"compressedfileurl":{"type":"string","description":"Url that allows to download the entire transfer directly as a ZIP archive."},"compressedfilestatus":{"type":"string"},"compressedfileformat":{"type":"string"},"torrentstatus":{"type":"string"},"torrenturl":{"type":"string"},"days":{"type":"integer","format":"int32"},"isexpired":{"type":"boolean","description":"Indicates whether the transfer is expired. False if expiredate or extendedexpiredate is in the future. True if expiredate is in the past and no extension exists, or if both expiredate and extendedexpiredate are in the past."},"source":{"type":"string","nullable":true},"key":{"type":"string","nullable":true},"fileserver":{"type":"string"},"fileserverurl":{"type":"string"},"fileserverurl_main":{"type":"string"},"footertext":{"type":"string"},"containsmorefiles":{"type":"integer","format":"int32","nullable":true},"customfields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"},"description":"List of transfer custom fields. These fields are only available if the transfer has been recevied by an organization via 'Receive files' page or via 'File request'. Available custom fields are configured by the organization administrator."},"files":{"type":"array","items":{"$ref":"#/components/schemas/FileDto"},"description":"List of files contained in this transfer. Preview URLs provide small thumbnails for identifying files; mediumpreview and largepreview return the same URL as smallpreview. Use each file's downloadurl to retrieve the original file."},"filesdb":{"type":"boolean","description":"Indicates when a transfer uses the FilesDB data model."},"hasfilesonotherfileserver":{"type":"boolean","description":"Indicates that at least one uploaded FilesDB file is stored on a physical fileserver different from the transfer main fileserver."},"fileExplorer":{"$ref":"#/components/schemas/FilesDbExplorerView"},"numberoffiles":{"type":"integer","format":"int32"},"numberofdownloads":{"type":"integer","format":"int32"},"downloads":{"type":"array","items":{"$ref":"#/components/schemas/Download"}},"antivirusscanstatus":{"type":"string"},"passwordprotected":{"type":"boolean"},"iconcolor":{"type":"string"},"iconletter":{"type":"string"},"ftphost":{"type":"string"},"region":{"type":"string","nullable":true},"protocol":{"type":"string","nullable":true},"e2ee":{"type":"boolean","nullable":true},"kind":{"type":"string","nullable":true},"ftpcorppasswordrequired":{"type":"boolean"},"udpthreshold":{"type":"integer","format":"int32"},"permanent":{"type":"boolean"},"maxdays":{"type":"integer","format":"int32"},"allowediting":{"type":"boolean"},"allowforwarding":{"type":"boolean"},"alloweditingexpiredate":{"type":"boolean"},"blockdownloads":{"type":"boolean","nullable":true},"infected":{"type":"boolean"},"infected_deleted":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"TransferRecipient":{"type":"object","properties":{"email":{"type":"string","nullable":true},"downloadlink":{"type":"string","nullable":true},"delivered":{"type":"boolean"},"deliveryerror":{"type":"string","nullable":true}},"additionalProperties":false},"CustomField":{"type":"object","properties":{"customfieldid":{"type":"string"},"defaultvalue":{"type":"string"},"description":{"type":"string"},"label":{"type":"string"},"customLabel":{"type":"string","nullable":true},"listitems":{"type":"string"},"required":{"type":"boolean","nullable":true},"visible":{"type":"boolean","nullable":true},"type":{"type":"string"},"rendertype":{"type":"integer","format":"int32"},"sortorder":{"type":"integer","format":"int32","nullable":true},"length":{"type":"integer","format":"int32","nullable":true},"startValue":{"type":"integer","format":"int64","nullable":true},"placeholder":{"type":"string"},"removable":{"type":"boolean"},"editableType":{"type":"boolean"},"editableRequired":{"type":"boolean"},"value":{"type":"string"},"barcodeimage":{"type":"string"}},"additionalProperties":false},"FileDto":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"filesize":{"type":"integer","format":"int64","nullable":true},"downloadurl":{"type":"string","description":"Url to one of Filemail fileservers - use it to download this individual file directly."},"fileid":{"type":"string","nullable":true},"thumbid":{"type":"string"},"previewurl":{"type":"string","description":"Url to a small thumbnail, or a file icon when a thumbnail is unavailable. Previews are intended for identifying files in a transfer. Use downloadurl to retrieve the original file.","nullable":true},"hascustompreview":{"type":"boolean","nullable":true},"videopreview":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Video"},"nullable":true},"downloads":{"type":"array","items":{"$ref":"#/components/schemas/Download"},"nullable":true},"filetype":{"type":"string","nullable":true},"filetypedescription":{"type":"string","nullable":true},"category":{"type":"string"},"smallpreview":{"type":"string","description":"Url to the same small thumbnail or file icon as previewurl.","nullable":true},"mediumpreview":{"type":"string","description":"Returns the same URL as smallpreview. Retained for compatibility; does not provide a medium-sized image.","nullable":true,"deprecated":true},"largepreview":{"type":"string","description":"Returns the same URL as smallpreview. Retained for compatibility; does not provide a large-sized image.","nullable":true,"deprecated":true},"hascustomthumbnail":{"type":"boolean","nullable":true},"transferid":{"type":"string"},"md5":{"type":"string","nullable":true},"suspecteddamage":{"type":"boolean","nullable":true}},"additionalProperties":false},"Video":{"type":"object","properties":{"size":{"type":"integer","format":"int64"},"resolution":{"type":"integer","format":"int32"},"downloadUrl":{"type":"string","nullable":true}},"additionalProperties":false},"Download":{"type":"object","properties":{"downloaddate":{"type":"integer","format":"int64"},"ip":{"type":"string"},"email":{"type":"string"},"location":{"type":"string"},"locationurl":{"type":"string"},"locationflag":{"type":"string","nullable":true},"kBps":{"type":"integer","format":"int32","nullable":true},"filename":{"type":"string","nullable":true},"filesize":{"type":"integer","format":"int64","nullable":true},"downloadtype":{"$ref":"#/components/schemas/DownloadType"}},"additionalProperties":false},"DownloadType":{"enum":["SingleFile","MultipleFiles","EntireTransfer"],"type":"string"},"FilesDbExplorerView":{"type":"object","properties":{"filesToken":{"type":"string","nullable":true},"parentItemId":{"type":"string","nullable":true},"offset":{"type":"integer","format":"int32"},"limit":{"type":"integer","format":"int32"},"total":{"type":"integer","format":"int32"},"itemsLeft":{"type":"integer","format":"int32"},"hasMore":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/FilesDbExplorerItem"}}},"additionalProperties":false},"FilesDbExplorerItem":{"type":"object","properties":{"uploadItemId":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","nullable":true},"filesize":{"type":"integer","format":"int64","nullable":true},"downloadurl":{"type":"string","nullable":true},"smallpreview":{"type":"string","nullable":true},"md5":{"type":"string","nullable":true}},"additionalProperties":false},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` # Sharing a transfer ## POST /transfer/share > Shares an existing transfer with more recipients. Recipients may be specified using their email address or via contact group names (you need to have these groups defined in the contacts area first). Sharings does not add new recipients to an existing transfer. Instead it only sends out download links. When sharing with an existing recipient - they will receive their original tracked download link again. When sharing with new recipients - they will receive the general (non-tracked) download link. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Transfer"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/transfer/share":{"post":{"tags":["Transfer"],"description":"Shares an existing transfer with more recipients. Recipients may be specified using their email address or via contact group names (you need to have these groups defined in the contacts area first). Sharings does not add new recipients to an existing transfer. Instead it only sends out download links. When sharing with an existing recipient - they will receive their original tracked download link again. When sharing with new recipients - they will receive the general (non-tracked) download link.","requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/ShareTransferRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/ShareTransferRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/ShareTransferRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/ShareTransferRequest"}}}},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/BaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"ShareTransferRequest":{"required":["to","transferid"],"type":"object","properties":{"transferid":{"minLength":1,"type":"string","description":"Unique identifier of the transfer that should be forwarded."},"message":{"maxLength":5000,"type":"string","description":"Custom message to be included in the email that will be sent out to recipients."},"to":{"type":"array","items":{"type":"string"},"description":"List of email addresses or contact group names which should receive this transfer."}},"additionalProperties":false},"BaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` # Renaming a file in a transfer ## PUT /transfer/file/rename > Renames an existing file in a transfer. File names include their relative paths inside a transfer e.g. \`/path/to/file.pdf\`. When renaming a file it is required to provide a new relative path. To only rename \`/path/to/file.pdf\` without changing its logical location specify \`/path/to/new\_file.pdf\`. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"File"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/transfer/file/rename":{"put":{"tags":["File"],"description":"Renames an existing file in a transfer. File names include their relative paths inside a transfer e.g. `/path/to/file.pdf`. When renaming a file it is required to provide a new relative path. To only rename `/path/to/file.pdf` without changing its logical location specify `/path/to/new_file.pdf`.","requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/RenameFileRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/RenameFileRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/RenameFileRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/RenameFileRequest"}}}},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/RenameFileDtoBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/RenameFileDtoBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/RenameFileDtoBaseResponse"}}}},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"RenameFileRequest":{"required":["fileKey","newFileName"],"type":"object","properties":{"fileKey":{"minLength":1,"type":"string","description":"File key / identifier which can be obtained from `GET /transfer` request. Every file in the transfer response includes its unique identifier under `fileid` property."},"newFileName":{"maxLength":2000,"minLength":1,"type":"string","description":"New relative path and name of the file within the transfer."}},"additionalProperties":false},"RenameFileDtoBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/RenameFileDto"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"RenameFileDto":{"type":"object","properties":{"fileName":{"type":"string","nullable":true}},"additionalProperties":false},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` # Deleting a file in a transfer ## DELETE /transfer/file/{filekey} > Deletes an existing file in a transfer, modifies transfer size and frees up storage space occupied by the file. Note that this operation cannot be reverted. Information about new occupied storage space for current user is contained in the response. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"File"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/transfer/file/{filekey}":{"delete":{"tags":["File"],"description":"Deletes an existing file in a transfer, modifies transfer size and frees up storage space occupied by the file. Note that this operation cannot be reverted. Information about new occupied storage space for current user is contained in the response.","parameters":[{"name":"filekey","in":"path","description":"File key / identifier which can be obtained from `GET /transfer` request. Every file in the transfer response includes its unique identifier under `fileid` property.","required":true,"schema":{"type":"string","description":"File key / identifier which can be obtained from `GET /transfer` request. Every file in the transfer response includes its unique identifier under `fileid` property."}}],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/DeleteFileDtoBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/DeleteFileDtoBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/DeleteFileDtoBaseResponse"}}}},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"DeleteFileDtoBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/DeleteFileDto"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"DeleteFileDto":{"type":"object","properties":{"storageinuse":{"type":"integer","description":"Deleting a file frees up some storage space in Filemail - this field provides information on the number of bytes still occuppied on the calling user's account.","format":"int64"}},"additionalProperties":false},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` # Downloading files This article explains how you can download transfers and individual files using the Filemail API. In order to download files first you need to fetch the transfer details. This is done using the [Transfer Details](/getting-transfer-details) endpoint. This endpoint requires a unique transfer identifier or transfer tracking ID. Optionally it also requires a password, in case the sender password-protected the transfer. Please refer to the linked article for more details. ### Example transfer This is an example of a typical transfer response (fields which are not relevant to this article are removed) {% code title="GET /transfer/gaaihvyksuejqub" lineNumbers="true" %} ```json "transfer": { "id": "gaaihvyksuejqub", "url": "https://app.filemail.com/d/gaaihvyksuejqub", "compressedfileurl": "https://8888.filemail.com/api/file/get?compressedfilekey=GIhUF8z7...", "files": [ { "filename": "path/to/file.jpg", "filesize": 93073, "downloadurl": "https://8888.filemail.com/api/file/get?filekey=n94A8Bc5...", "md5": "247797b2eb3e8e4ce398f66dbd9e7879" }, { "filename": "..." ... } ] } ``` {% endcode %} {% hint style="success" %} Note that there are 2 different possible approaches to downloading files in Filemail: 1. `files[n].downloadurl` - for downloading individual files in their original form (not compressed). 2. `transfer.compressedfileurl` - for downloading all files within the transfer as a ZIP archive. {% endhint %} ### Download endpoints - HTTP layer recommendations When using these endpoints please note the following: * **Always use HTTPS** to ensure the download is encrypted and protected from tampering or interception by malicious actors. Filemail API will always provide HTTPS URLs in response to transfer details requests. * Use `GET` HTTP method. * It is recommended to include your [API Key](/filemail-api-2.0/getting-started#api-keys) in the request. * It is recommended to provide custom `User-Agent` header, which briefly describes the calling service or app. E.g. `ACME File Downloader v.2.5.1` * It is **strongly recommended to apply chunking** while downloading. This is achieved with the `Range` header. {% hint style="success" %} Use chunk size equal to `50 * 1024 * 1024` bytes when downloading files and verifying their integrity. This provides maximum performance for file integrity checks. Also it is not guaranteed that the verification endpoints will work with a different chunk size in future releases. {% endhint %} * Both types of URLs (ZIP and individual files) support [range headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Range) however only **one range within that header is supported:** * `Range: bytes=100-200` :white\_check\_mark: * `Range: bytes=200-999, 2000-2499, 9500-` :no\_entry: * When using `Range` header bytes are zero-indexed. * Provide chunk boundaries that **both are within the file length limits**. When downloading last chunk you need to calculate the end position taking into account the total file size - use the `files[n].filesize` property - value is in bytes. * E.g. if you chose a chunk size of `50*1024*1024` (recommended) then a 70MB file (70\*10^6 bytes) will have 2 chunks with the following boundaries: * chunk 1: `Range: bytes=0-52428799` (end position = 50\*1024\*1024-1) * chunk 2: `Range: bytes=52428800-69999999` * When using `Range` header expect `206 Partial Content` response status code. * Without `Range` header expect `200 OK` response status code. * Response body contains raw file bytes. ### Download strategies There are 2 approaches available: 1. Download all files as ZIP: 1. Use the `compressedfileurl` property. 2. It is recommended to use `Range` header in order to perform chunked downloads. It is possible to download multiple chunks in parallel. Recommended maximum parallelism level is up to 4 chunks at a time. 3. This method does not allow MD5 integrity check of the chunks or the final ZIP archive. If you need to perform an integrity check - you'll need to unzip the archive and check every file individually. [Read more on verification](#verifying-individual-files-integrity). 4. Filemail will register single download tracking event, at the end of the archive. 2. Download files one-by-one: 1. Use the `files[n].downloadurl` property. 2. Make sure that you request all files from the Filemail API first - see `filesLimit` parameter in the [Getting transfer details](/getting-transfer-details#get-transfer-transferid)endpoint. 3. Loop over all returned files. It is possible to download multiple files in parallel. Recommended maximum parallelism level is up to 4 files at a time. 4. While download single file - it is also possible to introduce parallelism on the file chunk level using the `Range` header. Recommended maximum parallelism level is up to 4 chunks at a time. 5. Recommended chunk size is exactly `50*1024*1024` bytes. This gives you maximum performance when verifying file integrity. It is also a reasonable size in case a chunk should be re-downloaded (e.g. due to loss of network connectivity or because of a failed integrity check). 6. In this approach Filemail will register download tracking multiple times, at the end of each file. ### Verifying integrity of individual files and chunks {% hint style="warning" %} The following techniques apply only to individual files. They are not suitable for verifying entire ZIP archives or their chunks. {% endhint %} In order to verify integrity of an individual file: * Calculate MD5 hash of the downloaded file (see `LocalChunkMD5` method in the [Code Snippet](#net-code-snippet-chunked-download) section. Use `start=0` and `end=fileSize-1` . * Compare the resulting hash with the value in transfer details response `files[n].md5` . In order to verify integrity of a specific file chunk (downloaded using `Range` header): * Take the `host` from the URL you used to download the file. In the example response above it will be `8888.filemail.com` . * Issue a `GET` request to `https://[host]/GetRangeHash.ashx` endpoint. * Make sure to always use HTTPS protocol. * Include your [API Key](/filemail-api-2.0/getting-started#api-keys) in the request. * Provide request parameters in query string: | Query parameter | Parameter value | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `transferid` | Use the value from transfer details `transfer.id` | | `thefilename` | Use the URL-encoded value from transfer details `files[n].filename` | | `position` | This should be the start byte 0-based index of the chunk. Use the same value as in the download request `Range` header. | | `length` | Number of bytes equal to the chunk length. Note that last chunk of a file is usually shorter than the default 50 \* 1024 \* 1024 bytes. | Full request URL matching the example transfer and the returned response: 
GET https://8888.filemail.com/GetRangeHash.ashx?
  transferid=gaaihvyksuejqub&
  thefilename=path%2Fto%2Ffile.jpg&
  position=0&
  length=93073
---
{ 
  "responsestatus": "OK",
  "hash": "d47d82f98f02b204e9200a98ecf8417e"
}
Compare the received `hash` with an MD5 hash calculated locally on raw bytes of a downloaded chunk. MD5 hashes returned from Filemail API are formatted as lowercase hex-strings e.g. `d47d82f98f02b204e9200a98ecf8417e` {% hint style="success" %} It is strongly recommended to use chunk size of 50 \* 1024 \* 1024 bytes when downloading files and verifying their integrity. This provides maximum performance for file integrity checks. Also it is not guaranteed that the verification endpoints will work with a different chunk size in future releases.
{% endhint %} In case hash verification fails, this means there was a data corruption either when reading data from Filemail servers or during nwetwork transport. In such case re-download the entire chunk once again and repeat verification. ### Error handling Prepare your download flow to handle unexpected errors: * Retry a chunk when it fails (HTTP status other than `200` or `206`). * Use exponential backoff when issuing retries. * Apply maximum number of retries, then issue a notification to the calling app/service about file download error. Also cancel downloads of any other pending or queued chunks. * When a retry is successful - make sure to write the re-downloaded bytes to the same area of the file on the local file system. * When using .NET and [HttpClient](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient) class - handle at least `HttpRequestException` and `OperationCanceledException` (when using a `CancellationToken` ). ### .NET code snippet - chunked download Below you can find a simplified downloader implementation including remote MD5 verification written in C#/.NET 9. For clarity parallelism and error handling are not included. {% hint style="warning" %} This code is not production ready and should not be used in real-world applications. Please adjust the implementation by applying error handling. Optionally add parallelism and download entire transfer as ZIP archive instead of individual files. {% endhint %} ```csharp var transferId = "gaaihvyksuejqub"; var fileName = "path/to/file.jpg"; var downloadUrl = "https://8888.filemail.com/api/file/get?filekey=n94A8Bc5..."; var fileSize = 93073; using var outputFile = new FileStream("file.jpg", FileMode.Create, FileAccess.ReadWrite); var httpClient = new HttpClient(); var start = 0L; var chunkSize = 50000L * 3; while (start < fileSize) { var end = start + chunkSize - 1; if (end >= fileSize) { end = fileSize - 1; } var httpRequest = new HttpRequestMessage(HttpMethod.Get, new Uri(downloadUrl)); httpRequest.Headers.Add("x-api-key", "mJE5v1zHs...."); httpRequest.Headers.Range = new System.Net.Http.Headers.RangeHeaderValue(start, end); httpRequest.Headers.UserAgent.ParseAdd("FilemailDemoClient/2.5.1"); var responseStream = await httpClient.SendAsync(httpRequest, cancel); outputFile.Seek(start, SeekOrigin.Begin); await responseStream.Content.CopyToAsync(outputFile); Console.WriteLine($"chunk {start}-{end} complete"); Console.WriteLine($"verifying md5"); var localMD5 = await LocalChunkMD5(outputFile, start, end); var remoteMD5 = await GetRangeHash(downloadUrl, transferId, fileName, start, end - start + 1); if (false == string.Equals(localMD5, remoteMD5, StringComparison.OrdinalIgnoreCase)) { throw new ApplicationException($"{fileName} MD5 mismatch {start}-{end} / {localMD5} / {remoteMD5}"); } Console.WriteLine($"md5 OK"); start = end + 1; } Console.WriteLine($"file {fileName} complete"); Console.ReadLine(); ``` Here are the helper methods `LocalChunkMD5` (calculated from a fragment of the local file) and `GetRangeHash` (requested from Filemail server): ```csharp private static async Task GetRangeHash(string downloadUrl, string? transferid, string? thefilename, long position, long length) { var builder = new UriBuilder("https", new Uri(downloadUrl).Host); builder.Path = "GetRangeHash.ashx"; var query = HttpUtility.ParseQueryString(string.Empty); query["transferid"] = transferid; query["thefilename"] = thefilename; query["position"] = position.ToString(); query["length"] = length.ToString(); builder.Query = query.ToString(); var rangeHashUrl = builder.Uri.ToString(); var httpClient = new HttpClient(); var httpRequest = new HttpRequestMessage(HttpMethod.Get, rangeHashUrl); httpRequest.Headers.Add("x-api-key", "mJE5v1zHs...."); httpRequest.Headers.UserAgent.ParseAdd("FilemailDemoClient/2.5.1"); var response = await httpClient.SendAsync(httpRequest); var json = await response.Content.ReadAsStringAsync(); var hash = JObject.Parse(json)!["hash"]!.Value(); return hash; } private static async Task LocalChunkMD5(Stream stream, long start, long end) { stream.Seek(start, SeekOrigin.Begin); var buffer = new byte[1024 * 1024]; // 1MB memory buffer var remaining = end - start + 1; using var md5 = MD5.Create(); while (remaining > 0) { int read = await stream.ReadAsync(buffer, 0, (int)Math.Min(buffer.Length, remaining)); if (read <= 0) { break; } md5.TransformBlock(buffer, 0, read, null, 0); remaining -= read; } md5.TransformFinalBlock(Array.Empty(), 0, 0); return Convert.ToHexString(md5.Hash!).ToLowerInvariant(); } ``` # Handling contacts This page will help you getting contacts for your account through the Filemail API. As per now, the only available operation on contacts through our Public API is searching the contact list. Any matches is returned in an array with stored Name and E-mail and also a parameter `isGroup` that if `true` means that this is a group of contacts. ## POST /contact/search > Performs a search in current user's contacts and contact groups. Returns a list of matching contacts and groups. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Contact"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/contact/search":{"post":{"tags":["Contact"],"description":"Performs a search in current user's contacts and contact groups. Returns a list of matching contacts and groups.","requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/ContactSearchRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/ContactSearchRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/ContactSearchRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/ContactSearchRequest"}}}},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ContactSearchResultBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ContactSearchResultBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ContactSearchResultBaseResponse"}}}},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"ContactSearchRequest":{"required":["term"],"type":"object","properties":{"term":{"minLength":1,"type":"string","description":"The search phrase. For contact groups - it matches any substring of the group name. For contacts - it matches any substring of contact name or email address."},"exclude":{"type":"array","items":{"type":"string"},"description":"List of email addresses and contact group names to exclude from search results.","nullable":true},"limit":{"type":"integer","description":"Optional limit of returned search results. Note that results are first sorted by contact/group name, then by email. Search results will be limited to the requested limit based on the mentioned sort order.","format":"int32","nullable":true}},"additionalProperties":false},"ContactSearchResultBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/ContactSearchResult"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"ContactSearchResult":{"type":"object","properties":{"contacts":{"type":"array","items":{"$ref":"#/components/schemas/ContactSearchItem"},"description":"A list of matching contacts and contact groups."}},"additionalProperties":false},"ContactSearchItem":{"type":"object","properties":{"name":{"type":"string","description":"The contact or contact group name."},"email":{"type":"string","description":"The contact email. This property is not returned for contact groups."},"isGroup":{"type":"boolean","description":"`True` when the object represents a contact group. `False` when it represents a contact."},"memberCount":{"type":"integer","description":"Number of contacts within a contact group. This field is not returned for contacts.","format":"int32","nullable":true}},"additionalProperties":false,"description":"Represents single contat or contact group in the contact search results."},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` # Custom authentication This page explains how to act on behalf of other users with logintokens and refreshtokens. Use the endpoints described below when you need to execute API requests on behalf of other Filemail accounts. This can be useful when creating an app/UI that integrates with Filemail infrastructure, but requires other users to authenticate. Typical flow: 1. Use the [#post-auth-login](#post-auth-login "mention") providing user email and password. 2. Store the resulting `refreshtoken` for later use in a secure place (it is valid for 3 months). The resulting `logintoken` (valid for 7 days) should be used to authenticate further requests. 3. Include both `x-api-key` and `logintoken` in the request headers: 4. ``` x-api-key: mJE5v1zHs.... logintoken: r9BPAFW..... ``` 5. When you issue a request with an expired `logintoken` the server will return `401` HTTP status code. In that case use the `refreshtoken` and the [#post-auth-refreshtoken](#post-auth-refreshtoken "mention") endpoint to create a new `logintoken`. Note that the `refreshtoken` can be used only once. You will also get a new `refreshtoken` in the response every time you call [#post-auth-refreshtoken](#post-auth-refreshtoken "mention"). ## POST /auth/login > Authenticate as a Filemail user. This operation generates a short-lived (7 days) logintoken and a long-lasting (3 months) refreshtoken. The refreshtoken can be later used to obtain a new logintoken. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Auth"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/auth/login":{"post":{"tags":["Auth"],"description":"Authenticate as a Filemail user. This operation generates a short-lived (7 days) logintoken and a long-lasting (3 months) refreshtoken. The refreshtoken can be later used to obtain a new logintoken.","requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}}},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/LoginDtoBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/LoginDtoBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/LoginDtoBaseResponse"}}}},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"429":{"description":"Too Many Requests","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"LoginRequest":{"required":["email","password"],"type":"object","properties":{"email":{"minLength":1,"type":"string","description":"Email of the user."},"password":{"minLength":1,"type":"string","description":"Password matching the user email."}},"additionalProperties":false},"LoginDtoBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/LoginDto"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"LoginDto":{"required":["logintoken","logintokenExpireDate","refreshtoken"],"type":"object","properties":{"logintoken":{"minLength":1,"type":"string","description":"Login token. Append it to HTTP requests as `logintoken` header to issue authenticated requests."},"logintokenExpireDate":{"type":"integer","description":"Login token expiration date represented as unix time in milliseconds.","format":"int64"},"refreshtoken":{"minLength":1,"type":"string","description":"A one-time-use refresh token. Use it issue a new logintoken (and also a new refreshtoken). Default lifetime of this token is 3 months."},"twoFactorToken":{"type":"string","description":"This token is used only when setting up Multi-Factor-Authentication.","nullable":true},"signInStatus":{"$ref":"#/components/schemas/SignInStatus"}},"additionalProperties":false},"SignInStatus":{"enum":["NotAuthorized","Authorized","CaptchaRequired","PinRequired","SetupRequired"],"type":"string"},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` ## POST /auth/logout > Logout a Filemail user. This operation destroys the logintoken provided in the \`logintoken\` header and the associated refreshtoken. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Auth"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/auth/logout":{"post":{"tags":["Auth"],"description":"Logout a Filemail user. This operation destroys the logintoken provided in the `logintoken` header and the associated refreshtoken.","parameters":[{"name":"allDevices","in":"query","description":"When set to `true` all the user's logintokens and refreshtokens will be destroyed.","schema":{"type":"boolean","description":"When set to `true` all the user's logintokens and refreshtokens will be destroyed."}},{"name":"logintoken","in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/BaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` ## POST /auth/refreshtoken > Generates new logintoken and a new refreshtoken based on an existing refreshtoken (obtained in the \`login\` operation). The provided refreshtoken will be destroyed. ```json {"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Auth"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/auth/refreshtoken":{"post":{"tags":["Auth"],"description":"Generates new logintoken and a new refreshtoken based on an existing refreshtoken (obtained in the `login` operation). The provided refreshtoken will be destroyed.","requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}}}},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/RefreshTokenDtoBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenDtoBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenDtoBaseResponse"}}}},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"RefreshTokenRequest":{"type":"object","properties":{"refreshtoken":{"type":"string","description":"A one-time-use refreshtoken obtained from the `login` endpoint."}},"additionalProperties":false},"RefreshTokenDtoBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/RefreshTokenDto"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"RefreshTokenDto":{"type":"object","properties":{"logintoken":{"type":"string","nullable":true},"logintokenExpireDate":{"type":"integer","description":"Login token expiration date represented as unix time in milliseconds.","format":"int64","nullable":true},"refreshtoken":{"type":"string","nullable":true}},"additionalProperties":false},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}} ``` # Integrate Portal page Do you want to insert a Filemail Portal page into your website? No problem, just follow this guide. To insert a portal page on to your own website, you can use our embedded portal. Insert it anywhere on your webpage where you want the Portal uploader to appear. This is the minimum basic version which will show your default portal page: 
<div data-widget="portal" data-portal-url="https://your-subdomain.filemail.com"></div>
<script src="https://cdn.filemail.com/widgets/embed.js"></script>
If you want to embed a specific non default portal, use the /p/your-portal, configured as the Public Portal link in our portal configuration: 
<div data-widget="portal" data-portal-url="https://your-subdomain.filemail.com/p/your-portal"></div><script src="https://cdn.filemail.com/widgets/embed.js"></script>
### Custom data fields
Data fieldDescription
data-widthdefault 100%
data-heightdefault 800px
data-*Other data-* attributes are forwarded as query parameters to the portal URL, which can be used to pre-populate fields.
#### Example with different prefilled values: {% code overflow="wrap" %} ```html
``` {% endcode %} [^1]: your configured subdomain # Integrate Download page You can integrate Filemail Download Page on your own website by adding this code snippet to your HTML. Put it exactly where you want the downloader to appear on your page. {% code overflow="wrap" %} ```html
``` {% endcode %} # Web Form Integration If you have a custom form already on your own website, and want to enahnce it with large file upload ability - then use our integrated uploader designed for custom forms. {% code overflow="wrap" %} ```html
``` {% endcode %} While this integration can be used in many different scenarios, we will use the popular Wordpress plugin Contracts Form 7 in the following example. ## Contact Form 7 + Filemail You start by creating a new custom Contact form and set it up with all the fields you need.
At the place in the form where you want your file upload to be, you will add a small code snippet like this: {% code overflow="wrap" %} ```html
[hidden transfer-url id:transfer-url] ``` {% endcode %} ### Required attributes
Data fieldDescription
NameExample value
data-filemail-widget
Required with value "form"
data-companyid
Your companies account id. Found in Settings - My Company and on top you will see "Account ID".
data-target
This is the selector of an HTML input element (which is part of your custom form) where you want us to insert the link to uploaded files. It's most convenient to use the input's id attribute - in that case the selector is prefixed with # sign
### Optional attributes:
NameExample value
data-incoming-page-name
Portal page ID. Found in Portal Administration - Edit Portal - Leave empty to use default.
data-height
Specify the height of this component in pixels
data-color
Set a custom color on the component
data-to
Specify the to e-mail address if you don't want it to be the account default e-mail. It will appear in the Filemail inbox of this user(s) (multiple recipients are separated with comma).
After the user has selected files using the embedded file browser from Filemail, the files are being transferred and when finished, the URL will have been inserted into your hidden field in the contact form. Now user can post the form with the link to files included. That link can be then injected it into the Contact Form 7 email (the one which you receive when people submit the form) like this: ![](https://456380398-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FErlabM7V8PkhTh4HyjBB%2Fuploads%2FTtsBTkb9cz2BGNnOWlky%2Fimage.png?alt=media\&token=440dfc26-69db-4225-8c5c-a3645912ba5a)
# Zapier Supercharge Your Workflow with Filemail on Zapier
Want to automate your file transfers like a pro? Filemail now works with **Zapier**, giving you the power to connect with thousands of other apps — no code needed! With our Zapier integration, you can: * **Trigger actions** in other tools *when you receive a new transfer* * **Kick off workflows** automatically *when you send a transfer* Whether you're syncing files to cloud storage, notifying your team in Slack, or logging activity in a CRM — Filemail + Zapier makes it effortless. Start building your Zaps and let Filemail handle the heavy lifting! 👉 Explore [Filemail on Zapier](https://zapier.com/apps/filemail/integrations)
# CLI This article will tell you how you can use the Filemail CLI tool ## Installation instructions ### Install NodeJS v20 or above (minimum required version) 1. * For Windows and MacOS the installer is here: * For Linux distros, using built-in package managers, the instructions are here: 2. ### Install Filemail CLI using NPM with following command ``` npm install -g filemail-cli ``` ### Test upload of a file with the CLI: ``` filemail upload testFile.txt -u your@email.com ``` ### Available commands (run filemail -h to learn more) ``` Usage: filemail [options] [command] CLI for sending files to Filemail.com. Options: -V, --version output the version number -h, --help display help for command Commands: login [options] Login to Filemail API and get login token. logout Logout from Filemail API and destroy login token. upload [options] Upload files to Filemail.com. help [command] display help for command ``` ### Store password and settings in a json file for safety and convenience You can create a json config file to store your password and other settings. Thanks to this you won't need to pass them as arguments. An example json file containing username, password and from parameter value settings: ``` { "username": "my@login.com", "password": "myS3cretP4ssword", "from": "your@email.com" } ``` You can then use it with CLI passing it with `--config-file` option. For example:\ ​`filemail upload testFile.txt --config-file "c:\filemail-config.json"` ### All supported upload options (run filemail upload --help to learn more) | Option | Description | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `-g, --config-file ` | JSON file with configuration to apply. | | `-b, --log-file ` | Log file to save logs to. | | `-r, --api-retry-limit ` | Retry limit for API calls. (default: 3) | | `-d, --log-level ` | Logging level of the file logger. (Choices: Error, Warning, Info, Debug, Trace – default: Info) | | `--api-request-total-timeout ` | Request total timeout in milliseconds. (default: no timeout) | | `-u, --username ` | Your username for Filemail.com. Ignored if `--logintoken` option is present. | | `-p, --password ` | Your password for Filemail.com. If not provided and not in config file, CLI will prompt for it. | | `-l, --logintoken ` | Authentication token from Filemail API. | | `-t, --to ` | Recipient e-mail addresses (space separated, without quotation marks). | | `--from ` | Sender’s e-mail address. | | `--subject ` | Transfer subject. | | `-m, --message ` | Transfer message. | | `-n, --notify ` | Get email notification every time a file is downloaded. | | `-c, --confirmation ` | Send confirmation when files have been successfully sent. | | `-d, --days ` | Number of days files should be available to download. Defaults to account setting if not specified. | | `--upload-password ` | Password you want to use to secure the transfer. | | `--no-progress-bar` | Hide upload progress bar. | | `--no-infinite-retries` | Application exits as soon as any chunk’s retry limit exceeds `--chunk-upload-retry-limit`. | | `-k, --max-chunks-upload-in-parallel ` | Maximum number of chunks to upload simultaneously. (default: 9) | | `--chunk-upload-retry-limit ` | Retry limit for file chunks upload. (default: 3) | | `-e, --e2ee-key ` | End-to-end encryption key you want to use to encrypt the transfer. | | `-x, --max-chunk-size ` | Maximum size of a single file chunk in bytes. (default: 5 MB) | | `--upload-idle-timeout ` | Upload idle timeout in milliseconds. Time out inactive connections. (default: 90 sec) | | `-h, --help` | Display help for command. | The application will exit with code 0 if transfer was successful, otherwise it failed and you might want to check parameters and retry. ### Example: This example will send 2 files (`file1.txt` and `log.log`) and a folder (`/myFolder`) to 3 recipients (`patrick@email.com`, `monica@email.com` and `john@email.com`) from the user `nicole@email.com` having set an E2EE key to `superPassword` ``` filemail upload --username nicole@email.com --e2ee-key superPassword --to patrick@email.com monica@email.com john@email.com -- c:\file1.txt c:\log.log c:\myFolder ```