برچسب‌ها
هر عملیات در این گروه: آنچه می‌پذیرد، آنچه برمی‌گرداند و خطاهایی که ممکن است با آن‌ها پاسخ دهد.
عملیات‌ها
The names a conversation can be filed under, several at once. Labels belong to the workspace, so every member and every key sees the same set, and renaming or deleting one changes it for everybody.
A label's id comes from the name it was created with and never changes, so a rename keeps every conversation labelled. Its colour is a hex value or one of seven gradient tokens, and GET /labels/colors lists the palette the app offers. Apply and remove labels on a conversation with PATCH /threads/{id}. GET /threads?folder=USER_BIG_CLIENTS lists every conversation carrying a label, and labelIds narrows a folder to the ones carrying it.
GET/labels
List labels
Every user label in the workspace, sorted by name and then by id, a page at a time: follow nextCursor while hasMore is true to read them all. Each row carries its colour, how many conversations carry it and when it was created and last changed, 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 PATCH /threads/{id} takes them, but they cannot be renamed, recoloured or deleted.
The order the app's sidebar shows is each person's own arrangement and is not exposed here.
Requires the labels:read scope.
پارامترهای کوئری
limitintegerRows per page, 1 to 100.
دست‌کم 1حداکثر 100پیش‌فرض25cursorstringThe previous page's
nextCursor, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400invalid_cursor.
خروجی
A page of labels, by name.
خطاها
خطاهایی که هر عملیاتی ممکن است برگرداند400401403404422500فهرست خطاها
همچنین در دسترس در
POST/labels
Create a label
Creates a label and answers with it. The id comes from the name (Big Clients becomes USER_BIG_CLIENTS) and never changes afterwards. A workspace holds at most 50 labels.
Leave color out for a label with no colour, or send color.backgroundColor as a hex value or a gradient token. GET /labels/colors lists the swatches the app offers.
Requires the labels:write scope.
بدنهٔ درخواست
namestringالزامیTrimmed, then 1 to 225 characters. Also decides the id, which never changes afterwards.
1 تا 225 نویسهcolorLabelColorInputThe colour. Leave it out for a label with no colour.
خروجی
Created, read back as it is stored.
خطاها
- 409
label_name_taken: another label already has that name, compared without case, or already holds the id this name gives because it was created under it and renamed since.- 422
label_limit_reachedonce the workspace holds 50 labels, orinvalid_parameterfor a colour that is neither a hex value nor a gradient token.
خطاهایی که هر عملیاتی ممکن است برگرداند400401403404500فهرست خطاها
همچنین در دسترس در
GET/labels/colors
List label colours
The fourteen solid colours and seven gradients the app offers when you make or edit a label, in the order it shows them. Each one says what to send as color.backgroundColor, the ink drawn on it, and for a gradient the colour at each end and one solid hex for places a gradient cannot go.
A fixed catalogue with no paging. Fetch it once and keep it. A label may also carry any other hex, set through this API, which the app keeps and offers back as its own swatch.
Requires the labels:read scope.
خروجی
The whole palette.
خطاها
خطاهایی که هر عملیاتی ممکن است برگرداند400401403404422500فهرست خطاها
همچنین در دسترس در
GET/labels/{id}
Retrieve a label
One label by id, in the same shape as a row of the list. Ids are matched exactly, and a system id such as INBOX is a 404.
Requires the labels:read scope.
پارامترهای مسیر
idstringالزامیLabel id such as
USER_RECEIPTS, matched case sensitively.
خروجی
The label.
خطاها
خطاهایی که هر عملیاتی ممکن است برگرداند400401403404422500فهرست خطاها
همچنین در دسترس در
PATCH/labels/{id}
Rename or recolour a label
Renames a label, recolours it, or both. Send name, color or both; a field left out stays as it is, and color: null or an empty backgroundColor clears the colour. The id never changes, so every conversation keeps the label through a rename.
Requires the labels:write scope.
پارامترهای مسیر
idstringالزامیLabel id such as
USER_RECEIPTS.
بدنهٔ درخواست
namestringThe new name, trimmed, 1 to 225 characters. Left out, the name stays.
1 تا 225 نویسهcolorobjectThe new colour.
nullclears it. Left out, the colour stays.می‌تواند null باشدbackgroundColorstringالزامیA hex colour (
#RGB,#RGBA,#RRGGBBor#RRGGBBAA), stored upper-cased, or a gradient token:gradient:sunset,gradient:ember,gradient:meadow,gradient:lagoon,gradient:aurora,gradient:berry,gradient:midnight. The app's solid swatches are#EF4444,#F97316,#EA9602,#DCB30B,#79BB19,#2EB45C,#00AD9B,#09A9CA,#3B82F6,#6366F1,#8B5CF6,#D946EF,#EC4899,#64748B, and any other hex is kept as it is. An empty string means no colour. Anything else is a 422invalid_parameteroncolor.backgroundColor.تا 32 نویسهtextColorstringAccepted and ignored. The ink is worked out from
backgroundColor.تا 32 نویسه
خروجی
Saved, read back as it is stored.
خطاها
- 409
label_name_taken: another label already has that name, compared without case.- 422
invalid_parameterfor a body with neithernamenorcolor, or a colour that is neither a hex value nor a gradient token.
خطاهایی که هر عملیاتی ممکن است برگرداند400401403404500فهرست خطاها
همچنین در دسترس در
DELETE/labels/{id}
Delete a label
Deletes the label and takes it off every conversation that carried it, in one step. The conversations stay in whatever folder they were in. There is no undo: creating the same name again gives the same id, but the conversations do not get the label back.
Requires the labels:write scope.
پارامترهای مسیر
idstringالزامیLabel id such as
USER_OLD_PROJECT.
خروجی
Deleted.
خطاها
خطاهایی که هر عملیاتی ممکن است برگرداند400401403404422500فهرست خطاها
همچنین در دسترس در
اشیا
DeletedLabelobject
objectstring- یکی از
"label" idstringdeletedboolean- یکی از
true
Labelobject
objectstring- یکی از
"label" idstringFixed when the label is created:
USER_and the name upper-cased, with each run of spaces turned into_, soBig ClientsisUSER_BIG_CLIENTS. It never changes, so a renamed label keeps the id of its first name. Store the id rather than the name.namestringtypestringAlways
user. System labels such asINBOX,STARREDandUNREADare never listed, though a thread carries them andPATCH /threads/{id}takes them.یکی از"user"colorobjectHow the label is painted. Null on a label saved with no colour.
می‌تواند null باشدbackgroundColorstringThe stored colour: a hex value such as
#3B82F6, stored upper-cased, or a gradient token such asgradient:sunset.GET /labels/colorslists the palette the app offers, with the two ends of every gradient.textColorstringThe ink the app draws on that colour,
#18181Bor#FFFFFF. Worked out here frombackgroundColorand never stored, so atextColoryou sent is not echoed.
threadCountintegerConversations carrying the label now, the number the Labels table in the app shows. A key limited to particular addresses counts only conversations delivered to them.
createdAtstringNull on a label made before these times were recorded.
می‌تواند null باشدقالبdate-timeupdatedAtstringThe last rename or recolour. Null on a label made before these times were recorded.
می‌تواند null باشدقالبdate-time
LabelColorEntryobject
objectstring- یکی از
"label_color" kindstring- یکی از
"solid""gradient" namestringThe swatch name, such as
redorsunset.valuestringWhat to send as
color.backgroundColorto use this swatch.یکی از"#EF4444""#F97316""#EA9602""#DCB30B""#79BB19""#2EB45C""#00AD9B""#09A9CA""#3B82F6""#6366F1""#8B5CF6""#D946EF""#EC4899""#64748B""gradient:sunset""gradient:ember""gradient:meadow""gradient:lagoon""gradient:aurora""gradient:berry""gradient:midnight"solidstringOne hex for places a gradient cannot be drawn, such as an icon. The same as
valueon a solid.fromstringWhere a gradient starts, drawn at 135 degrees. Null on a solid.
می‌تواند null باشدtostringWhere a gradient ends. Null on a solid.
می‌تواند null باشدtextColorstringThe ink the app draws on this swatch.
LabelColorInputobject
backgroundColorstringالزامیA hex colour (
#RGB,#RGBA,#RRGGBBor#RRGGBBAA), stored upper-cased, or a gradient token:gradient:sunset,gradient:ember,gradient:meadow,gradient:lagoon,gradient:aurora,gradient:berry,gradient:midnight. The app's solid swatches are#EF4444,#F97316,#EA9602,#DCB30B,#79BB19,#2EB45C,#00AD9B,#09A9CA,#3B82F6,#6366F1,#8B5CF6,#D946EF,#EC4899,#64748B, and any other hex is kept as it is. An empty string means no colour. Anything else is a 422invalid_parameteroncolor.backgroundColor.تا 32 نویسهtextColorstringAccepted and ignored. The ink is worked out from
backgroundColor.تا 32 نویسه
LabelColorListobject
objectstring- یکی از
"list"
LabelListobject
objectstring- یکی از
"list" dataLabel[]hasMorebooleanTrue when another page follows. Pass
nextCursorback ascursorto read it.nextCursorstringAn opaque cursor for the next page, or null on the last page. Pass it back unchanged.
می‌تواند null باشد