Files

Every attachment the mailbox holds, sent and received, and every file uploaded to it, the Files page of the app: name, type, size, the address it came to, the thread it belongs to and whether it can be deleted. A deleted file is not listed.

Only an upload that nothing depends on can be deleted, and its deletable is true. Every other file has a usage saying what keeps it: received or sent for a file that came in or went out on a message, linked for an upload that went out as a download link that still works, and scheduled for one attached to a message that has not gone out yet.

Files have scopes of their own: files:read reads them and files:write uploads, deletes and publishes them. Reading an email with threads:read still reads the attachments on it. A key limited to particular addresses or domains sees only the files that arrived at them. It does not see files uploaded for the whole workspace, which have no deliveredTo.

The index starts from the day it shipped, so an older mailbox lists what has arrived since. Older attachments are still on their messages, where GET /threads/{id}/messages/{messageId}/attachments reads them.

Requires the files:read scope.

Stores a file on the Files page, the way its Upload button does, and answers with it. Send the file itself as the body, up to 100 MB, with its type in Content-Type and its name in filename. Attach it to a send as { "fileId": "..." } in the attachments of POST /emails, which is how a file larger than the inline cap goes out.

A key limited to particular addresses or domains uploads to the first address it holds, which becomes deliveredTo. An unlimited key uploads for the whole workspace and deliveredTo is null, so a narrowed key never reaches that file.

A workspace keeps up to 10 GB of uploads and takes 500 an hour. Nothing makes an upload safe to repeat, so after a lost response look for the file with GET /files before sending it again.

Requires the files:write scope.

The numbers on the Analytics tab of the Files page in one request: how many files the mailbox holds and how many bytes they take, in all and split into received, sent and uploaded, the file types and the addresses taking the most space, how many files arrived on each of the last 30 days, and the download links still working with how often they were fetched.

Deleted files are not counted. A key limited to particular addresses or domains counts only the files that arrived at them, so files uploaded for the whole workspace are left out of its numbers.

Requires the files:read scope.

Deletes up to 100 files in one call, each the way DELETE /files/{id} deletes one, and reports the rest instead of failing. It is what selecting several files on the Files page and pressing Delete does.

Only an upload that nothing depends on is deleted. A file that was received or sent, or an upload that went out as a download link that still works or is attached to a message that has not gone out yet, comes back in kept with its usage and a reason. An id that is unknown, already deleted or outside the addresses a narrowed key holds comes back in missing. The rule is checked again at the moment of deleting, so a file that became used in between is kept. There is no undo.

Requires the files:write scope.

One file, with usage and deletable saying whether it can be deleted and what keeps it when it cannot. A deleted file, one outside the addresses a narrowed key holds, and an unknown id all answer 404.

Requires the files:read scope.

Deletes an uploaded file: its bytes are removed from storage and it leaves the Files page. The row stays, marked deleted, so the index knows the file existed. There is no undo.

Only an upload that nothing depends on can be deleted, the files whose deletable is true. A file that was received or sent stays with its message, and so does an upload that went out as a download link that still works or is attached to a message that has not gone out yet: those answer 409 file_in_use. An upload that was sent inside a message can still be deleted, because the message keeps its own copy, which is listed as a separate sent file.

It needs the same scope as uploading. A key limited to particular addresses or domains may delete only a file that arrived at one of them. POST /files/batch-delete deletes many at once.

Requires the files:write scope.

The file exactly as it is stored, the same bytes the Download action on the Files page saves. A file whose bytes are gone from storage answers 404 like a missing one.

Requires the files:read scope.

Every download link made for this file, newest first, revoked ones included. A large attachment sent from OpenEmail travels as a link rather than inside the message, and each send makes a link of its own, and POST /files/{id}/links makes one on purpose, so this is how often each copy was fetched and when last.

A file attached inside a message has no links, because nothing records when those are opened.

Requires the files:read scope.

Makes a public download link for the file that anybody holding it can open without signing in, which is how an image or document is referenced from an email or a web page. Each call makes a new link with its own download count. The link keeps working until it is revoked or the file is deleted.

A file that came in or went out on a message is copied to public storage first. Programs and scripts are refused with 422 file_unshareable.

Requires the files:write scope.

Makes the file private, as Make private on the Files page does: every public download link to it stops working at once, including the ones in mail that already went out, and revoked says how many were still working. A file with no live links answers revoked: 0, so the call is safe to repeat. The file itself stays, and POST /files/{id}/links can publish it again at a new link.

A key limited to particular addresses reaches only the files that arrived at them, and any other file is a 404.

Requires the files:write scope.

Stops a public link from working, for good, including in mail that already went out with it. Revoking a link that is already revoked answers with it unchanged. An unknown link is a 404 not_found.

Requires the files:write scope.