Kontaktet
Çdo veprim në këtë grup: çfarë pranon, çfarë kthen dhe gabimet me të cilat mund të përgjigjet.
Veprimet
The address book, and it belongs to the workspace rather than to whoever saved a row. Every member and every key on the workspace reads and writes the same book.
A contact is addressed by its email address on every route here, because no id is exposed. Two things write rows: somebody saving one, in the app or through this API, which lands as manual, and a member sending mail from the app composer, which lands as auto. Mail ARRIVING from an address creates nothing, so an empty book on a busy mailbox is the expected state rather than a fault.
GET/contacts
List contacts
The address book belongs to the workspace, so every key on it reads the same rows and a contact saved by one member is visible to the rest.
Most recently seen first, with contacts that have never been mailed last. source is manual for an address somebody saved, in the app or through this API, and auto for one recorded because a member sent mail to it from the composer. Mail arriving from an address creates no contact.
Paging is keyset. Pass nextCursor back as cursor while hasMore is true.
Requires the contacts:read scope.
Parametrat e pyetjes
limitintegerRows per page, a whole number from 1 to 200. The server defaults to 50.
Të paktën 1Më së shumti 200Parazgjedhja50cursorstringThe
nextCursorfrom the previous page. Never build one yourself.sourcestringNarrows the page to contacts recorded that way.
Një nga"manual""auto""form"qstringSearches the name and the address. When nothing matches exactly on the first page, close spellings are returned instead, and the pages that follow keep matching the same way.
Deri në 200 karaktere
Kthen
Contacts in this workspace.
Gabimet
Gabimet që mund të kthejë çdo veprim400401403404422500Katalogu i gabimeve
E disponueshme edhe në
POST/contacts
Create a contact
The address is the identity, so there is no id to choose and no id in the response. It is trimmed and lower cased before it is stored, and the contact is saved with source set to manual.
The new contact joins the built-in default audience as it is written, and any audience named in audienceIds alongside it. Naming audiences also requires the audiences:write scope.
An address already in the book is refused rather than merged, so a retry cannot overwrite a name somebody edited in the app.
Requires the contacts:write scope.
Trupi i kërkesës
emailstringE detyrueshmeTrimmed and lower cased before it is stored.
Deri në 320 karaktereFormatiemailnamestringDisplay name. Leave it out to save the contact without one.
Mund të jetë nullDeri në 200 karakterenotesstringFree text kept with the contact and shown beside it in the app.
Mund të jetë nullDeri në 5000 karaktereaudienceIdsstring[]Audiences to put the new contact in. The default audience is joined whether or not it is named here. Sending this also requires the
audiences:writescope.Deri në 25 elemente
Kthen
Created.
Gabimet
- 409
contact_exists: that address is already in this workspace book. PATCH it instead.
Gabimet që mund të kthejë çdo veprim400401403404422500Katalogu i gabimeve
E disponueshme edhe në
GET/contacts/people
List people
Everyone on the Contacts page in the app: the saved contacts, and every address seen in mail as the sender or a recipient of a thread's newest message, with the number of threads and when mail last moved. A person seen in mail and saved is one row.
The addresses seen in mail are listed only when the key also holds threads:read, because they are read out of the mail. Without it the rows are the saved contacts alone and seen is false. A key limited to particular addresses or domains gets the saved contacts alone too, with seen false, even when it holds threads:read, because the other addresses would be read out of the mail of every address in the workspace. Deleted addresses and the mailbox's own addresses are left out.
blockedBy names the workspace blocklist rule that blocks a row, the same rule blocked=true filters on.
Requires the contacts:read scope.
Parametrat e pyetjes
limitintegerRows per page, 1 to 100.
Të paktën 1Më së shumti 100Parazgjedhja25cursorstringAn opaque cursor from the previous page, with the same
sort,qandblocked. Keyset, not offset: pass the previous page'snextCursor. One that names nothing in this list is a 400invalid_cursor.sortstringrecentputs the newest mail first, then saved contacts never seen in mail.namegoes by name, or by address where there is none, ignoring case.threadsputs the people with the most threads first.Një nga"recent""name""threads"Parazgjedhja"recent"qstringSearches names, addresses and notes, with close spellings when nothing matches exactly.
Deri në 200 karaktereemailstringOne address only, matched case insensitively: the way to read one person's thread count and last mail.
Deri në 320 karaktereblockedstringtruefor only the people the workspace blocklist blocks, whole-domain rules included.Një nga"true""false"
Kthen
A page of people.
Gabimet
Gabimet që mund të kthejë çdo veprim400401403404422500Katalogu i gabimeve
E disponueshme edhe në
POST/contacts/batch-delete
Delete contacts in bulk
Deletes up to 200 addresses in one call, each the way DELETE /contacts/{email} deletes one: a saved contact goes with its notes, photo and audience memberships, and every address is hidden, so a send does not record it again. Addresses that were only seen in mail are hidden too. An entry that is not an address comes back in invalid and the rest still go through.
Requires the contacts:write scope.
Trupi i kërkesës
emailsstring[]E detyrueshmeAddresses, matched case insensitively. A repeated address counts once.
Nga 1 deri në 200 elemente
Kthen
What was deleted.
Gabimet
Gabimet që mund të kthejë çdo veprim400401403404422500Katalogu i gabimeve
E disponueshme edhe në
GET/contacts/{email}
Retrieve a contact
The book is the workspace's. The address is matched case insensitively, and it is a path segment, so URL encode it: [email protected] travels as grace%40example.com.
A 404 means only that the address is not in the book. It says nothing about whether mail has been exchanged with it.
Requires the contacts:read scope.
Parametrat e shtegut
emailstringE detyrueshmeThe contact's address, matched case insensitively.
Kthen
The contact.
Gabimet
Gabimet që mund të kthejë çdo veprim400401403404422500Katalogu i gabimeve
E disponueshme edhe në
PATCH/contacts/{email}
Update a contact
A partial update, never an upsert. An address not in the book is a 404.
The address itself cannot be changed: it is the identity and the path segment, so moving a contact to a new address is a delete and a create. source and lastSeenAt are the server's and are not accepted here.
Requires the contacts:write scope.
Parametrat e shtegut
emailstringE detyrueshmeThe contact's address, matched case insensitively.
Trupi i kërkesës
namestringNew display name. Null clears it.
Mund të jetë nullDeri në 200 karakterenotesstringNew notes. Null clears them.
Mund të jetë nullDeri në 5000 karaktere
Kthen
Saved.
Gabimet
Gabimet që mund të kthejë çdo veprim400401403404422500Katalogu i gabimeve
E disponueshme edhe në
PUT/contacts/{email}
Save a contact
Saves the address the way Add to contacts and Keep in contacts do in the app. An address that is not a contact yet becomes one, answered with 201. One recorded from a send becomes manual, and one already saved keeps what it has, answered with 200. A deleted address is brought back. The body is optional.
Requires the contacts:write scope.
Parametrat e shtegut
emailstringE detyrueshmeThe address, trimmed and lower cased on the server.
Trupi i kërkesës
namestringUp to 200 characters. Left out, the stored name is kept.
Deri në 200 karakterenotesstringUp to 5,000 characters.
nullclears the notes; left out, they are kept.Mund të jetë nullDeri në 5000 karaktere
Kthen
Already a contact, now kept as manual.
Saved as a new contact.
Gabimet
- 422
unknown_parameterfor any key butnameandnotes.
Gabimet që mund të kthejë çdo veprim400401403404500Katalogu i gabimeve
E disponueshme edhe në
DELETE/contacts/{email}
Delete a contact
Deletes somebody from the contacts the way Delete does in the app. A saved contact goes with its notes, its photo and every audience membership, the built-in default one included. The address is then hidden: it leaves GET /contacts/people, and mail sent to it from the app composer no longer records it. The address can be one that was only ever seen in mail.
No mail moves. Saving the address again, with POST /contacts or PUT /contacts/{email}, brings it back as a new contact.
Requires the contacts:write scope.
Parametrat e shtegut
emailstringE detyrueshmeThe contact's address, matched case insensitively.
Kthen
Deleted and hidden.
Gabimet
- 422
invalid_contactwhen the path is not an address.
Gabimet që mund të kthejë çdo veprim400401403404500Katalogu i gabimeve
E disponueshme edhe në
PUT/contacts/{email}/photo
Set a contact photo
Uploads the photo shown for the contact, replacing any there was. Send the image itself as the body, not JSON, with its type in Content-Type: image/png, image/jpeg, image/webp, image/gif. Up to 5 MB goes in. It is fitted into a 512 pixel square and stored as WebP, and an animated image keeps its first frame.
The address has to be a saved contact: save it with PUT /contacts/{email} first.
Requires the contacts:write scope.
Parametrat e shtegut
emailstringE detyrueshmeThe contact's address, matched case insensitively.
Trupi i kërkesës
Lloji i përmbajtjesimage/png, image/jpeg, image/webp, image/gif
Kthen
The contact, with its new photoUrl.
Gabimet
- 404
contact_not_foundonemail: the address is not a saved contact.- 422
invalid_imagewhen the body is not an image of an accepted type, is too large or cannot be read.- 502
image_not_stored: the image was read but could not be stored. Try again.- 503
image_busy: the image service is saturated. Try again shortly.
Gabimet që mund të kthejë çdo veprim400401403500Katalogu i gabimeve
E disponueshme edhe në
DELETE/contacts/{email}/photo
Remove a contact photo
Removes the contact photo and deletes the stored image. Removing a photo from a contact that has none changes nothing.
Requires the contacts:write scope.
Parametrat e shtegut
emailstringE detyrueshmeThe contact's address, matched case insensitively.
Kthen
The contact, with photoUrl null.
Gabimet
- 404
contact_not_foundonemail: the address is not a saved contact.
Gabimet që mund të kthejë çdo veprim400401403422500Katalogu i gabimeve
E disponueshme edhe në
POST/contacts/{email}/block
Block a contact
Puts the address on the workspace blocklist, the one PATCH /settings edits as blockedSenders, so mail from it is refused from then on. A plus tag is dropped: blocking [email protected] blocks [email protected]. When a rule already blocks the address, a whole-domain one included, nothing is added and created is false. The address does not have to be a contact.
It needs settings:write, because it writes the blocklist rather than the contact.
Requires the settings:write scope.
Parametrat e shtegut
emailstringE detyrueshmeThe address to block.
Kthen
Blocked.
Gabimet
- 422
invalid_contactwhen the path is not an address,blocklist_entry_too_broadwhen it has fewer than two letters or numbers, or the narrowed-key refusal.capability_unsupportedonaddressAllowlist: the blocklist belongs to the whole workspace and filters the mail of every address in it, so a key limited to particular addresses or domains cannot change it. Use a key with no address or domain restriction.
Gabimet që mund të kthejë çdo veprim400401403404500Katalogu i gabimeve
E disponueshme edhe në
DELETE/contacts/{email}/block
Unblock a contact
Takes every workspace blocklist rule that blocks the address off the list, and lists them in removed. When one is a whole-domain rule, everybody at that domain is unblocked with it. Rules set for one address or one domain in the settings are not touched. An address no rule blocks answers with removed empty.
Requires the settings:write scope.
Parametrat e shtegut
emailstringE detyrueshmeThe address to unblock.
Kthen
Unblocked.
Gabimet
- 422
invalid_contactwhen the path is not an address, or the narrowed-key refusal.capability_unsupportedonaddressAllowlist: the blocklist belongs to the whole workspace and filters the mail of every address in it, so a key limited to particular addresses or domains cannot change it. Use a key with no address or domain restriction.
Gabimet që mund të kthejë çdo veprim400401403404500Katalogu i gabimeve
E disponueshme edhe në
GET/contacts/{email}/threads
List conversations with a contact
Every thread the address wrote or was written to, in every folder, the Mail tab on a contact in the app. The address does not have to be a saved contact. Each row is a summary of the thread; GET /threads/{id} reads the messages.
Requires the threads:read scope.
Parametrat e shtegut
emailstringE detyrueshmeThe address. It does not have to be a saved contact.
Parametrat e pyetjes
limitintegerThreads per page, 1 to 100.
Të paktën 1Më së shumti 100Parazgjedhja25cursorstringThe previous page's
nextCursor, with the sameqandsort.qstringSearches inside those threads, with the same syntax as the mailbox search.
Deri në 200 karakteresortstringnewest(the default),oldest,senderorsubject.Një nga"newest""oldest""sender""subject"Parazgjedhja"newest"
Kthen
A page of threads.
Gabimet
- 422
invalid_contactwhen the path is not an address, or the narrowed-key refusal.capability_unsupportedonaddressAllowlist: a contact's threads and activity are read from the mail of every address in the workspace, so a key limited to particular addresses or domains cannot read them. Use a key with no address or domain restriction.
Gabimet që mund të kthejë çdo veprim400401403404500Katalogu i gabimeve
E disponueshme edhe në
GET/contacts/{email}/activity
Read activity with a contact
The Activity tab on a contact in the app: messages received from the address and sent to it, per bucket, over a window that ends now, with the threads that moved, the threads waiting on a reply from the mailbox, and the median time each side takes to answer. Mail in the bin or in spam is left out.
Requires the threads:read scope.
Parametrat e shtegut
emailstringE detyrueshmeThe address. It does not have to be a saved contact.
Parametrat e pyetjes
minutesintegerHow far back the window reaches from now. The default is 90 days.
Të paktën 1Më së shumti 10540800Parazgjedhja129600grainstringBucket width:
minute,hourorday, defaulting today.Një nga"minute""hour""day"Parazgjedhja"day"offsetMinutesintegerThe reader's offset from UTC in minutes, so that a day bucket falls on their calendar.
Të paktën -840Më së shumti 840Parazgjedhja0
Kthen
The activity.
Gabimet
- 422
invalid_contactwhen the path is not an address, or the narrowed-key refusal.capability_unsupportedonaddressAllowlist: a contact's threads and activity are read from the mail of every address in the workspace, so a key limited to particular addresses or domains cannot read them. Use a key with no address or domain restriction.
Gabimet që mund të kthejë çdo veprim400401403404500Katalogu i gabimeve
E disponueshme edhe në
PUT/contacts/{email}/audiences
Set a contact's audiences
Sets exactly which audiences the contact is in, the way the audience picker on a contact does in the app. The contact joins every listed audience it is not in yet and leaves every other one, in one transaction. The built-in default audience is always kept, so { "audienceIds": [] } leaves the contact in the default audience alone. Memberships it keeps also keep their addedAt.
The address is matched case insensitively and has to be a contact already. Create it with POST /contacts, which takes audienceIds too. An id that names no audience in this workspace refuses the whole call and changes nothing.
audiences:write is the only scope checked, because this writes memberships rather than the contact. Sending the same list again changes nothing, so a retry is safe.
Requires the audiences:write scope.
Parametrat e shtegut
emailstringE detyrueshmeThe contact's address, matched case insensitively.
Trupi i kërkesës
audienceIdsstring[]E detyrueshmeEvery audience the contact should be in once the call returns, up to 100. The default audience is kept whether or not it is named, so an empty array leaves only the default one. A repeated id counts once.
Deri në 100 elemente
Kthen
The contact, with the audiences it is in after the change.
Gabimet
- 404
contact_not_foundonemailwhen the address is not in the workspace book, oraudience_not_foundonaudienceIdswhen an id names no audience here. Nothing is changed.- 422
invalid_parameteronaudienceIdsfor more than 100 ids, and on the entry, such asaudienceIds.0, for an empty one,unknown_parameterfor any other key in the body.
Gabimet që mund të kthejë çdo veprim400401403500Katalogu i gabimeve
E disponueshme edhe në
Objektet
Contactobject
objectstring- Një nga
"contact" emailstringTrimmed and lower cased on write. This is the key every contact route takes, because no contact id is exposed.
namestring- Mund të jetë null
sourcestringautowhen a send from the app composer recorded the address,manualwhen somebody saved it here or in the app. A recorded send never downgrades amanualcontact toauto.Një nga"manual""auto""form"notesstring- Mund të jetë null
photoUrlstringWhere the contact photo is served, or null when the contact has none. Set it with
PUT /contacts/{email}/photo. A new upload gets a new URL.Mund të jetë nulllastSeenAtstringWhen mail last went to this address from the app composer. Null until it does.
Mund të jetë nullFormatidate-timecreatedAtstring- Formati
date-time updatedAtstring- Formati
date-time
ContactActivityobject
objectstring- Një nga
"contact_activity" emailstringsincestringThe start of the first bucket, on the boundary
grainandoffsetMinutesput it.Formatidate-timeuntilstring- Formati
date-time grainstring- Një nga
"minute""hour""day" bucketsobject[]Only the buckets with mail in them, oldest first.
bucketstringThe bucket in the reader's time:
2026-09-23,2026-09-23T14or2026-09-23T14:05.receivedintegerMessages from this address.
sentintegerMessages from the mailbox to this address.
totalsobjectreceivedintegersentintegerthreadsintegerThreads with at least one message in the window.
waitingintegerThreads whose newest message is from this address, so the mailbox owes the reply.
lastReceivedAtstring- Mund të jetë nullFormati
date-time lastSentAtstring- Mund të jetë nullFormati
date-time
replyTimeobjectyoursnumberMedian milliseconds the mailbox took to answer, or null without a reply to measure.
Mund të jetë nulltheirsnumberMedian milliseconds this address took to answer.
Mund të jetë null
ContactBatchDeleteobject
objectstring- Një nga
"contact_batch_delete" deletedintegerAddresses deleted and hidden, saved or not.
savedintegerOf those, how many were saved contacts.
invalidstring[]Entries that are not addresses, lower cased. Nothing happened to them.
ContactBlockobject
objectstring- Një nga
"contact_block" emailstringThe address as the blocklist sees it: lower cased, with any plus tag dropped.
blockedbooleanblockedByobjectOn a block, the rule that now blocks the address.
Mund të jetë nullrulestringThe entry on the workspace blocklist that matches this address, exactly as it is stored.
liststringblockedSendersfor an address or pattern rule,blockedDomainsfor a rule that blocks a whole domain and every subdomain under it.Një nga"blockedSenders""blockedDomains"
createdbooleanOn a block, false when a rule already blocked the address and nothing was added.
removedobject[]On an unblock, every rule taken off the workspace blocklist. A
blockedDomainsentry here unblocked the whole domain.rulestringThe entry on the workspace blocklist that matches this address, exactly as it is stored.
liststringblockedSendersfor an address or pattern rule,blockedDomainsfor a rule that blocks a whole domain and every subdomain under it.Një nga"blockedSenders""blockedDomains"
ContactDetailobject
objectstring- Një nga
"contact" emailstringTrimmed and lower cased on write. This is the key every contact route takes, because no contact id is exposed.
namestring- Mund të jetë null
sourcestringautowhen a send from the app composer recorded the address,manualwhen somebody saved it here or in the app. A recorded send never downgrades amanualcontact toauto.Një nga"manual""auto""form"notesstring- Mund të jetë null
photoUrlstringWhere the contact photo is served, or null when the contact has none. Set it with
PUT /contacts/{email}/photo. A new upload gets a new URL.Mund të jetë nulllastSeenAtstringWhen mail last went to this address from the app composer. Null until it does.
Mund të jetë nullFormatidate-timecreatedAtstring- Formati
date-time updatedAtstring- Formati
date-time audiencesobject[]Every audience this contact is in, the built-in default one included. Single-contact responses carry it; the list route does not.
idstringThe audience handle,
aud_plus 24 hex.namestringbuiltinstringdefaulton the one audience every contact joins, null on an audience somebody created.Mund të jetë nullNjë nga"default"
ContactListobject
objectstring- Një nga
"list" dataContact[]hasMorebooleannextCursorstring- Mund të jetë null
ContactThreadobject
objectstring- Një nga
"thread" idstringThe id
GET /threads/{id}takes.subjectstring- Mund të jetë null
fromobjectWho sent the newest message.
Mund të jetë nullnamestring- Mund të jetë null
emailstring
receivedAtstringWhen the newest message arrived or went out.
Mund të jetë nullmessageCountintegerhasUnreadbooleanlabelsobject[]idstringnamestring
ContactThreadListobject
objectstring- Një nga
"list" dataContactThread[]hasMorebooleanTrue when another page follows. Pass
nextCursorback ascursorto read it.nextCursorstringOpaque. Pass it back as
cursorfor the next page, and never build one yourself.Mund të jetë null
DeletedContactobject
objectstring- Një nga
"contact" emailstringdeletedboolean- Një nga
true wasSavedbooleanTrue when a saved contact was removed, false when the address was only seen in mail and has now been hidden.
Personobject
objectstring- Një nga
"person" emailstringLower cased. The key every contact route takes.
displayEmailstringThe address as the most recent message wrote it, which may carry capitals.
namestringThe saved name, or else the newest display name seen in mail.
Mund të jetë nullsavedbooleanTrue when the address is a saved contact.
sourcestringAs on a contact, or null when the address is only seen in mail.
Mund të jetë nullNjë nga"manual""auto""form"notesstring- Mund të jetë null
photoUrlstring- Mund të jetë null
threadsintegerHow many threads have this address as the sender or a recipient of their newest message. Null when the key does not read mail or the address has never been seen in it.
Mund të jetë nulllastAtstringWhen the newest of those threads last moved. Null for a saved contact never seen in mail.
Mund të jetë nullFormatidate-timecreatedAtstring- Mund të jetë nullFormati
date-time updatedAtstring- Mund të jetë nullFormati
date-time blockedByobjectThe workspace blocklist rule that blocks this address, or null when none does.
Mund të jetë nullrulestringThe entry on the workspace blocklist that matches this address, exactly as it is stored.
liststringblockedSendersfor an address or pattern rule,blockedDomainsfor a rule that blocks a whole domain and every subdomain under it.Një nga"blockedSenders""blockedDomains"
PersonListobject
objectstring- Një nga
"list" dataPerson[]hasMorebooleanTrue when another page follows. Pass
nextCursorback ascursorto read it.nextCursorstringOpaque. Pass it back as
cursorfor the next page, and never build one yourself.Mund të jetë nullseenbooleanTrue when the addresses seen in mail are included, which needs
threads:read. False means the rows are the saved contacts alone.