openemail.labels
Bu ad alanındaki her yöntem: imzası, parametreleri, döndürdüğü değer ve bir örnek.
Yöntemler
The labels a thread can carry.
labels.list()
List the workspace's labels, a page at a time
list(options?: ListOptions): Promise<Page<LabelResource>>Resolves one page of the workspace's user labels, sorted by name and then by id. listAll collects every page and iterate walks them lazily. Each label carries its colour, threadCount (how many conversations carry it now) 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.
Parametreler
options.limitnumberPage size, from 1 to 100. The server defaults to 25.
options.cursorstringThe
nextCursorof the previous page, passed back as it came. Leave it out for the first page.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client API key for this call only.
Döndürür
Page<LabelResource> with items, hasMore and nextCursor. Each item has id, name, type, color, threadCount, createdAt and updatedAt.
Örnek
const page = await openemail.labels.list({ limit: 50 }) for (const label of page.items) console.log(label.name, label.threadCount) if (page.hasMore) console.log('more after', page.nextCursor)Notlar
Labels belong to the workspace, so a narrowed key still sees every label.
threadCountis 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
idrather thannamein 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.
Şurada da var
labels.listAll()
Collect every label into one array
listAll(options?: ListOptions): Promise<Array<LabelResource>>Walks every page of list and resolves with all labels, sorted by name and then by id. One request per page.
Parametreler
options.limitnumberPage 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.signalAbortSignalCancels the request in flight and the walk with it.
options.apiKeystringOverrides the client API key for every page of this walk.
Döndürür
Array<LabelResource> holding every label.
Örnek
const labels = await openemail.labels.listAll({ limit: 100 })const receipts = labels.find((label) => label.name === 'Receipts') if (receipts) { await openemail.threads.update('CAHk7pQ2x9LmZ4-mail.example.com', { addLabelIds: [receipts.id] })}Notlar
If any page fails the promise rejects and the labels already fetched are discarded.
Şurada da var
- API
GET /labels
labels.iterate()
Stream the labels one at a time
iterate(options?: ListOptions): AsyncGenerator<LabelResource, void, undefined>Returns an async generator that yields labels individually, sorted by name and then by id, and requests the next page only once the current one is drained. Nothing is fetched until you consume it, and breaking out of the loop stops the requests.
Parametreler
options.limitnumberPage 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.signalAbortSignalCancels the request in flight and the walk with it.
options.apiKeystringOverrides the client API key for every page of this walk.
Döndürür
AsyncGenerator<LabelResource, void, undefined> yielding one label per step.
Örnek
for await (const label of openemail.labels.iterate()) { if (label.threadCount === 0) console.log('unused', label.name)}Notlar
The generator is lazy, so an abandoned loop costs only the pages you consumed.
Şurada da var
- API
GET /labels
labels.listColors()
List the colours the app offers for labels
listColors(options?: RequestScope): Promise<Array<LabelColorResource>>Resolves the whole label palette as a plain array: 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.
Parametreler
options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client API key for this call only.
Döndürür
Array<LabelColorResource>, each with kind, name, value, solid, from, to and textColor.
Örnek
const colors = await openemail.labels.listColors()const sunset = colors.find((color) => color.name === 'sunset') await openemail.labels.create({ name: 'Launch', color: { backgroundColor: sunset?.value ?? '#EF4444' }})Notlar
kindissolidorgradient.fromandtoare null on a solid.
Şurada da var
labels.get()
Read one user label by id
get(id: string, options?: RequestScope): Promise<LabelResource>Looks up a single user label and returns it in the same shape as a row of list, with its colour, threadCount, 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.
Parametreler
idstringZorunluLabel id such as
USER_RECEIPTS, matched case sensitively.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client API key for this call only.
Döndürür
LabelResource with id, name, type: 'user', color, threadCount, createdAt and updatedAt.
Örnek
const label = await openemail.labels.get('USER_RECEIPTS') console.log(label.name, label.color?.backgroundColor ?? 'no colour', label.threadCount)Notlar
A missing label throws
OpenEmailApiErrorwithisNotFoundtrue and coderesource_not_found.
Şurada da var
labels.create()
Create a user label
create(body: LabelInput, options?: RequestScope): Promise<LabelResource>Creates a label and resolves with 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. 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.
Parametreler
body.namestringZorunluDisplay name, trimmed, 1 to 225 characters. Also decides the id.
body.colorLabelColorInputThe colour. Leave it out for a label with no colour.
body.color.backgroundColorstringA hex colour such as
#3B82F6or a gradient token such asgradient:sunset, at most 32 characters. Required oncecoloris given.body.color.textColorstringAccepted and ignored. The ink is worked out from
backgroundColor.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client API key for this call only.
Döndürür
LabelResource with the new id, the trimmed name, color, threadCount of 0, createdAt and updatedAt.
Örnek
const label = await openemail.labels.create({ name: 'Big Clients', color: { backgroundColor: 'gradient:aurora' }}) console.log(label.id, label.color?.textColor)Notlar
The SDK does not retry a create after a network failure. If you retry by hand after a lost response, a 409
label_name_takenmeans the first attempt succeeded.
Şurada da var
labels.update()
Rename or recolour a user label
update(id: string, patch: LabelPatch, options?: RequestScope): Promise<LabelResource>Renames a label, recolours it, or both, and resolves with it as it is stored. Send name, color or both: a field left out stays as it is, and a patch with neither 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 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.
Parametreler
idstringZorunluLabel id such as
USER_RECEIPTS.patch.namestringNew display name, trimmed, 1 to 225 characters. Left out, the name stays.
patch.colorLabelColorInput | nullNew colour.
nullclears it, and leaving it out keeps the stored colour.patch.color.backgroundColorstringA hex colour or a gradient token, at most 32 characters. An empty string clears the colour.
patch.color.textColorstringAccepted and ignored. The ink is worked out from
backgroundColor.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client API key for this call only.
Döndürür
LabelResource with the unchanged id and the new name and color.
Örnek
const saved = await openemail.labels.update('USER_RECEIPTS', { color: { backgroundColor: '#EA9602' }}) console.log(saved.id, saved.name, saved.color?.backgroundColor)Notlar
The SDK retries this call after a network failure, since the same patch sent twice leaves the same label.
Şurada da var
labels.delete()
Delete a user label and remove it from every thread
delete(id: string, options?: RequestScope): Promise<DeletedLabelResource>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.
Parametreler
idstringZorunluLabel id such as
USER_OLD_PROJECT.options.signalAbortSignalCancels the request.
options.apiKeystringOverrides the client API key for this call only.
Döndürür
DeletedLabelResource, { object: 'label', id, deleted: true }.
Örnek
const removed = await openemail.labels.delete('USER_OLD_PROJECT') console.log(removed.id, removed.deleted)Notlar
The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.
getfirst if you want to say how many conversations will lose the label: itsthreadCountis that number.