> For the complete documentation index, see [llms.txt](https://docs.filemail.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.filemail.com/api/sending-files/initialize.md).

# 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. This value may be helpful only in the event of failures during file uploads.","format":"int64","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"}}},"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}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.filemail.com/api/sending-files/initialize.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.