client.files()
Cada método de este espacio de nombres: su firma, sus parámetros, lo que devuelve y un ejemplo.
Métodos
Every attachment the mailbox holds, sent and received, and the files uploaded to it, with their bytes, the download links they went out as and whether each can be deleted.
files().list
List one page of the files the mailbox holds
Page list(RequestOptions options)Returns one page of the Files page: every attachment the mailbox holds, sent and received, and every file uploaded to it, with its name, type, size, the address it came to, the thread it belongs to and whether it can be deleted. files().listAll collects every page and files().iterate walks them lazily.
Only an upload that nothing depends on can be deleted, and its deletable is true. Every other row has a usage saying what keeps it: received, sent, linked for an upload that went out as a download link that still works, or scheduled for one attached to a message that has not gone out yet.
A key limited to particular addresses or domains sees only the files that arrived at them, the same boundary the thread list uses, so it does not see files uploaded for the whole workspace. A deleted file is not listed.
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 threads().listAttachments reads them.
Parámetros
options.qStringSearches the file name and its type. Words match loosely, and a close spelling is tried when nothing matches exactly.
options.kindStringKeeps one kind:
image,pdf,audio,videoortext, the choices of the filter on the Files page, also inuk.openemail.constants.FileKinds.options.directionStringKeeps one direction:
inboundfor files that arrived on a message,outboundfor files that went out on one,uploadedfor files put on the Files page.options.addressStringKeeps the files of one address, the
deliveredToof the file, compared without regard to case.options.sinceInstant or StringKeeps files added at or after this moment. An
Instantor an ISO 8601 string.options.untilInstant or StringKeeps files added before this moment. An
Instantor an ISO 8601 string.options.sortStringnewest(the default),oldest,largestorname, also inuk.openemail.constants.FileSorts. A cursor carries on in the order it was handed out in.options.limitintPage size, from 1 to 100. The server defaults to 25.
options.cursorStringThe
nextCursorof the previous page. Leave it out for the first page.options.apiKeyStringOverrides the client's API key for this call only.
Devuelve
A Page of file maps, with items, hasMore and nextCursor. Each item has id, filename, mimeType, sizeBytes, direction, threadId, messageId, deliveredTo, usage, deletable and createdAt.
Ejemplo
Page page = client.files().list(RequestOptions.create().set("kind", "pdf").set("sort", "largest")); for (Map<String, Object> file : page) { System.out.println(file.get("filename") + " " + file.get("sizeBytes"));} if (page.hasMore()) { System.out.println("Next page: " + page.nextCursor());}Notas
Needs
files:read. Reading an email withthreads:readstill reads the attachments on it, whilefiles:readreads every file, uploads included.The cursor is opaque and holds where the last row sat in this order. A cursor this list did not hand out, or one handed out under another
sort, is a 400invalid_cursor.
También disponible en
- API
GET /files- TypeScript
files.list()- Python
files.list()- Ruby
files.list- PHP
files->list- Go
Files.List- C#
Files.ListAsync- CLI
openemail files list
files().listAll
Collect every file into one list
List<Map<String, Object>> listAll(RequestOptions options)Walks every page of files().list and returns every file in one map, in the order sort names. One request per page, with the same filters on each.
Parámetros
options.qStringSearches the file name and its type. Words match loosely, and a close spelling is tried when nothing matches exactly.
options.kindStringKeeps one kind:
image,pdf,audio,videoortext, the choices of the filter on the Files page.options.directionStringKeeps one direction:
inboundfor files that arrived on a message,outboundfor files that went out on one,uploadedfor files put on the Files page.options.addressStringKeeps the files of one address, the
deliveredToof the file, compared without regard to case.options.sinceInstant or StringKeeps files added at or after this moment. An
Instantor an ISO 8601 string.options.untilInstant or StringKeeps files added before this moment. An
Instantor an ISO 8601 string.options.sortStringnewest(the default),oldest,largestorname. A cursor carries on in the order it was handed out in.options.limitintPage size for each request, from 1 to 100. The server defaults to 25.
options.cursorStringStarts the walk after this cursor instead of the first page.
options.apiKeyStringOverrides the client's API key for every page of this walk.
Devuelve
A list of file maps holding every file, each with the fields files().list returns.
Ejemplo
List<Map<String, Object>> all = client.files().listAll(RequestOptions.of("q", "invoice")); for (Map<String, Object> item : all) { System.out.println(item.get("id") + " " + item.get("createdAt"));}Notas
If any page fails, the exception is thrown and the rows already fetched are discarded.
También disponible en
- API
GET /files- TypeScript
files.listAll()- Python
files.list_all()- Ruby
files.list_all- PHP
files->listAll- Go
Files.ListAll- C#
Files.ListAllAsync
files().iterate
Stream the files one at a time
PagedIterable iterate(RequestOptions options)Returns a PagedIterable that yields one file at a time, in the order sort names, and requests the next page only once the current one is used up. Nothing is fetched until the loop starts, and breaking out of the for stops the requests.
Parámetros
options.qStringSearches the file name and its type. Words match loosely, and a close spelling is tried when nothing matches exactly.
options.kindStringKeeps one kind:
image,pdf,audio,videoortext, the choices of the filter on the Files page.options.directionStringKeeps one direction:
inboundfor files that arrived on a message,outboundfor files that went out on one,uploadedfor files put on the Files page.options.addressStringKeeps the files of one address, the
deliveredToof the file, compared without regard to case.options.sinceInstant or StringKeeps files added at or after this moment. An
Instantor an ISO 8601 string.options.untilInstant or StringKeeps files added before this moment. An
Instantor an ISO 8601 string.options.sortStringnewest(the default),oldest,largestorname. A cursor carries on in the order it was handed out in.options.limitintPage size for each request, from 1 to 100. The server defaults to 25.
options.cursorStringStarts the walk after this cursor instead of the first page.
options.apiKeyStringOverrides the client's API key for every page of this walk.
Devuelve
A PagedIterable that yields one file map per step.
Ejemplo
for (Map<String, Object> file : client.files().iterate(RequestOptions.of("sort", "oldest"))) { System.out.println(file.get("createdAt") + " " + file.get("filename"));}Notas
The generator is lazy, so an abandoned loop costs only the pages you consumed.
También disponible en
- API
GET /files- TypeScript
files.iterate()- Python
files.iterate()- Ruby
files.iterate- PHP
files->iterate- Go
Files.Iterate- C#
Files.IterateAsync
files().get
Read one file by id
Map<String, Object> get(String id, RequestOptions options)Returns one file: its name, type, size, whether it was sent, received or uploaded, the address it came to, the thread and message it belongs to, and whether it can be deleted. files().download fetches its bytes.
deletable is true only for an upload that nothing depends on. Otherwise usage says 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.
Parámetros
idStringObligatorioThe id from
files().list,file_and 24 hex.options.apiKeyStringOverrides the client's API key for this call only.
Devuelve
A map with the fields files().list returns for each file, usage and deletable included.
Ejemplo
Map<String, Object> file = client.files().get("file_6bb640f5b99e47deb758f1f5"); System.out.println(file.get("filename") + " " + file.get("mimeType"));Notas
A deleted file, one outside the addresses a narrowed key holds, and an unknown id all answer 404
resource_not_found.
También disponible en
- API
GET /files/{id}- TypeScript
files.get()- Python
files.get()- Ruby
files.get- PHP
files->get- Go
Files.Get- C#
Files.GetAsync- CLI
openemail files get
files().stats
Count the files and the space they take
Map<String, Object> stats(RequestOptions options)Returns 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.
Parámetros
options.apiKeyStringOverrides the client's API key for this call only.
Devuelve
A map with totals, received, sent and uploaded, each a map of files and bytes, then types, byDay, addresses and links.
Ejemplo
Map<String, Object> stats = client.files().stats(); System.out.println(stats.get("totals") + " " + stats.get("uploaded") + " " + stats.get("types"));Notas
Needs
files:read.typesholds at most the 8 types taking the most bytes andaddressesat most the 6 addresses holding the most. A file uploaded for the whole workspace has no address, so it counts in the totals and never inaddresses.byDaycovers the last 30 days in UTC, today included, and is sparse: a day on which no file arrived has no entry, so a chart must fill the gaps. EachdayisYYYY-MM-DD.linkscounts the download links that still work:sharesof them, fetcheddownloadstimes in all, last atlastDownloadAt, which is null when none was ever fetched. Scanners and link previewers are left out of the count.
También disponible en
- API
GET /files/stats- TypeScript
files.stats()- Python
files.stats()- Ruby
files.stats- PHP
files->stats- Go
Files.Stats- C#
Files.StatsAsync- CLI
openemail files stats
files().download
Fetch the bytes of a file
byte[] download(String id, RequestOptions options)Returns the file exactly as it is stored, the same bytes the Download action on the Files page saves. The response carries the file's own Content-Type and name.
Parámetros
idStringObligatorioThe id from
files().list.options.apiKeyStringOverrides the client's API key for this call only.
Devuelve
A string holding the bytes of the file.
Ejemplo
Map<String, Object> file = client.files().get("file_6bb640f5b99e47deb758f1f5"); byte[] bytes = client.files().download((String) file.get("id")); System.out.println(bytes.length + " bytes");Notas
The whole file is held in memory, so fetch very large ones one at a time.
A file whose bytes are gone from storage answers 404 like a missing one.
También disponible en
files().listLinks
List the download links a file went out as
Page listLinks(String id, RequestOptions options)Returns one page of the download links made for this file, newest first. A large attachment sent from OpenEmail travels as a link rather than inside the message, and each send makes a link of its own. Every row says how often it was fetched, when last, and whether it was revoked. While one of its links still works, an upload cannot be deleted.
A file attached inside a message has no links, because nothing records when those are opened.
Parámetros
idStringObligatorioThe file id from
files().list.options.limitintPage size, from 1 to 100. The server defaults to 25.
options.cursorStringThe
nextCursorof the previous page. Leave it out for the first page.options.apiKeyStringOverrides the client's API key for this call only.
Devuelve
A Page of link maps, with items, hasMore and nextCursor. Each item has id, url, host, downloads, lastDownloadAt, revokedAt and createdAt.
Ejemplo
Page page = client.files().listLinks("file_6bb640f5b99e47deb758f1f5"); for (Map<String, Object> link : page) { System.out.println(link.get("url") + " " + link.get("downloads"));} if (page.hasMore()) { System.out.println("Next page: " + page.nextCursor());}Notas
The count leaves out scanners and link previewers, the same classifier the
email.downloadedwebhook uses.
También disponible en
files().listAllLinks
Collect every download link of a file into one list
List<Map<String, Object>> listAllLinks(String id, RequestOptions options)Walks every page of files().listLinks and returns every download link of the file in one map, newest first. One request per page, with the same filters on each.
Parámetros
idStringObligatorioThe file id from
files().list.options.limitintPage size for each request, from 1 to 100. The server defaults to 25.
options.cursorStringStarts the walk after this cursor instead of the first page.
options.apiKeyStringOverrides the client's API key for every page of this walk.
Devuelve
A list of link maps holding every download link of the file, each with the fields files().listLinks returns.
Ejemplo
List<Map<String, Object>> links = client.files().listAllLinks("file_6bb640f5b99e47deb758f1f5"); for (Map<String, Object> link : links) { System.out.println(link.get("downloads"));}Notas
If any page fails, the exception is thrown and the rows already fetched are discarded.
También disponible en
files().iterateLinks
Stream the download links of a file one at a time
PagedIterable iterateLinks(String id, RequestOptions options)Returns a PagedIterable that yields one link at a time, newest first, and requests the next page only once the current one is used up. Nothing is fetched until the loop starts, and breaking out of the for stops the requests.
Parámetros
idStringObligatorioThe file id from
files().list.options.limitintPage size for each request, from 1 to 100. The server defaults to 25.
options.cursorStringStarts the walk after this cursor instead of the first page.
options.apiKeyStringOverrides the client's API key for every page of this walk.
Devuelve
A PagedIterable that yields one link map per step.
Ejemplo
for (Map<String, Object> link : client.files().iterateLinks("file_6bb640f5b99e47deb758f1f5")) { System.out.println(link.get("url") + " " + link.get("revokedAt"));}Notas
The generator is lazy, so an abandoned loop costs only the pages you consumed.
También disponible en
files().createLink
Publish a file at a public link
Map<String, Object> createLink(String id, RequestOptions options)Makes a public download link for the file and returns it. Anybody holding url can open the file without signing in, which is how an image or a document is referenced from an email or a web page. Each call makes a new link with its own download count, and a link keeps working until it is revoked with files().revokeLink or the file is deleted.
The link lives on the files host of domain when that domain has one set up, such as files.acme.com, else on the files host of the address the file belongs to, else on the OpenEmail API address. 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.
Parámetros
idStringObligatorioThe file id from
files().list.options.domainStringThe domain whose files host serves the link, such as
acme.com.options.apiKeyStringOverrides the client's API key for this call only.
Devuelve
A map with id, url, host, downloads, lastDownloadAt, revokedAt and createdAt.
Ejemplo
Map<String, Object> link = client.files().createLink("file_6bb640f5b99e47deb758f1f5", RequestOptions.of("domain", "acme.com")); System.out.println(link.get("url"));Notas
Needs
files:write.Not retried after a lost response, because a second call makes a second link. Look for it with
files().listLinksfirst.
También disponible en
files().revokeLink
Revoke a public link
Map<String, Object> revokeLink(String id, String linkId, RequestOptions options)Stops a public link from working, for good, including in mail that already went out with it, and returns the link with revokedAt set. Revoking a link that is already revoked returns it unchanged, so the call is safe to repeat. An unknown link is a 404.
Parámetros
idStringObligatorioThe file id from
files().list.linkIdStringObligatorioThe link id from
files().listLinksorfiles().createLink.options.apiKeyStringOverrides the client's API key for this call only.
Devuelve
A map for the link, with revokedAt set.
Ejemplo
Map<String, Object> result = client.files().revokeLink("file_6bb640f5b99e47deb758f1f5", "shr_2f9c4a1e7b3d"); System.out.println(result.get("id") + " " + result.get("url"));Notas
Needs
files:write.
También disponible en
files().revokeAllLinks
Revoke every link to a file
Map<String, Object> revokeAllLinks(String id, RequestOptions options)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. Returns revoked, how many links were still working. The file itself stays, and files().createLink 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.
Parámetros
idStringObligatorioThe file id from
files().list.options.apiKeyStringOverrides the client's API key for this call only.
Devuelve
A map with fileId and revoked, the number of links that stopped working.
Ejemplo
Map<String, Object> result = client.files().revokeAllLinks("file_6bb640f5b99e47deb758f1f5"); System.out.println(result.get("object") + " " + result.get("fileId"));Notas
A file with no working links returns
revokedat 0, so the call is safe to repeat.Needs
files:write.
También disponible en
files().upload
Upload a file to the Files page
Map<String, Object> upload(byte[] data, RequestOptions options)Stores the bytes as a new file, the way the Upload button on the Files page does, and returns it: direction is uploaded, usage is null and deletable is true. Attach it to a send as Body.of("fileId", file.get("id")) in the attachments of emails().send, which is how a file larger than the inline cap goes out.
data is a byte array, sent as the request body. The name travels as the filename query parameter, and it is cleaned rather than refused: characters a file name cannot hold become _, and a name longer than 255 characters is cut, keeping its extension. The type is contentType, and application/octet-stream without it. A value that is not shaped like a MIME type is stored as application/octet-stream too.
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 afterwards.
Parámetros
databyte[]ObligatorioThe file: a byte array, not empty and at most 100 MB.
options.filenameStringObligatorioThe name the file is stored and downloaded under, such as
report.pdf. A byte array has no name of its own, so a missing or blank name throws anIllegalArgumentExceptionbefore anything is sent.options.contentTypeStringThe MIME type, such as
application/pdf. Left out, the file is stored asapplication/octet-stream.options.timeoutDurationHow long the upload may take. Left out, it waits for the client timeout or ten minutes, whichever is longer.
options.apiKeyStringOverrides the client's API key for this call only.
Devuelve
A map for the new file, with direction set to uploaded, usage null and deletable true.
Ejemplo
Map<String, Object> file = client.files().upload(Files.readAllBytes(Path.of("report.pdf")), RequestOptions.create().set("filename", "report.pdf").set("contentType", "application/pdf")); System.out.println(file.get("id"));Notas
Needs
files:write, the same scope that deletes files.The SDK does not retry an upload, because a second attempt after a lost response could store the file twice. Look for it with
files().listbefore trying again.An empty file is a 400
upload_empty, a program or script, judged by its name, is a 400upload_dangerous, and a file over 100 MB is a 413upload_too_large. A key limited to addresses that holds none is a 403upload_no_address.A workspace keeps up to 10 GB of uploads, and past that a 507
upload_storage_fullholds until some are deleted. It takes 500 uploads an hour, deleted ones included, and more is a 429upload_rate_limited. A 502upload_failedmeans storage failed and nothing was kept, so it is safe to try again.
También disponible en
- API
POST /files- TypeScript
files.upload()- Python
files.upload()- Ruby
files.upload- PHP
files->upload- Go
Files.Upload- C#
Files.UploadAsync- CLI
openemail files upload
files().delete
Delete an uploaded file for good
Map<String, Object> delete(String id, RequestOptions options)Removes an uploaded file: its bytes are deleted 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 are refused with 409 file_in_use, and the message names the file and says why. 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.
files().deleteMany deletes up to 100 in one call and reports the ones it kept instead of failing.
Parámetros
idStringObligatorioThe id from
files().list.options.apiKeyStringOverrides the client's API key for this call only.
Devuelve
A map with object set to file, id and deleted set to true.
Ejemplo
Map<String, Object> removed = client.files().delete("file_6bb640f5b99e47deb758f1f5"); System.out.println(removed.get("deleted"));Notas
Needs
files:write, the same scope that uploads. A key limited to some addresses may delete only files that arrived at them, so an upload made for the whole workspace answers it 404.A file that is unknown, already deleted or out of reach answers 404
resource_not_found. A file in use answers 409file_in_usewithparamset toid, and itsusageonfiles().getsays which rule keeps it.The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.
También disponible en
- API
DELETE /files/{id}- TypeScript
files.delete()- Python
files.delete()- Ruby
files.delete- PHP
files->delete- Go
Files.Delete- C#
Files.DeleteAsync- CLI
openemail files delete
files().deleteMany
Delete up to 100 files in one call
Map<String, Object> deleteMany(List<String> ids, RequestOptions options)Deletes every file in ids that can be deleted, the way files().delete 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 uploaded file that nothing depends on can be deleted. 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. Each of those comes back in kept with its usage and a reason in plain words. 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.
Parámetros
idsList<String>Obligatorio1 to 100 file ids from
files().list. More than 100, or none, is a 422 onids. A repeated id counts once.options.apiKeyStringOverrides the client's API key for this call only.
Devuelve
A map with object set to file_batch_delete, deleted, kept and missing. deleted and missing hold ids, and each entry of kept is a map with id, filename, usage and reason.
Ejemplo
Map<String, Object> result = client.files().deleteMany(List.of("file_6bb640f5b99e47deb758f1f5", "file_0c3e2a91d4b7f6058e1a2b3c")); System.out.println(result.get("deleted") + " " + result.get("kept"));Notas
Needs
files:write, the same scope that uploads.A partial result returns rather than throws, so read
keptandmissingto see what stayed.The SDK does not retry it. Calling it again after a lost response reports the files the first call deleted in
missing.To clear out every upload that can go, keep the rows of
files().listAllwhosedeletableis true and pass their ids 100 at a time.