| ## File Uploads |
| <aside class="warning"> |
| Not implemented |
| </aside> |
| |
| There is a single endpoint which handles all file uploads, regardless of what they are to be used for. To upload a file, submit a POST request to the file upload endpoint (see the authentication section for information on how to obtain this URL). The Content-Type MUST be correctly set for the type of the file being uploaded. The request MUST be authenticated as per any HTTP request. The request MAY include an "X-JMAP-AccountId" header, with the value being the account to use for the request. Otherwise, the default account will be used. |
| |
| The server will respond with one of the following HTTP response codes: |
| |
| #### `201`: File uploaded successfully |
| |
| The content of the response is a single JSON object with the following properties: |
| |
| - **accountId**: `String` |
| The id of the account used for the call. |
| - **blobId**: `String`, |
| The id representing the binary data uploaded. The data for this id is immutable. The id *only* refers to the binary data, not any metadata. |
| - **type**: `String` |
| The content type of the file. |
| - **size**: `Number` |
| The size of the file in bytes. |
| - **expires**: `Date` |
| The date the file will be deleted from temp storage if not referenced by another object, e.g. used in a draft. |
| |
| Once the file has been used, for example attached to a draft message, the file will no longer expire, and is instead guaranteed to exist while at least one other object references it. Once no other object references it, the server MAY immediately delete the file at any time. It MUST NOT delete the file during the method call which removed the last reference, so that if there is a create and a delete within the same call which both reference the file, this always works. |
| |
| If uploading a file would take the user over quota, the server SHOULD delete previously uploaded (but unused) files before their expiry time. This means a client does not have to explicitly delete unused temporary files (indeed, there is no way for it to do so). |
| |
| If identical binary content is uploaded, the same *blobId* SHOULD be returned. |
| |
| #### `400`: Bad request |
| |
| The request was malformed (this includes the case where an `X-JMAP-AccountId` header is sent with a value that does not exist). The client SHOULD NOT retry the same request. |
| |
| #### `401`: Unauthorized |
| |
| The `Authorization` header was missing or did not contain a valid token. Reauthenticate and then retry the request. There is no content in the response. |
| |
| #### `404`: Not Found |
| |
| The upload endpoint has moved. See the Authentication section of the spec for how to rediscover the current URL to use. There is no content in the response. |
| |
| #### `413`: Request Entity Too Large |
| |
| The file is larger than the maximum size the server is willing to accept for a single file. The client SHOULD NOT retry uploading the same file. There is no content in the response. The client may discover the maximum size the server is prepared to accept by inspecting the capabilities property of the Account object. |
| |
| #### `415`: Unsupported Media Type |
| |
| The server MAY choose to not allow certain content types to be uploaded, such as executable files. This error response is returned if an unacceptable type is uploaded. The client SHOULD NOT retry uploading the same file. There is no content in the response. |
| |
| #### `503`: Service Unavailable |
| |
| The server is currently down. The client should try again later with exponential backoff. There is no content in the response. |
