Java

client.labels()

この名前空間のすべてのメソッドの、シグネチャ、パラメーター、戻り値、例。

メソッド

The user labels a thread can carry: list, create, rename, recolour and delete them, have AI apply one to arriving mail and try it on recent mail first, and read the palette of colours the app offers.

`labels().list`

List the workspace's labels, a page at a time

labels:read結果をページ単位で取得

シグネチャ

Page list(RequestOptions options)

Returns one page of the workspace's user labels, sorted by name and then by id. labels().listAll collects every page and labels().iterate walks them lazily. Each label carries its colour, threadCount (how many conversations carry it now), aiInstructions and aiEnabled, which say whether AI applies it to arriving mail, and createdAt and updatedAt, which is everything the Labels table in the app shows.

System labels such as INBOX, STARRED and UNREAD are not listed. A thread carries them and threads().update takes them, but they cannot be renamed, recoloured or deleted.

color is null on a label saved with no colour. Otherwise color.backgroundColor is a hex value or a gradient token such as gradient:sunset, and color.textColor is the ink the app draws on it, worked out on the server rather than stored.

パラメーター

options.limitint: Page size, from 1 to 100. The server defaults to 25.
options.cursorString: The nextCursor of the previous page, passed back as it came. Leave it out for the first page.
options.apiKeyString: Overrides the client's API key for this call only.

戻り値

A Page of label maps, with items, hasMore and nextCursor. Each item has id, name, type, color, threadCount, aiInstructions, aiEnabled, createdAt and updatedAt.

例

Page page = client.labels().list(RequestOptions.create().limit(50)); for (Map<String, Object> label : page) {    System.out.println(label.get("name") + " " + label.get("threadCount"));} if (page.hasMore()) {    System.out.println("Next page: " + page.nextCursor());}

注意事項

Labels belong to the workspace, so a narrowed key still sees every label. threadCount is the exception: it counts only conversations delivered to the addresses the key holds.
An id is fixed when the label is created and survives a rename, so match on id rather than name in stored configuration.
The sidebar order in the app is each person's own arrangement and is not exposed.
The cursor is opaque and holds where the last row sat in this order, so a row deleted or edited between pages never breaks the walk: the next page starts at the first row that sorts after it. A cursor this list did not hand out is a 400 invalid_cursor.

ほかの提供先

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

`labels().listAll`

Collect every label into one list

labels:read結果をページ単位で取得

シグネチャ

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

Walks every page of labels().list and returns all labels in one map, sorted by name and then by id. One request per page.

パラメーター

options.limitint: Page size for each request, from 1 to 100. The server defaults to 25.
options.cursorString: Starts the walk after this cursor instead of the first page.
options.apiKeyString: Overrides the client's API key for every page of this walk.

戻り値

A list of label maps holding every label.

例

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

注意事項

If any page fails, the exception is thrown and the labels already fetched are discarded.

ほかの提供先

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

`labels().iterate`

Stream the labels one at a time

labels:read結果をページ単位で取得

シグネチャ

PagedIterable iterate(RequestOptions options)

Returns a PagedIterable that yields labels one at a time, sorted by name and then by id, 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.

パラメーター

options.limitint: Page size for each request, from 1 to 100. The server defaults to 25.
options.cursorString: Starts the walk after this cursor instead of the first page.
options.apiKeyString: Overrides the client's API key for every page of this walk.

戻り値

A PagedIterable that yields one label map per step.

例

for (Map<String, Object> label : client.labels().iterate()) {    System.out.println(label.get("threadCount") + " " + label.get("name"));}

注意事項

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

ほかの提供先

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

`labels().listColors`

List the colours the app offers for labels

labels:read

シグネチャ

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

Returns the whole label palette as a plain list: the fourteen solid colours and seven gradients the app offers when you make or edit a label, in the order it shows them. It is a fixed catalogue, so there is no paging. Fetch it once and keep it.

value is what to send as color.backgroundColor: a hex such as #3B82F6 for a solid, a token such as gradient:sunset for a gradient. textColor is the ink drawn on it. A gradient also carries from and to, drawn at 135 degrees, and solid, one hex for places a gradient cannot go.

A label may carry a colour outside this list. Any hex set through the API is kept as it is, and the app offers it back as its own swatch.

パラメーター

options.apiKeyString: Overrides the client's API key for this call only.

戻り値

A list of maps, each with kind, name, value, solid, from, to and textColor.

例

List<Map<String, Object>> colors = client.labels().listColors(); for (Map<String, Object> color : colors) {    System.out.println(color.get("name"));}

注意事項

kind is solid or gradient. from and to are null on a solid.

ほかの提供先

API: GET /labels/colors
TypeScript: labels.listColors()
Python: labels.list_colors()
Ruby: labels.list_colors
PHP: labels->listColors
Go: Labels.ListColors
C#: Labels.ListColorsAsync
CLI: openemail labels list-colors

`labels().get`

Read one user label by id

labels:read

シグネチャ

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

Looks up a single user label and returns it in the same shape as a row of labels().list, with its colour, threadCount, aiInstructions, aiEnabled, createdAt and updatedAt.

Only user labels are served. INBOX, TRASH and the other system ids are a 404 here even though threads carry them. Ids are matched exactly, so user_receipts does not find USER_RECEIPTS.

パラメーター

idString必須: Label id such as USER_RECEIPTS, matched case sensitively.
options.apiKeyString: Overrides the client's API key for this call only.

戻り値

A map with id, name, type set to user, color, threadCount, aiInstructions, aiEnabled, createdAt and updatedAt.

例

Map<String, Object> label = client.labels().get("USER_RECEIPTS"); System.out.println(label.get("name") + " " + label.get("color") + " " + label.get("threadCount"));

注意事項

A missing label throws a NotFoundException, whose isNotFound() is true and whose code() is resource_not_found.

ほかの提供先

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

`labels().create`

Create a user label

labels:write

シグネチャ

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

Creates a label and returns it as it is stored. name is trimmed and must then be 1 to 225 characters. The id is derived from the name as USER_ followed by the name upper cased, with each run of whitespace turned into _, so Big Clients becomes USER_BIG_CLIENTS, and it never changes afterwards.

A name another label already has, compared without case, is refused with 409 label_name_taken, and so is a name whose id another label holds because it was created under that name and renamed since. An existing label is never silently overwritten. A workspace holds at most 50 user labels, and the call past that is a 422 label_limit_reached on name.

color is optional. color.backgroundColor is a hex colour (#RGB, #RGBA, #RRGGBB or #RRGGBBAA, stored upper cased) or a gradient token such as gradient:sunset, and anything else is a 422 invalid_parameter on color.backgroundColor. labels().listColors returns the palette the app offers. textColor may be sent but is ignored: the ink is worked out from the background. Leaving color out stores no colour.

aiInstructions says what the label is for in plain words, such as invoices and receipts. With aiEnabled on, AI reads each arriving message against them and adds the label when it fits. It skips spam, the Bin, encrypted mail and muted threads, and it only labels: it never archives or moves anything. Turning aiEnabled on needs instructions and a paid plan, and a workspace may have 10 such labels. Without instructions it is a 422 invalid_parameter on aiInstructions, on the free plan a 403 plan_required, and past the tenth a 422 ai_label_limit_reached.

パラメーター

body.nameString必須: Display name, trimmed, 1 to 225 characters. Also decides the id.
body.colorMap<String, Object>: The colour, a map with backgroundColor. Leave it out for a label with no colour.
body.color.backgroundColorString: A hex colour such as #3B82F6 or a gradient token such as gradient:sunset, at most 32 characters. Required once color is given.
body.color.textColorString: Accepted and ignored. The ink is worked out from backgroundColor.
body.aiInstructionsString or null: What the label is for, in plain words, up to 500 characters, such as invoices and receipts.
body.aiEnabledboolean: Have AI apply the label to arriving mail that fits aiInstructions. It needs instructions and a paid plan, and a workspace may have 10 such labels.
options.apiKeyString: Overrides the client's API key for this call only.

戻り値

A map with the new id, the trimmed name, color, threadCount of 0, aiInstructions, aiEnabled, createdAt and updatedAt.

例

Map<String, Object> label = client.labels().create(Body.of("name", "Big Clients", "color", Body.of("backgroundColor", "gradient:aurora"))); System.out.println(label.get("id") + " " + label.get("color"));

注意事項

The SDK does not retry a create after a network failure. If you retry by hand after a lost response, a 409 label_name_taken means the first attempt succeeded.
The label is created before its AI settings are saved, so a create refused with plan_required, ai_label_limit_reached or invalid_parameter on aiInstructions leaves the label in place with no instructions and aiEnabled off. Set them with update rather than creating it again.
test runs the instructions over recent mail and shows what they would catch, without labelling anything.

ほかの提供先

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

`labels().update`

Rename or recolour a user label, or change what AI does with it

labels:write

シグネチャ

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

Renames a label, recolours it, or changes what AI does with it, and returns it as it is stored. Send any of name, color, aiInstructions and aiEnabled: a field left out stays as it is, and a patch with none of them is a 422. "color", null, or an empty backgroundColor, clears the colour.

The id never changes. A label created as Receipts keeps USER_RECEIPTS after a rename to Invoices, and every thread keeps the label. A new name another label already has, compared without case, is refused with 409 label_name_taken.

Colours follow the rules on labels().create: a hex value or a gradient token, and anything else is a 422 invalid_parameter. Only user labels can be changed, and a system label id is a 404.

With aiEnabled on, AI reads each arriving message against aiInstructions and adds the label when it fits. It skips spam, the Bin, encrypted mail and muted threads, and it only labels: it never archives or moves anything. Turning it on needs instructions and a paid plan, and a workspace may have 10 such labels. Without instructions it is a 422 invalid_parameter on aiInstructions, on the free plan a 403 plan_required, and past the tenth a 422 ai_label_limit_reached. "aiInstructions", null clears the instructions, which also turns aiEnabled off.

パラメーター

idString必須: Label id such as USER_RECEIPTS.
patch.nameString: New display name, trimmed, 1 to 225 characters. Left out, the name stays.
patch.colorMap<String, Object> or null: New colour, a map with backgroundColor. Null clears it, and leaving it out keeps the stored colour.
patch.color.backgroundColorString: A hex colour or a gradient token, at most 32 characters. An empty string clears the colour.
patch.color.textColorString: Accepted and ignored. The ink is worked out from backgroundColor.
patch.aiInstructionsString or null: What the label is for, in plain words, up to 500 characters. Null clears it, which also turns aiEnabled off. Left out, it stays.
patch.aiEnabledboolean: Whether AI applies the label to arriving mail that fits aiInstructions. Turning it on needs instructions and a paid plan, and a workspace may have 10 such labels. Left out, it stays.
options.apiKeyString: Overrides the client's API key for this call only.

戻り値

A map with the unchanged id and the new name, color, aiInstructions and aiEnabled.

例

Map<String, Object> saved = client.labels().update("USER_RECEIPTS", Body.of("color", Body.of("backgroundColor", "#EA9602"))); System.out.println(saved.get("id") + " " + saved.get("name") + " " + saved.get("color"));

注意事項

The SDK retries this call after a network failure, since the same patch sent twice leaves the same label.
test runs instructions over recent mail and shows what they would catch, so you can try wording before you save it here.

ほかの提供先

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

`labels().test`

Try a label on recent mail

labels:writethreads:read

シグネチャ

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

Runs the AI over the newest 20 inbox threads and returns the ones the label would catch, without labelling anything. Send aiInstructions to try wording you have not saved yet, or leave the body out to try what the label holds.

It spends one AI action of the caller, which the labelling of arriving mail never does. A message that arrived encrypted is skipped, and a key limited to particular addresses reads only the threads delivered to them.

パラメーター

idString必須: Label id such as USER_RECEIPTS, as list returns it.
body.aiInstructionsString: What the label is for, in plain words, 1 to 500 characters. Left out, the instructions saved on the label are tried.
options.apiKeyString: Overrides the client's API key for this call only.

戻り値

A map with object set to label_test, labelId, examined and matched. examined is how many recent threads were read, and each match is a map with threadId, subject, sender and receivedOn, where sender is the address the newest message is from and receivedOn is when it arrived, as its Date header gives it, or null.

例

Map<String, Object> result = client.labels().test("USER_RECEIPTS", Body.of("aiInstructions", "invoices and receipts")); System.out.println(result.get("matched") + " " + result.get("examined"));

注意事項

Needs both labels:write and threads:read. An unknown label id is a 404.
With no instructions to try, neither in the call nor on the label, it is a 422 invalid_parameter. A spent AI allowance is a 429 ai_quota_exceeded, and an install with no AI model set up a 409 ai_not_configured.
Nothing is saved: the label keeps the instructions it had. Save the wording with update once it catches what you want.
The SDK does not retry it, because each call spends an AI action.

ほかの提供先

API: POST /labels/{id}/test
TypeScript: labels.test()
Python: labels.test()
Ruby: labels.test
PHP: labels->test
Go: Labels.Test
C#: Labels.TestAsync
CLI: openemail labels test

`labels().delete`

Delete a user label and remove it from every thread

labels:write

シグネチャ

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

Deletes a user label and, in the same transaction, takes it off every thread that carried it. The threads are otherwise untouched, so a thread that was only filed under this label stays in whatever folder it was in.

There is no undo. Creating a label with the same name again produces the same id, but the threads it was removed from do not get it back. Only user labels can be deleted, and a system label id is a 404.

パラメーター

idString必須: Label id such as USER_OLD_PROJECT.
options.apiKeyString: Overrides the client's API key for this call only.

戻り値

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

例

Map<String, Object> removed = client.labels().delete("USER_OLD_PROJECT"); System.out.println(removed.get("id") + " " + removed.get("deleted"));

注意事項

The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.
Call labels().get first if you want to say how many conversations will lose the label: its threadCount is that number.

ほかの提供先

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

client.labels()

メソッド

パラメーター

戻り値

例

注意事項

ほかの提供先

パラメーター

戻り値

例

注意事項

ほかの提供先

パラメーター

戻り値

例

注意事項

ほかの提供先

パラメーター

戻り値

例

注意事項

ほかの提供先

パラメーター

戻り値

例

注意事項

ほかの提供先

パラメーター

戻り値

例

注意事項

ほかの提供先

パラメーター

戻り値

例

注意事項

ほかの提供先

パラメーター

戻り値

例

注意事項

ほかの提供先

パラメーター

戻り値

例

注意事項

ほかの提供先

受信トレイを、あなたの思いどおりに。

受信トレイを、
あなたの思いどおりに。