client.contacts()
هر متد در این فضای نام: امضا، پارامترها، آنچه برمی‌گرداند و یک نمونه.
متدها
The workspace address book: the contacts somebody saved and the ones the app composer recorded, everyone seen in mail beside them, and for each person their audiences, photo, blocking, conversations and activity.
contacts().list
List the workspace contacts, most recently seen first
Page list(RequestOptions options)Returns one page of the workspace address book, ordered by lastSeenAt with the most recent first and contacts that have never been mailed last. source says where a row came from: manual for a contact somebody saved, in the app or through contacts().create, and auto for an address recorded when a member sent mail to it from the app composer. A saved contact stays manual when it is mailed later.
source narrows the page to one origin, so RequestOptions.of("source", "manual") is the contacts somebody saved on purpose and RequestOptions.of("source", "auto") the ones the composer recorded. q searches the name and the address.
This lists saved contacts only. contacts().listPeople lists everyone the Contacts page in the app shows, the addresses seen in mail included, with thread counts.
Paging is keyset. limit takes 1 to 200 and defaults to 50, and nextCursor goes back as cursor while hasMore is true. Never build a cursor yourself.
Contacts belong to the whole workspace rather than to any one address, so a key limited to particular addresses or domains reads and writes the same book as every other key. An app connected by a member who reaches only some addresses is refused with 422 capability_unsupported on addressAllowlist, on every contacts, audiences and broadcasts route.
پارامترها
options.limitintRows per page, a whole number from 1 to 200. The server defaults to 50.
options.cursorStringThe
nextCursorfrom the previous page. Never build one yourself.options.sourceStringmanual,autoorform. Leave it out for the whole book.options.qStringSearches the name and the address, up to 200 characters. When nothing matches exactly on the first page, close spellings are returned instead, and the pages that follow keep matching the same way.
options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A Page of contact maps, with items, hasMore and nextCursor. Each contact has email, name, source, notes, photoUrl and lastSeenAt.
نمونه
Page saved = client.contacts().list(RequestOptions.create().set("source", "manual").limit(200)); for (Map<String, Object> contact : saved) { System.out.println(contact.get("name") + " " + contact.get("email"));} if (saved.hasMore()) { System.out.println("Next page: " + saved.nextCursor());}نکته‌ها
Mail sent through this API adds no contacts. Only sends from the app composer record recipients, and
contacts().createis the way to add one deliberately.Every member of the workspace reads and writes the same book, so a contact saved by one person is visible to the rest.
A contact that has never been mailed has
lastSeenAtnull and sorts last, after every contact with a date.Addresses are stored lower cased.
همچنین در دسترس در
- API
GET /contacts- TypeScript
contacts.list()- Python
contacts.list()- Ruby
contacts.list- PHP
contacts->list- Go
Contacts.List- C#
Contacts.ListAsync- CLI
openemail contacts list
contacts().listAll
Collect the whole address book into one list
List<Map<String, Object>> listAll(RequestOptions options)Follows nextCursor from page to page and returns every contact in the workspace, most recently seen first and never-mailed contacts last. It takes the same source and q filters as contacts().list.
Everything is held in memory before the call returns, and an address book grows with every recipient the composer records. Prefer contacts().iterate when you can stop early. limit sets the page size of each request, not the total.
پارامترها
options.sourceStringmanual,autoorform. Leave it out for the whole book.options.qStringSearches the name and the address, up to 200 characters. When nothing matches exactly on the first page, close spellings are returned instead, and the pages that follow keep matching the same way.
options.limitintPage size per request, from 1 to 200, defaulting to 50 on the server.
options.cursorStringA cursor from an earlier page to start after.
options.apiKeyStringOverrides the client's API key for every page of this walk.
خروجی
A list of contact maps holding every contact across all pages.
نمونه
List<Map<String, Object>> saved = client.contacts().listAll(RequestOptions.create().set("source", "manual").limit(200)); for (Map<String, Object> all : saved) { System.out.println(all.get("email") + " " + all.get("name"));}نکته‌ها
A failure on any page throws out of the whole call, and the contacts already fetched are discarded.
همچنین در دسترس در
contacts().iterate
Stream the address book one contact at a time
PagedIterable iterate(RequestOptions options)Returns a PagedIterable that yields contacts one at a time, most recently seen first, 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.sourceStringmanual,autoorform. Leave it out for the whole book.options.qStringSearches the name and the address, up to 200 characters. When nothing matches exactly on the first page, close spellings are returned instead, and the pages that follow keep matching the same way.
options.limitintPage size per request, from 1 to 200, defaulting to 50 on the server.
options.cursorStringA cursor from an earlier page to start after.
options.apiKeyStringOverrides the client's API key for every page of this walk.
خروجی
A PagedIterable that yields one contact map per step.
نمونه
for (Map<String, Object> contact : client.contacts().iterate(RequestOptions.of("source", "auto"))) { System.out.println(contact.get("lastSeenAt") + " " + contact.get("email"));}نکته‌ها
The generator is lazy, so an abandoned loop costs only the pages you consumed.
همچنین در دسترس در
- API
GET /contacts- TypeScript
contacts.iterate()- Python
contacts.iterate()- Ruby
contacts.iterate- PHP
contacts->iterate- Go
Contacts.Iterate- C#
Contacts.IterateAsync
contacts().get
Read one contact by email address
Map<String, Object> get(String email, RequestOptions options)Looks up a contact by address in the workspace address book. The address is trimmed and lower cased before the lookup, so [email protected] finds [email protected], and the SDK URL encodes it for the path.
A 404 means only that the address is not in the book. It says nothing about whether mail has been exchanged with it, since received mail never creates contacts.
پارامترها
emailStringالزامیThe contact's address, matched case insensitively.
options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map with email, name, source, notes, photoUrl and lastSeenAt, plus audiences, every audience the contact is in as a map with id, name and builtin. builtin is default on the audience every contact belongs to and null on one somebody created. A key that also holds forms:read gets signUps, what this address sent through sign-up forms, newest first and at most 20. Each is a map with id, formId, formName, status (pending or added), answers, sourceUrl, createdAt and confirmedAt.
نمونه
Map<String, Object> contact = client.contacts().get("[email protected]"); System.out.println(contact.get("name") + " " + contact.get("notes"));نکته‌ها
nameis null for an address recorded automatically without a display name, andnotesis free text somebody set in the app or throughcontacts().update.The address is the contact's identity here and on every other contacts route. There is no id in the public contract.
همچنین در دسترس در
- API
GET /contacts/{email}- TypeScript
contacts.get()- Python
contacts.get()- Ruby
contacts.get- PHP
contacts->get- Go
Contacts.Get- C#
Contacts.GetAsync- CLI
openemail contacts get
contacts().create
Save a contact in the workspace address book
Map<String, Object> create(Map<String, Object> body, RequestOptions options)Adds one address to the workspace address book and returns the saved row. email is trimmed and lower cased before it is stored, so [email protected] and [email protected] are the same contact.
The contact is saved with source set to manual, the same value a contact typed into the app carries, and it joins the default audience as it is written. Every contact is in that audience for as long as it exists, so there is nothing to add afterwards. Name audiences of your own in audienceIds to put it in them in the same call, or add it later with audiences().addContact. Sending audienceIds also requires the audiences:write scope, since it writes memberships as well as a contact.
An address can be in the book once. A second create for an address that is already there is refused with 409 contact_exists rather than merged, so a retry cannot quietly overwrite a name somebody edited in the app. Read the existing row with contacts().get and change it with contacts().update.
پارامترها
body.emailStringالزامیThe address to save, trimmed and lower cased before it is stored.
body.nameString or nullDisplay name. Leave it out to save the contact without one.
body.notesString or nullFree text kept with the contact and shown beside it in the app.
body.audienceIdsList<String>Up to 25 audience ids to put the new contact in. The default audience is joined whether or not it is named. When this is present the key also needs
audiences:write, or the call is refused with 403 before anything is saved.options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map with email, name, source as manual, notes and lastSeenAt, which is null until mail goes to the address from the app composer, plus audiences, every audience the contact is now in, the default one included.
نمونه
Map<String, Object> contact = client.contacts().create(Body.of( "email", "[email protected]", "name", "Grace Hopper", "notes", "Met at the compiler workshop")); System.out.println(contact.get("email") + " " + contact.get("source"));نکته‌ها
The SDK does not retry a create after a network failure. If you retry by hand after a lost response, a 409
contact_existsmeans the first attempt landed.Contacts belong to the workspace, so the contact this creates is the one every member and every other key sees.
An id in
audienceIdsthat is not an audience of this workspace fails the whole create. Nothing is saved.
همچنین در دسترس در
contacts().update
Change a contact's name or notes
Map<String, Object> update(String email, Map<String, Object> patch, RequestOptions options)Changes the fields you send and leaves the rest alone. A key you leave out keeps its stored value, and an explicit null clears it, so Body.of("notes", null) empties the notes while an empty patch changes nothing.
The address cannot be changed. It is the contact's identity, its path segment and the unique key of the book, so moving a contact to a new address is a contacts().delete and a contacts().create, and that new contact starts with no audience membership beyond the default one.
source and lastSeenAt are the server's to set and are not accepted here. A contact recorded automatically stays auto after you give it a name.
پارامترها
emailStringالزامیThe contact's address, matched case insensitively.
patch.nameString or nullNew display name. Null clears it.
patch.notesString or nullNew notes. Null clears them.
options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map for the contact as it stands after the change, with audiences alongside it.
نمونه
Map<String, Object> contact = client.contacts().update("[email protected]", Body.of("name", "Grace Hopper", "notes", null)); System.out.println(contact.get("name") + " " + contact.get("notes"));نکته‌ها
The SDK retries this call after a network failure, since the same patch sent twice leaves the same contact.
An address that is not in the book is a 404, the same as
contacts().get.Audience membership is not touched here. Use
contacts().setAudiencesto set the whole list, oraudiences().addContactandaudiences().removeContactfor one audience.
همچنین در دسترس در
contacts().delete
Delete somebody from the contacts and hide the address
Map<String, Object> delete(String email, RequestOptions options)Does what Delete does on the Contacts page in the app. A saved contact goes with its notes, its photo and every audience it was in, the default one included. The address is then hidden: contacts().listPeople leaves it out, and mail sent to it from the app composer no longer records it as a contact. The address can be one that was only ever seen in mail, which is how you take somebody off the people list, and wasSaved says which it was.
Nothing else moves: the mail exchanged with the address stays in the mailbox, and the address can still be written to. There is no undo. contacts().create or contacts().save afterwards brings the address back as a new contact with no name, no notes and no membership beyond the default audience.
پارامترها
emailStringالزامیThe contact's address, matched case insensitively.
options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map with object set to contact, email, deleted set to true and wasSaved.
نمونه
Map<String, Object> removed = client.contacts().delete("[email protected]"); System.out.println(removed.get("email") + " " + removed.get("deleted"));نکته‌ها
An address that is not in the book is no longer a 404: it is hidden and answers with
wasSavedfalse. Something that is not an address is a 422invalid_contact.The SDK does not retry a delete, though a second attempt is harmless: it answers with
wasSavedfalse.contacts().deleteManydeletes up to 200 addresses in one call.
همچنین در دسترس در
contacts().setAudiences
Set exactly which audiences a contact is in
Map<String, Object> setAudiences(String email, Map<String, Object> body, RequestOptions options)Makes the contact's audiences match the list you send, 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, and memberships it keeps keep their addedAt.
The default audience is always kept, whether or not you name it, so Body.of("audienceIds", List.of()) leaves the contact in the default audience alone. To add or remove one audience without restating the rest, use audiences().addContact or audiences().removeContact.
The address is trimmed and lower cased, the SDK URL encodes it for the path, and it has to be a contact already: an address that is not in the book is a 404 contact_not_found on email. Create it with contacts().create, which takes audienceIds too. An id that is not an audience of this workspace is a 404 audience_not_found on audienceIds, and nothing is changed.
پارامترها
emailStringالزامیThe contact's address, matched case insensitively.
body.audienceIdsList<String>الزامیEvery audience the contact should be in, up to 100 ids. A repeated id counts once. More than 100 is a 422
invalid_parameteronaudienceIds, and an empty id is the same error on that entry, such asaudienceIds.0.options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map for the contact as it stands after the change, with audiences, every audience the contact is now in as a map with id, name and builtin, the default one included.
نمونه
Map<String, Object> contact = client.contacts().setAudiences("[email protected]", Body.of( "audienceIds", List.of("aud_9f2c4b7e1a0d63d84c5f2e7b", "aud_1c4e7a9b2d0f36e85a7c1b4d"))); System.out.println(contact.get("audiences"));نکته‌ها
audiences:writeis the only scope checked, because this writes memberships rather than the contact.Safe to replay: sending the same list again changes nothing. The SDK retries it after a network failure.
Read the current list with
contacts().getfirst when you mean to add one audience to what the contact already has, or useaudiences().addContact.
همچنین در دسترس در
contacts().listPeople
List everyone on the Contacts page, saved or seen in mail
PeoplePage listPeople(RequestOptions options)Returns one page of the people the Contacts page in the app lists: the saved contacts, and every address seen in mail as the sender or a recipient of a thread's newest message. Each row says whether it is saved, how many threads it shares with the mailbox and when mail last moved (lastAt). A person seen in mail and saved is one row. contacts().list is the saved contacts alone.
The addresses seen in mail are included only when the key also holds threads:read, because they are read out of the mail. Without it the page holds the saved contacts and seen is false. Deleted addresses and the mailbox's own addresses are never listed.
sort is recent, newest mail first and saved contacts never seen in mail after them, name, by name or else by address, ignoring case, or threads, most threads first. blockedBy on each row names the workspace blocklist rule that blocks it, and RequestOptions.of("blocked", true) narrows the page to those rows.
Paging is keyset. limit takes 1 to 100 and defaults to 25, and nextCursor goes back as cursor, with the same sort, q and blocked, while hasMore is true.
پارامترها
options.qStringSearches names, addresses and notes, up to 200 characters. When nothing matches exactly on the first page, close spellings are returned instead.
options.emailStringOne address only, matched case insensitively: the way to read one person's thread count and last mail.
options.sortStringrecent(the default),nameorthreads, also inuk.openemail.constants.PeopleSorts.options.blockedbooleantruefor only the people the workspace blocklist blocks, whole-domain rules included.options.limitintRows per page, 1 to 100. The server defaults to 25.
options.cursorStringThe
nextCursorfrom the previous page. Never build one yourself.options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A PeoplePage with items, hasMore, nextCursor and seen. Each person is a map with email, displayEmail, name, saved, source, notes, photoUrl, threads, lastAt, createdAt, updatedAt and blockedBy.
نمونه
PeoplePage page = client.contacts().listPeople(RequestOptions.create().set("sort", "threads").limit(50)); for (Map<String, Object> person : page) { System.out.println(person.get("name") + " " + person.get("email") + " " + person.get("threads"));} if (page.hasMore()) { System.out.println("Next page: " + page.nextCursor());}نکته‌ها
emailis lower cased and is what every other contacts method takes.displayEmailkeeps the capitals the newest message wrote.A malformed or stale cursor is a 400
invalid_cursor. Start again without one.A key limited to particular addresses or domains gets the saved contacts alone, with
seenfalse, even when it holdsthreads:read, because the addresses seen in mail would be read from the mail of every address in the workspace.
همچنین در دسترس در
contacts().listAllPeople
Collect everyone on the Contacts page into one list
List<Map<String, Object>> listAllPeople(RequestOptions options)Follows nextCursor from page to page and returns every person contacts().listPeople would list, in the same order and with the same filters. It is how you count the people a blocklist blocks: count(client.contacts().listAllPeople(blocked: true)).
Everything is held in memory before the call returns, and a busy mailbox has seen a great many addresses. Prefer contacts().iteratePeople when you can stop early.
پارامترها
options.qStringSearches names, addresses and notes, up to 200 characters. When nothing matches exactly on the first page, close spellings are returned instead.
options.emailStringOne address only, matched case insensitively: the way to read one person's thread count and last mail.
options.sortStringrecent(the default),nameorthreads.options.blockedbooleantruefor only the people the workspace blocklist blocks, whole-domain rules included.options.limitintPage size per request, from 1 to 100, defaulting to 25 on the server.
options.cursorStringA cursor from an earlier page to start after.
options.apiKeyStringOverrides the client's API key for every page of this walk.
خروجی
A list of person maps holding every person across all pages.
نمونه
List<Map<String, Object>> blocked = client.contacts().listAllPeople(RequestOptions.create().set("blocked", true).limit(100)); for (Map<String, Object> people : blocked) { System.out.println(people.get("email") + " " + people.get("name"));}نکته‌ها
A failure on any page throws out of the whole call, and the people already fetched are discarded.
seenis not reported here. Read one page withcontacts().listPeopleto learn whether the key reads the people seen in mail.
همچنین در دسترس در
contacts().iteratePeople
Stream everyone on the Contacts page one person at a time
PagedIterable iteratePeople(RequestOptions options)Returns a PagedIterable that yields the people contacts().listPeople lists, one at a time, 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.qStringSearches names, addresses and notes, up to 200 characters. When nothing matches exactly on the first page, close spellings are returned instead.
options.emailStringOne address only, matched case insensitively: the way to read one person's thread count and last mail.
options.sortStringrecent(the default),nameorthreads.options.blockedbooleantruefor only the people the workspace blocklist blocks, whole-domain rules included.options.limitintPage size per request, from 1 to 100, defaulting to 25 on the server.
options.cursorStringA cursor from an earlier page to start after.
options.apiKeyStringOverrides the client's API key for every page of this walk.
خروجی
A PagedIterable that yields one person map per step.
نمونه
for (Map<String, Object> person : client.contacts().iteratePeople(RequestOptions.of("sort", "recent"))) { System.out.println(person.get("saved") + " " + person.get("threads") + " " + person.get("email"));}نکته‌ها
The generator is lazy, so an abandoned loop costs only the pages you consumed.
همچنین در دسترس در
contacts().save
Save an address as a contact, or keep one that was recorded
Map<String, Object> save(String email, Map<String, Object> body, RequestOptions options)Does what Add to contacts and Keep in contacts do in the app, and is safe to call whatever state the address is in. An address that is not a contact yet becomes one with source manual. A contact recorded from a send becomes manual. A contact already saved keeps what it has. A deleted address is brought back.
name in the body replaces the stored name and leaving it out keeps it. notes replaces the stored notes and null clears them. Unlike contacts().create, an address already in the book is not an error, and unlike contacts().update, an address not in the book is not one either.
پارامترها
emailStringالزامیThe address, trimmed and lower cased on the server.
body.nameStringUp to 200 characters. Left out, the stored name is kept.
body.notesString or nullUp to 5,000 characters. Null clears the notes, and left out, they are kept.
options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map for the contact as it stands after the save, with audiences.
نمونه
Map<String, Object> contact = client.contacts().save("[email protected]", Body.of("name", "Grace Hopper")); System.out.println(contact.get("source"));نکته‌ها
The server answers 201 for a new contact and 200 for one that was there. The SDK returns the same map for both, so compare
createdAtwithupdatedAtif you need to tell them apart.Safe to replay, so the SDK retries it after a network failure.
A new contact joins the default audience, as it does from
contacts().create.
همچنین در دسترس در
- API
PUT /contacts/{email}- TypeScript
contacts.save()- Python
contacts.save()- Ruby
contacts.save- PHP
contacts->save- Go
Contacts.Save- C#
Contacts.SaveAsync- CLI
openemail contacts save
contacts().deleteMany
Delete up to 200 contacts in one call
Map<String, Object> deleteMany(List<String> emails, RequestOptions options)Deletes every address in emails the way contacts().delete deletes one: a saved contact goes with its notes, its photo and every audience membership, and every address is hidden, so mail sent to it from the app composer 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. A repeated address counts once. There is no undo.
پارامترها
emailsList<String>الزامی1 to 200 addresses, matched case insensitively. More than 200, or none, is a 422 on
emails.options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map with object set to contact_batch_delete, deleted, saved and invalid. deleted counts the addresses deleted and hidden, saved how many of them were saved contacts.
نمونه
Map<String, Object> result = client.contacts().deleteMany(List.of("[email protected]", "[email protected]")); System.out.println(result.get("deleted") + " " + result.get("saved"));نکته‌ها
Safe to replay: deleting an address twice leaves it deleted and hidden, so the SDK retries it after a network failure.
No mail is deleted, and nobody is unsubscribed from anything.
همچنین در دسترس در
contacts().setPhoto
Upload the photo shown for a contact
Map<String, Object> setPhoto(String email, byte[] data, RequestOptions options)Sends the image bytes as the request body, replacing any photo the contact had. PNG, JPEG, WebP and GIF are accepted, up to 5 MB. The server fits the image into a 512 pixel square, stores it as WebP, keeps the first frame of an animation, and answers with the contact and its new photoUrl.
data is a byte array. The type is read from contentType. Without any of these the bytes go as application/octet-stream and the server refuses them with 422 invalid_image.
The address has to be a saved contact already: contacts().save it first.
پارامترها
emailStringالزامیThe contact's address, matched case insensitively.
databyte[]الزامیThe image as a byte array.
options.contentTypeStringimage/png,image/jpeg,image/webporimage/gif. Required, since a byte array carries no type of its own.options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map for the contact with the new photoUrl.
نمونه
Map<String, Object> contact = client.contacts().setPhoto("[email protected]", Files.readAllBytes(Path.of("grace.jpg")), RequestOptions.of("contentType", "image/jpeg")); System.out.println(contact.get("photoUrl"));نکته‌ها
An address that is not a saved contact is a 404
contact_not_found.A busy image service answers 503
image_busy, which the SDK retries like any other 503.Every upload gets a new URL, so a cached old photo never shows under the new one.
همچنین در دسترس در
contacts().removePhoto
Remove a contact photo
Map<String, Object> removePhoto(String email, RequestOptions options)Takes the photo off the contact and deletes the stored image, the way Remove does on a contact in the app. The contact answers with photoUrl null. Removing a photo from a contact that has none changes nothing.
پارامترها
emailStringالزامیThe contact's address, matched case insensitively.
options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map for the contact with photoUrl null.
نمونه
Map<String, Object> result = client.contacts().removePhoto("[email protected]"); System.out.println(result.get("email") + " " + result.get("name"));نکته‌ها
An address that is not a saved contact is a 404
contact_not_found.Safe to replay, so the SDK retries it after a network failure.
همچنین در دسترس در
contacts().block
Block an address
Map<String, Object> block(String email, RequestOptions options)Puts the address on the workspace blocklist, the same list settings().update edits as blockedSenders, so mail from it is refused from then on. This is Block on a contact in the app. A plus tag is dropped: blocking [email protected] blocks [email protected], and every tag of it.
When a rule already blocks the address, a whole-domain rule included, nothing is added: created is false and blockedBy names that rule. The address does not have to be a contact.
پارامترها
emailStringالزامیThe address to block.
options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map with object set to contact_block, email, blocked set to true, blockedBy and created.
نمونه
Map<String, Object> result = client.contacts().block("[email protected]"); System.out.println(result.get("created") + " " + result.get("blockedBy"));نکته‌ها
It needs
settings:writerather thancontacts:write, because it writes the blocklist rather than the contact.Safe to replay, so the SDK retries it after a network failure.
An address with fewer than two letters or numbers is refused with 422
blocklist_entry_too_broad.A key limited to particular addresses or domains gets 422
capability_unsupportedonaddressAllowlist, because the blocklist belongs to the whole workspace and filters the mail of every address in it.
همچنین در دسترس در
contacts().unblock
Unblock an address
Map<String, Object> unblock(String email, RequestOptions options)Takes every workspace blocklist rule that blocks the address off the list and lists them in removed. This is Unblock on a contact in the app.
When one of them is a whole-domain rule, in blockedDomains, everybody at that domain is unblocked with it, so check removed when that matters. Rules set for one address or one domain in the settings are not touched. An address that no rule blocks answers with removed empty.
پارامترها
emailStringالزامیThe address to unblock.
options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map with object set to contact_block, email, blocked set to false and removed, each entry of which is a map with rule and list.
نمونه
Map<String, Object> result = client.contacts().unblock("[email protected]"); System.out.println(result.get("removed"));نکته‌ها
Safe to replay, so the SDK retries it after a network failure.
A key limited to particular addresses or domains gets 422
capability_unsupportedonaddressAllowlist, because the blocklist belongs to the whole workspace and filters the mail of every address in it.
همچنین در دسترس در
contacts().listThreads
List the conversations with one person
Page listThreads(String email, RequestOptions options)Returns one page of the threads the address wrote or was written to, in every folder: the Mail tab on a contact in the app. Each row is a summary, subject, from, receivedAt, messageCount, hasUnread and labels, and threads().get reads the messages behind its id.
limit takes 1 to 100 and defaults to 25. Pass nextCursor back as cursor, with the same q and sort, while hasMore is true.
پارامترها
emailStringالزامیThe address. It does not have to be a saved contact.
options.qStringSearches inside those threads, with the mailbox search syntax, up to 200 characters.
options.sortStringnewest(the default),oldest,senderorsubject, also inuk.openemail.constants.ContactThreadSorts.options.limitintThreads per page, 1 to 100. The server defaults to 25.
options.cursorStringThe
nextCursorfrom the previous page. Never build one yourself.options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A Page of thread summary maps, with items, hasMore and nextCursor.
نمونه
Page page = client.contacts().listThreads("[email protected]", RequestOptions.of("q", "invoice")); for (Map<String, Object> thread : page) { System.out.println(thread.get("receivedAt") + " " + thread.get("subject"));} if (page.hasMore()) { System.out.println("Next page: " + page.nextCursor());}نکته‌ها
It needs
threads:read, because it reads mail rather than the contact.A key limited to particular addresses or domains gets 422
capability_unsupportedonaddressAllowlist, because a contact's threads and activity are read from the mail of every address in the workspace.
همچنین در دسترس در
contacts().listAllThreads
Collect every conversation with one person into one list
List<Map<String, Object>> listAllThreads(String email, RequestOptions options)Follows nextCursor from page to page and returns every thread contacts().listThreads would list for the address, in the same order.
Everything is held in memory before the call returns. Prefer contacts().iterateThreads when you can stop early.
پارامترها
emailStringالزامیThe address. It does not have to be a saved contact.
options.qStringSearches inside those threads, with the mailbox search syntax, up to 200 characters.
options.sortStringnewest(the default),oldest,senderorsubject.options.limitintPage size per request, from 1 to 100, defaulting to 25 on the server.
options.cursorStringA cursor from an earlier page to start after.
options.apiKeyStringOverrides the client's API key for every page of this walk.
خروجی
A list of thread summary maps holding every thread across all pages.
نمونه
List<Map<String, Object>> threads = client.contacts().listAllThreads("[email protected]"); for (Map<String, Object> thread : threads) { System.out.println(thread.get("id") + " " + thread.get("subject"));}نکته‌ها
A failure on any page throws out of the whole call, and the threads already fetched are discarded.
همچنین در دسترس در
contacts().iterateThreads
Stream the conversations with one person one thread at a time
PagedIterable iterateThreads(String email, RequestOptions options)Returns a PagedIterable that yields the threads contacts().listThreads lists for the address, one at a time, 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.
پارامترها
emailStringالزامیThe address. It does not have to be a saved contact.
options.qStringSearches inside those threads, with the mailbox search syntax, up to 200 characters.
options.sortStringnewest(the default),oldest,senderorsubject.options.limitintPage size per request, from 1 to 100, defaulting to 25 on the server.
options.cursorStringA cursor from an earlier page to start after.
options.apiKeyStringOverrides the client's API key for every page of this walk.
خروجی
A PagedIterable that yields one thread summary map per step.
نمونه
for (Map<String, Object> thread : client.contacts().iterateThreads("[email protected]")) { System.out.println(thread.get("hasUnread") + " " + thread.get("subject"));}نکته‌ها
The generator is lazy, so an abandoned loop costs only the pages you consumed.
همچنین در دسترس در
contacts().activity
Read how mail with one person has gone over a window
Map<String, Object> activity(String email, RequestOptions options)Returns the numbers behind the Activity tab on a contact in the app, over a window that ends now: messages received from the address and sent to it per bucket, the threads that moved, the threads whose newest message is theirs and so waits on a reply from the mailbox, when each side last wrote, and the median time each side takes to answer, in milliseconds.
minutes sets how far back the window reaches, 90 days by default. grain sets the bucket width and the key shape, YYYY-MM-DD, YYYY-MM-DDTHH or YYYY-MM-DDTHH:MM, and offsetMinutes shifts the boundaries so days break where the reader's day does. buckets is sparse and oldest first. Mail in the bin or in spam is left out.
پارامترها
emailStringالزامیThe address. It does not have to be a saved contact.
options.minutesintWindow length in minutes, from 1 to about 20 years. The server defaults to 90 days.
options.grainStringBucket width:
minute,hourorday, defaulting today.options.offsetMinutesintMinutes east of UTC to cut the buckets in, from -840 to 840, defaulting to 0. Pass
ZonedDateTime.now().getOffset().getTotalSeconds() / 60for the local zone.options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map with object set to contact_activity, email, since, until, grain, buckets, totals and replyTime. totals has received, sent, threads, waiting, lastReceivedAt and lastSentAt, and replyTime has yours and theirs, each null when there is no reply to measure.
نمونه
Map<String, Object> activity = client.contacts().activity("[email protected]", RequestOptions.of("minutes", 43200)); System.out.println(activity.get("totals"));نکته‌ها
It needs
threads:read, because it reads mail rather than the contact.Read only, so the SDK retries it after a network failure like any other read.
A key limited to particular addresses or domains gets 422
capability_unsupportedonaddressAllowlist, because a contact's threads and activity are read from the mail of every address in the workspace.
همچنین در دسترس در
contacts().listEvents
List the events recorded for one contact
Page listEvents(String email, RequestOptions options)Returns one page of the events events().send recorded for a contact in the last 90 days, the most recent first by when they happened. Each has its name, properties, occurredAt and mode, which is test for an event a test key sent.
limit takes 1 to 200 and defaults to 50. Pass nextCursor back as cursor, with the same name, while hasMore is true. listAllEvents and iterateEvents do that walk for you.
پارامترها
emailStringالزامیThe contact, by email address, compared without case. The
contactIdan event or an enrollment carries works here too.options.nameStringOnly events with exactly this name.
options.limitintEvents per page, a whole number from 1 to 200. The server defaults to 50.
options.cursorStringThe
nextCursorfrom the previous page, passed back exactly as it came. One that names no event of this contact is a 400invalid_cursor.options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A Page of maps with items, hasMore and nextCursor. Each item has id, contactId, email, name, properties, occurredAt, mode and createdAt.
نمونه
Page page = client.contacts().listEvents("[email protected]", RequestOptions.of("name", "order.placed")); for (Map<String, Object> event : page) { System.out.println(event.get("occurredAt") + " " + event.get("name") + " " + event.get("properties"));}نکته‌ها
An address or id nobody you can reach has is 404
contact_not_found. An app a member connected reads only the contacts that member added.Read only, so the SDK retries it after a network failure like any other read.
همچنین در دسترس در
contacts().listAllEvents
Collect every event of one contact into one list
List<Map<String, Object>> listAllEvents(String email, RequestOptions options)Follows nextCursor from page to page and returns every event recorded for the contact in the last 90 days, the most recent first, in the shape listEvents returns. limit sets the page size of each request, not the total.
پارامترها
emailStringالزامیThe contact, by email address, compared without case. The
contactIdan event or an enrollment carries works here too.options.nameStringOnly events with exactly this name.
options.limitintPage size per request, from 1 to 200, defaulting to 50 on the server.
options.cursorStringA
nextCursorfrom an earlier page to start after.options.apiKeyStringOverrides the client's API key for every page of this walk.
خروجی
A list of maps holding every matching event across all pages, each shaped like an item of listEvents.
نمونه
List<Map<String, Object>> events = client.contacts().listAllEvents("[email protected]");Set<Object> names = new HashSet<>(); for (Map<String, Object> event : events) { names.add(event.get("name"));} System.out.println(events.size() + " " + names);نکته‌ها
A failure on any page throws out of the whole call.
همچنین در دسترس در
contacts().iterateEvents
Stream the events of one contact one at a time
PagedIterable iterateEvents(String email, RequestOptions options)Returns a PagedIterable that yields the events of a contact one by one, the most recent first, and requests the next page only once the current one is drained. Breaking out of the loop stops the requests.
پارامترها
emailStringالزامیThe contact, by email address, compared without case. The
contactIdan event or an enrollment carries works here too.options.nameStringOnly events with exactly this name.
options.limitintPage size per request, from 1 to 200, defaulting to 50 on the server.
options.cursorStringA
nextCursorfrom an earlier page to start after.options.apiKeyStringOverrides the client's API key for every page of this walk.
خروجی
A PagedIterable that yields one event map per step.
نمونه
for (Map<String, Object> event : client.contacts().iterateEvents("[email protected]")) { if ("plan.cancelled".equals(event.get("name"))) { System.out.println("cancelled on " + event.get("occurredAt")); break; }}نکته‌ها
The
PagedIterableis lazy, so an abandoned loop costs only the pages you consumed.
همچنین در دسترس در
contacts().listCards
List the address book as contact cards
Page listCards(RequestOptions options)Returns one page of contact cards, newest first. A card is a saved contact with everything an address book keeps for it: phone numbers, other email addresses, postal addresses, websites, organisation, department, job title, birthday, nickname and the name in parts. Cards with no email address, such as a plumber saved on a phone, are listed too. It is the address book phones and computers sync over CardDAV.
email finds the card of one saved contact, and RequestOptions.of("withoutEmail", true) lists only the cards with no address. An address that was only ever mailed, and never saved, has no card.
Paging is keyset. limit takes 1 to 200 and defaults to 50, and nextCursor goes back as cursor while hasMore is true. Never build a cursor yourself.
پارامترها
options.limitintCards per page, a whole number from 1 to 200. The server defaults to 50.
options.cursorStringThe
nextCursorfrom the previous page. Never build one yourself.options.emailStringOnly the card of the saved contact with this address.
options.withoutEmailbooleanTrue lists only the cards that have no email address.
options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A Page of card maps, with items, hasMore and nextCursor. Each card has id, uid, email, name, nameParts, nickname, organization, department, title, birthday, notes, the lists emails, phones, addresses and urls, photoUrl, createdAt and updatedAt.
نمونه
Page page = client.contacts().listCards(RequestOptions.of("withoutEmail", true)); for (Map<String, Object> card : page) { System.out.println(card.get("name") + " " + card.get("phones"));} if (page.hasMore()) { System.out.println("Next page: " + page.nextCursor());}نکته‌ها
Every member reads the same address book through a key, since a key acts for the workspace owner.
A cursor that names no card is a 400
invalid_cursor. Start again without one.
همچنین در دسترس در
contacts().listAllCards
Collect every contact card into one list
List<Map<String, Object>> listAllCards(RequestOptions options)Follows nextCursor from page to page and returns every card in the address book, newest first. It takes the same email and withoutEmail filters as contacts().listCards.
Everything is held in memory before the call returns. Prefer contacts().iterateCards when you can stop early. limit sets the page size of each request, not the total.
پارامترها
options.emailStringOnly the card of the saved contact with this address.
options.withoutEmailbooleanTrue lists only the cards that have no email address.
options.limitintPage size per request, from 1 to 200, defaulting to 50 on the server.
options.cursorStringA cursor from an earlier page to start after.
options.apiKeyStringOverrides the client's API key for every page of this walk.
خروجی
A list of card maps holding every card across all pages.
نمونه
List<Map<String, Object>> cards = client.contacts().listAllCards(); for (Map<String, Object> card : cards) { System.out.println(card.get("id") + " " + card.get("email"));}نکته‌ها
A failure on any page throws out of the whole call, and the cards already fetched are discarded.
همچنین در دسترس در
contacts().iterateCards
Stream the address book one card at a time
PagedIterable iterateCards(RequestOptions options)Returns a PagedIterable that yields cards one at a time, newest first, 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. It takes the same email and withoutEmail filters as contacts().listCards.
پارامترها
options.emailStringOnly the card of the saved contact with this address.
options.withoutEmailbooleanTrue lists only the cards that have no email address.
options.limitintPage size per request, from 1 to 200, defaulting to 50 on the server.
options.cursorStringA cursor from an earlier page to start after.
options.apiKeyStringOverrides the client's API key for every page of this walk.
خروجی
A PagedIterable that yields one card map per step.
نمونه
for (Map<String, Object> card : client.contacts().iterateCards()) { System.out.println(card.get("birthday") + " " + card.get("name"));}نکته‌ها
The generator is lazy, so an abandoned loop costs only the pages you consumed.
همچنین در دسترس در
contacts().getCard
Get one contact card
Map<String, Object> getCard(String id, RequestOptions options)Returns one card with everything it holds. To find the card of a saved contact by its address, pass email to contacts().listCards.
پارامترها
idStringالزامیThe card id,
ccd_followed by 24 characters, fromcontacts().listCardsorcontacts().getCard.options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map with id, uid, the vCard UID that phones and computers know the card by, email, null on a card with no address, name, nameParts, nickname, organization, department, title, birthday, notes, photoUrl, createdAt and updatedAt. emails, phones and urls are lists of maps with value, label and customLabel, and addresses is a list of maps with label, customLabel, street, locality, region, postalCode and country.
نمونه
Map<String, Object> card = client.contacts().getCard("ccd_0123456789abcdef01234567"); System.out.println(card.get("name") + " " + card.get("organization") + " " + card.get("phones"));نکته‌ها
An id that names no card is a 404
contact_card_not_found, thrown as aNotFoundException.
همچنین در دسترس در
contacts().createCard
Add a card to the address book
Map<String, Object> createCard(Map<String, Object> body, RequestOptions options)Adds a contact card. With email the card is a saved contact as well, the same one contacts().create makes, and an address the workspace already knows from mail becomes saved. Without one it is a card on its own, kept for its name, phone numbers and the rest. A card needs at least a name, an email address, a phone number or an organisation.
Each entry in emails, phones and urls is a map with value, and optionally label, one of uk.openemail.constants.ContactCardLabels, and customLabel, a label of your own.
Phones and computers that sync the address book over CardDAV get the new card on their next sync.
پارامترها
body.emailString or nullThe address OpenEmail knows the contact by. With it the card is a saved contact as well. A saved contact keeps its address, so put any other address in
emails.body.nameString or nullThe full name the address book shows, up to 200 characters.
body.namePartsMap<String, Object> or nullThe name in parts, a map with
prefix,given,middle,familyandsuffix, the way phones keep it.body.nicknameString or nullA nickname.
body.organizationString or nullThe company or organisation.
body.departmentString or nullThe department within the organisation.
body.titleString or nullThe job title.
body.birthdayString or nullYYYY-MM-DD, or--MM-DDwhen the year is not known.body.notesString or nullFree-form notes. On a saved contact these are the notes the contact page shows.
body.emailsList<Map<String, Object>>Other email addresses besides
email, each a map withvalue, and optionallylabelandcustomLabel.body.phonesList<Map<String, Object>>Phone numbers, each a map with
value, and optionallylabelandcustomLabel.body.addressesList<Map<String, Object>>Postal addresses, each a map with any of
label,customLabel,street,locality,region,postalCodeandcountry.body.urlsList<Map<String, Object>>Websites and profile links, each a map with
value, and optionallylabelandcustomLabel.options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map for the new card, with the fields contacts().getCard returns.
نمونه
Map<String, Object> card = client.contacts().createCard(Body.of( "email", "[email protected]", "name", "Ada Lovelace", "organization", "Analytical Engines", "phones", List.of(Body.of("value", "+44 20 7946 0000", "label", "work")), "birthday", "1815-12-10")); System.out.println(card.get("id") + " " + card.get("email"));نکته‌ها
The SDK does not retry it after a network failure, because a second call would make a second card.
An address that already belongs to another card is a 409
contact_card_email_taken, and a card with nothing to keep a 422invalid_contact_card.A workspace that already keeps as many cards as it may gets a 409
contact_card_limit. Delete some before you add more.
همچنین در دسترس در
contacts().updateCard
Change a contact card
Map<String, Object> updateCard(String id, Map<String, Object> patch, RequestOptions options)Changes the fields you send and leaves the rest alone. Null clears a field, and a list you send (emails, phones, addresses or urls) replaces the whole list, so read the card first when you mean to add one entry.
On a saved contact, name and notes are the contact's own, so the contact page shows the change. email can only be given to a card that has none, which makes it a saved contact. A saved contact keeps its address: add another address to emails instead.
Phones and computers that sync the address book over CardDAV get the change on their next sync.
پارامترها
idStringالزامیThe card id,
ccd_followed by 24 characters, fromcontacts().listCardsorcontacts().getCard.patch.emailString or nullThe address OpenEmail knows the contact by. Given to a card that has none, it makes the card a saved contact. A saved contact keeps its address, so put any other address in
emails.patch.nameString or nullThe full name the address book shows, up to 200 characters.
patch.namePartsMap<String, Object> or nullThe name in parts, a map with
prefix,given,middle,familyandsuffix, the way phones keep it.patch.nicknameString or nullA nickname.
patch.organizationString or nullThe company or organisation.
patch.departmentString or nullThe department within the organisation.
patch.titleString or nullThe job title.
patch.birthdayString or nullYYYY-MM-DD, or--MM-DDwhen the year is not known.patch.notesString or nullFree-form notes. On a saved contact these are the notes the contact page shows.
patch.emailsList<Map<String, Object>>Other email addresses besides
email, each a map withvalue, and optionallylabelandcustomLabel. The list replaces the one the card has.patch.phonesList<Map<String, Object>>Phone numbers, each a map with
value, and optionallylabelandcustomLabel. The list replaces the one the card has.patch.addressesList<Map<String, Object>>Postal addresses, each a map with any of
label,customLabel,street,locality,region,postalCodeandcountry. The list replaces the one the card has.patch.urlsList<Map<String, Object>>Websites and profile links, each a map with
value, and optionallylabelandcustomLabel. The list replaces the one the card has.options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map for the card as it stands after the change.
نمونه
Map<String, Object> updated = client.contacts().updateCard("ccd_0123456789abcdef01234567", Body.of( "phones", List.of(Body.of("value", "+1 555 0100", "label", "mobile")))); System.out.println(updated.get("phones"));نکته‌ها
The SDK retries this call after a network failure, since the same patch sent twice leaves the same card.
Changing the address of a saved contact is a 422
invalid_contact_card, and an address that already belongs to another card a 409contact_card_email_taken.An id that names no card is a 404
contact_card_not_found.
همچنین در دسترس در
contacts().deleteCard
Delete a contact card
Map<String, Object> deleteCard(String id, RequestOptions options)Removes the card from the address book and from every phone and computer that syncs it. On a saved contact it is the same as contacts().delete: the contact goes with its notes, photo and audiences, and the address is hidden from the people list and the suggestions.
پارامترها
idStringالزامیThe card id,
ccd_followed by 24 characters, fromcontacts().listCardsorcontacts().getCard.options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map with object set to contact_card, id and deleted set to true.
نمونه
Map<String, Object> removed = client.contacts().deleteCard("ccd_0123456789abcdef01234567"); System.out.println(removed.get("id") + " " + removed.get("deleted"));نکته‌ها
There is no undo, and the SDK does not retry it after a network failure.
An id that names no card is a 404
contact_card_not_found.
همچنین در دسترس در
contacts().importVcf
Import a contacts file
Map<String, Object> importVcf(byte[] data, RequestOptions options)Sends a vCard (.vcf) file as the request body and queues it. Every card in it becomes a contact card, with its phone numbers, addresses and the rest. Poll getImport until status is completed.
The file may be 20 MB. Imported contacts join no audience, so a broadcast never reaches them because of an import. A card whose address or UID is already in the address book is counted under merged and left as it is, and a card with no address is matched on its phone number. A workspace keeps 20,000 cards, and the cards past that are counted under skipped.
data is a byte array, and it goes out as text/vcard.
پارامترها
databyte[]الزامیThe .vcf file: a byte array.
options.filenameStringThe name to show for the file in the list of imports, at most 255 characters.
options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map with status set to queued.
نمونه
Map<String, Object> queued = client.contacts().importVcf(Files.readAllBytes(Path.of("contacts.vcf")), RequestOptions.of("filename", "contacts.vcf")); System.out.println(queued.get("id") + " " + queued.get("status"));نکته‌ها
A body that holds no vCard is a 400
not_a_contacts_file, and an empty one a 400item_import_empty.A file over 20 MB is a 413
item_import_too_large.To send text you already hold, encode it first with
text.getBytes(StandardCharsets.UTF_8).An upload that outlasts the client
timeoutfails as a network error, so raise it on the client for a large file on a slow connection.Not retried automatically.
همچنین در دسترس در
contacts().listImports
List contacts imports
Page listImports(RequestOptions options)Returns one page of the contacts files and address books brought in, newest first, each with what it added and what it left out. Beside the files sent with importVcf it lists the address books that came with a mailbox import, and those carry the id of that import in parentImportId.
Paging is keyset. limit takes 1 to 100 and defaults to 25, and nextCursor goes back as cursor while hasMore is true. listAllImports and iterateImports do that walk for you.
پارامترها
options.limitintImports per page, a whole number from 1 to 100. The server defaults to 25.
options.cursorStringThe
nextCursorfrom the previous page. Never build one yourself.options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A Page of maps with items, hasMore and nextCursor.
نمونه
Page page = client.contacts().listImports(RequestOptions.create().limit(50)); for (Map<String, Object> item : page) { System.out.println(item.get("fileName") + " " + item.get("status") + " " + item.get("counts"));} if (page.hasMore()) { System.out.println("Next page: " + page.nextCursor());}نکته‌ها
sourceisfilefor an upload.takeout,carddavandmicrosoftcame with a mailbox import.A cursor that names no import is a 400
invalid_cursor.A GET is retried automatically on network failure and on 408, 500, 502, 503 and 504 responses, up to the client
maxRetries, and on a 429 only when it carries aRetry-Afterof a minute or less.
همچنین در دسترس در
contacts().listAllImports
Collect every contacts import into one list
List<Map<String, Object>> listAllImports(RequestOptions options)Follows nextCursor from page to page and returns every contacts import, newest first.
Everything is held in memory before the call settles. Prefer iterateImports when you can stop early. limit sets the page size of each request, not the total.
پارامترها
options.limitintPage size per request, from 1 to 100, defaulting to 25 on the server.
options.cursorStringA cursor from an earlier page to start after.
options.apiKeyStringOverrides the client's API key for every page of this walk.
خروجی
A list of maps holding every import across all pages.
نمونه
List<Map<String, Object>> imports = client.contacts().listAllImports(); for (Map<String, Object> item : imports) { System.out.println(item.get("counts"));}نکته‌ها
A failure on any page rejects the whole call, and the imports already fetched are discarded.
همچنین در دسترس در
contacts().iterateImports
Stream contacts imports one at a time
PagedIterable iterateImports(RequestOptions options)Returns a PagedIterable that yields contacts imports one by one, newest first, 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.
پارامترها
options.limitintPage size per request, from 1 to 100, defaulting to 25 on the server.
options.cursorStringA cursor from an earlier page to start after.
options.apiKeyStringOverrides the client's API key for every page of this walk.
خروجی
A PagedIterable of maps yielding one import per step.
نمونه
for (Map<String, Object> item : client.contacts().iterateImports()) { System.out.println(item.get("status") + " " + item.get("id") + " " + item.get("counts"));}نکته‌ها
The generator is lazy, so an abandoned loop costs only the pages you consumed.
همچنین در دسترس در
contacts().getImport
Get a contacts import
Map<String, Object> getImport(String id, RequestOptions options)Returns one contacts import with its counts and its report: the files it read, how many cards it left out and why, and up to 20 of the cards it left out. Poll it after importVcf until status is completed or failed.
counts.imported is what was added, counts.merged the cards left as they were because they were already in the address book, and counts.skipped what was left out, which report.skipped breaks down by reason: limit for a card past the 20,000 a workspace keeps, invalid for one that could not be read and empty for one that held nothing.
پارامترها
idStringالزامیContacts import id,
iimp_followed by 24 hex characters.options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map with status, counts, report, undoable and when it started, finished and was undone.
نمونه
Map<String, Object> item = client.contacts().getImport("iimp_7b1e4d8f60a5c7b92d3f9c2a"); System.out.println(item.get("status") + " " + item.get("counts") + " " + item.get("report"));نکته‌ها
An id that names no contacts import is a 404
item_import_not_found.A GET is retried automatically on network failure and on 408, 500, 502, 503 and 504 responses, up to the client
maxRetries, and on a 429 only when it carries aRetry-Afterof a minute or less.
همچنین در دسترس در
contacts().undoImport
Remove what a contacts import added
Map<String, Object> undoImport(String id, RequestOptions options)Deletes every contact and card the import added, changed since or not, and marks the import undone. Contacts that were already in the address book are not touched.
پارامترها
idStringالزامیContacts import id,
iimp_followed by 24 hex characters.options.apiKeyStringOverrides the client's API key for this call only.
خروجی
A map with status set to undone and undoneAt set.
نمونه
Map<String, Object> undone = client.contacts().undoImport("iimp_7b1e4d8f60a5c7b92d3f9c2a"); System.out.println(undone.get("status") + " " + undone.get("undoneAt") + " " + undone.get("counts"));نکته‌ها
An import that is still running, or was already removed, is a 409
item_import_not_undoable.undoableon the import says whether the call would remove anything.An id that names no contacts import is a 404
item_import_not_found.Not retried automatically.