Java

client.drafts()

Jede Methode in diesem Namespace: ihre Signatur, ihre Parameter, was sie zurückgibt und ein Beispiel.

Methoden

Unsent messages saved in the mailbox, each stored as a thread labelled DRAFT.

`drafts().list`

List one page of drafts

drafts:readBlättert durch die Ergebnisse

Signatur

Page list(RequestOptions options)

Returns one page of saved drafts, most recently saved first. A row is only object and id, so call get for recipients, subject and body. A draft is stored as a thread labelled DRAFT, so this reads the same index as threads().list(RequestOptions.of("folder", "draft")).

query takes the same search syntax as threads().list. Plain words must all appear and match loosely, ignoring case, accents and separators, against the draft's subject, its sender and the first 4,000 characters of its body with markup stripped, while a quoted phrase is matched as written apart from case and accents, so "ben jamin" does not find "Ben-Jamin". Filler words such as the or emails are dropped when something else is left to search for. Recipients are stored as one list without roles and are not written for a draft, so to:, cc: and bcc: match nothing here. subject:, body: and from: narrow the search, and after:, before:, newer_than: and older_than: read the time the draft was last saved, in UTC, with after: including the day it names and before: excluding it. A draft saved with no subject is stored as (no subject), so subject:"no subject" finds it. The drafts folder always applies, so in: and folder is: operators such as is:sent cannot widen the search beyond drafts, in:anywhere included.

The API pages with an opaque pageToken, which the SDK hands back as nextCursor and accepts as cursor. A page holds 25 drafts unless limit says otherwise.

Parameter

options.queryString: Mailbox search over the subject, sender and body preview. Plain words must all appear and match loosely, a quoted phrase has to appear as written, filler words are dropped when something else is left to search for, and operators such as subject: and older_than:30d narrow it. to:, cc: and bcc: match nothing on a draft, and the search cannot leave drafts.
options.limitint: Drafts per page, a whole number from 1 to 100. Defaults to 25.
options.cursorString: The nextCursor of the previous page, passed back unchanged.
options.apiKeyString: Overrides the client's API key for this call only.

Rückgabe

A Page of maps with items, hasMore and nextCursor. Each item has only object, set to draft, and id.

Beispiel

Page page = client.drafts().list(RequestOptions.create().set("query", "subject:proposal").limit(20)); for (Map<String, Object> summary : page) {    System.out.println(summary.get("id"));} if (page.hasMore()) {    System.out.println("Next page: " + page.nextCursor());}

Hinweise

The server offers a cursor whenever a page comes back full, so hasMore can be true on the last page and the following call returns no items.
Saving a draft moves it to the top, so a draft edited while you page is not returned by later pages.
A value query cannot use is ignored rather than narrowing, so a typo in a value widens the result instead of emptying it. That covers category, larger:, smaller:, size:, messagesize:, list:, rfc822msgid:, received: and sent:, the category words such as is:promotions, a has: word naming no kind of attachment, an importance: other than high or low, an unreadable date and a duration whose unit is not h, d, w, m or y. An operator name it does not know, project: for instance, is searched as plain text.

Auch verfügbar über

API: GET /drafts
TypeScript: drafts.list()
Python: drafts.list()
Ruby: drafts.list
PHP: drafts->list
Go: Drafts.List
C#: Drafts.ListAsync
CLI: openemail drafts list

`drafts().listAll`

Collect every draft into one list

drafts:readBlättert durch die Ergebnisse

Signatur

List<Map<String, Object>> listAll(RequestOptions options)

Walks every page with the same query as list and returns once the last page is in, so the whole result sits in memory at once. Drafts rarely number in the thousands, which makes this the simplest way to read them all.

Each request asks for limit drafts, 25 when you leave it out. Passing cursor starts the walk from that page instead of the first. The walk ends when the server stops offering a cursor or hands back the one it was given, and a failure on any page throws and discards what was collected.

Parameter

options.queryString: Mailbox search over the subject, sender and body preview, as in list. Plain words must all appear and match loosely, a quoted phrase has to appear as written, filler words are dropped when something else is left to search for, and operators such as subject: and older_than:30d narrow it. to:, cc: and bcc: match nothing on a draft, and the search cannot leave drafts.
options.limitint: Page size for each request, a whole number from 1 to 100. Defaults to 25.
options.cursorString: A nextCursor to start the walk from instead of the first page.
options.apiKeyString: Overrides the client's API key for every page of this walk.

Rückgabe

A list of maps, every matching draft with object set to draft and its id, most recently saved first.

Beispiel

List<Map<String, Object>> drafts = client.drafts().listAll(RequestOptions.create().limit(100)); for (Map<String, Object> all : drafts) {    System.out.println(all.get("id"));}

Hinweise

Rows are ids only. Reading each draft afterwards is one get per id.
Each page is its own request with its own retries, so one failed attempt does not restart the walk.

Auch verfügbar über

API: GET /drafts
TypeScript: drafts.listAll()
Python: drafts.list_all()
Ruby: drafts.list_all
PHP: drafts->listAll
Go: Drafts.ListAll
C#: Drafts.ListAllAsync

`drafts().iterate`

Stream drafts one at a time across pages

drafts:readBlättert durch die Ergebnisse

Signatur

PagedIterable iterate(RequestOptions options)

Returns a PagedIterable that yields drafts one by one and requests the next page only when the current one is used up. Nothing is fetched until the loop starts, and breaking out of it stops further requests.

The cursor marks a position in save time rather than a row count, so deleting drafts inside the loop does not make the walk skip the ones after them. Updating a draft during the walk moves it to the top, and it is not yielded a second time.

Parameter

options.queryString: Mailbox search over the subject, sender and body preview, as in list. Plain words must all appear and match loosely, a quoted phrase has to appear as written, filler words are dropped when something else is left to search for, and operators such as subject: and older_than:30d narrow it. to:, cc: and bcc: match nothing on a draft, and the search cannot leave drafts.
options.limitint: Page size for each request, a whole number from 1 to 100. Defaults to 25.
options.cursorString: A nextCursor to start from instead of the first page.
options.apiKeyString: Overrides the client's API key for every page of this walk.

Rückgabe

A PagedIterable that yields one map per draft, each with object set to draft and id.

Beispiel

for (Map<String, Object> summary : client.drafts().iterate(RequestOptions.of("query", "older_than:30d"))) {    System.out.println(summary.get("id"));}

Hinweise

The generator is lazy, so an abandoned loop costs only the pages it consumed.

Auch verfügbar über

API: GET /drafts
TypeScript: drafts.iterate()
Python: drafts.iterate()
Ruby: drafts.iterate
PHP: drafts->iterate
Go: Drafts.Iterate
C#: Drafts.IterateAsync

`drafts().get`

Read a draft's recipients, subject and body

drafts:read

Signatur

Map<String, Object> get(String id, RequestOptions options)

Returns the fields a draft was saved with: to, cc, bcc, subject, the body as html, the from address, the threadId it replies to and its attachment list. The id must belong to a thread labelled DRAFT, so an ordinary thread id is a 404 here even though threads().get opens it.

Values come back normalised rather than as sent. Recipients are bare addresses with display names dropped, an empty subject reads as (no subject), and from is the address the draft was saved with. It is reported only while the workspace can still send as the stored sender, so a draft saved from an address that has since gone reads from as null, as does a draft saved without a sender. A draft saved with text and no html returns that text in html, unconverted.

threadId is null for a draft that does not reply to anything. forwardOf is the message in threadId the draft forwards, or null. attachments carries only filename, contentType and size, because draft attachments are stored as names and types without content: a forwarding draft attaches the forwarded message's files when it is sent, and any other file goes on the send itself.

Parameter

idStringErforderlich: Draft id, which starts with draft-.
options.apiKeyString: Overrides the client's API key for this call only.

Rückgabe

A map with id, to, cc, bcc, subject, html, from, threadId, forwardOf and attachments, a list of maps with filename, contentType and size.

Beispiel

Map<String, Object> draft = client.drafts().get("draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8"); System.out.println(draft.get("from") + " " + draft.get("to") + " " + draft.get("subject"));

Hinweise

A draft keeps the same id through every update.
A missing draft throws a NotFoundException, an ApiException whose isNotFound() is true.

Auch verfügbar über

API: GET /drafts/{id}
TypeScript: drafts.get()
Python: drafts.get()
Ruby: drafts.get
PHP: drafts->get
Go: Drafts.Get
C#: Drafts.GetAsync
CLI: openemail drafts get

`drafts().create`

Save a new draft

drafts:write

Signatur

Map<String, Object> create(Map<String, Object> body, RequestOptions options)

Saves an unsent message to the mailbox and returns its id. Every field is optional, so create([]) saves a blank draft. The body is strict: any key outside the fields below is a 422 invalid_parameter, and there is no field for attachments, which a send carries itself.

To forward an email, pass threadId and forwardOf, the id of a message in that thread from threads().get. The draft takes the names of that message's files and, unless you give a subject, its subject with Fwd: in front. Sending the draft with emails().send and its draftId then quotes the message below the body, attaches its files and threads it the way forwarding in the app does. forwardOf without threadId, or naming no message of that thread, is a 422 invalid_parameter.

Nothing is validated beyond length. Addresses in to, cc and bcc may carry a display name, as in Ada Lovelace <[email protected]>, and from is stored as given. A draft saved without from has no sender, and get reads from back as null. subject is capped at 998 characters, and html and text at 1,000,000 each. When both bodies are sent only html is kept.

threadId records the conversation the draft replies to, but the draft is stored as a thread of its own under its new id. It shows up in threads().list(RequestOptions.of("folder", "draft")), not inside the original thread.

Parameter

body.toList<String>: Recipient addresses, bare or with a display name.
body.ccList<String>: Copy recipients, bare or with a display name.
body.bccList<String>: Blind copy recipients, bare or with a display name.
body.subjectString: At most 998 characters. Empty is stored as (no subject).
body.htmlString: Body markup, at most 1,000,000 characters. Kept over text when both are set.
body.textString: Body used only when html is absent, at most 1,000,000 characters. Stored as is and read back in html.
body.fromString: Sender address, optionally with a display name. Left out, the draft is saved with no sender.
body.threadIdString: Id of the thread this draft replies to, or the thread holding the message forwardOf names.
body.forwardOfString: Id of the message in threadId to forward. Sending the draft quotes it below the body and attaches its files.
options.apiKeyString: Overrides the client's API key for this call only.

Rückgabe

A map with object set to draft and id, the new draft's id.

Beispiel

Map<String, Object> draft = client.drafts().create(Body.of(    "from", "Ada Lovelace <[email protected]>",    "to", List.of("[email protected]"),    "subject", "Engine notes for Thursday",    "html", "<p>Agenda below, comments welcome.</p>")); System.out.println(draft.get("id"));

Hinweise

The SDK does not retry a create after a network failure, because the endpoint takes no idempotency key and a second attempt saves a second draft.
A display name containing a comma splits into two broken recipients, because the lists are joined and split again on commas. Send such names without the comma.
Draft ids are draft- followed by a UUID.

Auch verfügbar über

API: POST /drafts
TypeScript: drafts.create()
Python: drafts.create()
Ruby: drafts.create
PHP: drafts->create
Go: Drafts.Create
C#: Drafts.CreateAsync
CLI: openemail drafts create

`drafts().update`

Change fields on a saved draft

drafts:write

Signatur

Map<String, Object> update(String id, Map<String, Object> body, RequestOptions options)

A partial update: each field you send replaces the stored value and each field you leave out keeps it. Arrays replace wholesale, so sending to with one address drops the rest. The limits and the strict body are the same as create.

The draft must already exist. An unknown id, or the id of a thread that is not a draft, is a 404 rather than a new draft. The returned id is the one to keep using, and it is always the id you passed.

Sending text without html replaces the stored body with that text. The draft keeps its attachment list, and a draft that forwards a message keeps forwarding it unless threadId moves it to another conversation.

Parameter

idStringErforderlich: Draft id, which starts with draft-.
body.toList<String>: Replacement recipients. An empty list clears them.
body.ccList<String>: Replacement copy recipients.
body.bccList<String>: Replacement blind copy recipients.
body.subjectString: Replacement subject, at most 998 characters.
body.htmlString: Replacement body markup, at most 1,000,000 characters.
body.textString: Replacement body used only when html is absent.
body.fromString: Replacement sender. An empty string clears it, leaving the draft with no sender.
body.threadIdString: Thread the draft replies to. An empty string detaches it.
options.apiKeyString: Overrides the client's API key for this call only.

Rückgabe

A map with object set to draft and id, the id you passed.

Beispiel

Map<String, Object> saved = client.drafts().update("draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8", Body.of(    "to", List.of("[email protected]", "[email protected]"),    "subject", "Engine notes for Thursday, revised")); System.out.println(saved.get("id"));

Hinweise

The SDK does not retry this call after a network failure. Read the draft with get before trying again.
Leaving a field out keeps its stored value. An empty string clears threadId, and an empty string or null clears from.

Auch verfügbar über

API: PATCH /drafts/{id}
TypeScript: drafts.update()
Python: drafts.update()
Ruby: drafts.update
PHP: drafts->update
Go: Drafts.Update
C#: Drafts.UpdateAsync
CLI: openemail drafts update

`drafts().delete`

Delete a draft permanently

drafts:write

Signatur

Map<String, Object> delete(String id, RequestOptions options)

Removes the draft, its stored body and its attachment entries from the mailbox. It does not go to the Bin and there is no undo.

The id must belong to a thread carrying the DRAFT label, so an ordinary thread id is a 404. Use threads().trash to remove real mail.

Parameter

idStringErforderlich: Draft id, which starts with draft-.
options.apiKeyString: Overrides the client's API key for this call only.

Rückgabe

A map with object set to draft, the id and deleted set to true.

Beispiel

Map<String, Object> removed = client.drafts().delete("draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8"); System.out.println(removed.get("id") + " " + removed.get("deleted"));

Hinweise

The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.
threads().update refuses DRAFT with 422 label_not_directly_settable, so an ordinary thread can never be turned into something this method deletes.

Auch verfügbar über

API: DELETE /drafts/{id}
TypeScript: drafts.delete()
Python: drafts.delete()
Ruby: drafts.delete
PHP: drafts->delete
Go: Drafts.Delete
C#: Drafts.DeleteAsync
CLI: openemail drafts delete

client.drafts()

Methoden

Parameter

Rückgabe

Beispiel

Hinweise

Auch verfügbar über

Parameter

Rückgabe

Beispiel

Hinweise

Auch verfügbar über

Parameter

Rückgabe

Beispiel

Hinweise

Auch verfügbar über

Parameter

Rückgabe

Beispiel

Hinweise

Auch verfügbar über

Parameter

Rückgabe

Beispiel

Hinweise

Auch verfügbar über

Parameter

Rückgabe

Beispiel

Hinweise

Auch verfügbar über

Parameter

Rückgabe

Beispiel

Hinweise

Auch verfügbar über

Der Posteingang,nach eigenen Regeln.

Der Posteingang,
nach eigenen Regeln.