nextmail contacts

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 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 { source: 'manual' } is the contacts somebody saved on purpose and { source: 'auto' } the ones the composer recorded. --q searches the name and the address.

This lists saved contacts only. 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.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Looks up a contact by address in the workspace address book. The address is trimmed and lower cased before the lookup, so Grace@Example.com finds grace@example.com, 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.

Adds one address to the workspace address book and returns the saved row. email is trimmed and lower cased before it is stored, so Grace@Example.com and grace@example.com 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 --audience-ids to put it in them in the same call, or add it later with audiences.addContact. Sending --audience-ids 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 get and change it with update.

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 { notes: null } empties the notes while {} changes nothing. attributes is merged key by key: a string sets a custom field, null removes one and the fields you do not name are kept.

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 delete and a 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.

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: 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. create or save afterwards brings the address back as a new contact with no name, no notes and no membership beyond the default audience.

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 { audienceIds: [] } 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 create, which takes --audience-ids too. An id that is not an audience of this workspace is a 404 audience_not_found on --audience-ids, and nothing is changed.

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. 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 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.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one JSON document with --json, shaped as Returns describes. --max <n> stops after that many items.

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 replaces the stored name and leaving it out keeps it. --notes replaces the stored notes and null clears them. --attributes sets the custom fields it names and keeps the rest. Unlike create, an address already in the book is not an error, and unlike update, an address not in the book is not one either.

Deletes every address in emails the way 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.

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 Blob, an ArrayBuffer or a Uint8Array. The type is read from --content-type, or from a Blob's own type when that is left out. Without either 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: save it first.

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.

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 ada+news@example.com blocks ada@example.com, 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.

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.

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.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

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 --offset-minutes 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.

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.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

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, job title and birthday. 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 --without-email 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.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Resolves one card with everything it holds. To find the card of a saved contact by its address, list the cards with email.

Adds a contact card. With email the card is a saved contact as well, the same one 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.

Phones and computers that sync the address book over CardDAV get the new card on their next sync.

Changes the fields you send and leaves the rest alone. null clears a field, and a list you send (emails, phones, addresses, 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.

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 delete: the contact goes with its notes, photo and audiences, and the address is hidden from the people list and the suggestions.

Finds the cards in the address book that look like the same person, as Find duplicates on the Contacts page of the app does: cards that share an email address or a phone number, or that have the same full name. Each group in data lists its cards with the most complete one first, which is the card to keep when you pass the rest to mergeCards.

Groups found by a shared address come first, then by phone number, then by name. Phone numbers match on their last nine digits, so +44 20 7946 0000 and 020 7946 0000 are the same number. Group cards are never compared.

Folds other cards into the card id names and deletes them, as Merge does in Find duplicates on the Contacts page of the app. Fields the kept card leaves empty are filled from the others, notes are joined, and every email address, phone number, postal address and website is kept. Groups that held the other cards hold the kept one instead.

A saved contact among the others stays known by its address, in the people list and in its audiences, but it leaves the address book. When the kept card has no address of its own, it becomes the saved contact of the first address the others had. Phones and computers that sync the address book over CardDAV get the change on their next sync.

Resolves the birthdays of the people in the address book that fall between from and to, the birthdays calendar the Calendar page of the app can show. There is one entry for each date, so a window of a whole year can hold somebody twice, and age is how old they turn that day when the card holds the year of birth. Somebody born on 29 February has their birthday on 28 February in other years.

from and to take a Date or an ISO 8601 string and may be at most 366 days apart. timezone, UTC unless you say, decides which day the window starts and ends on.

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 Blob, an ArrayBuffer or a Uint8Array, and it goes out as text/vcard.

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.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Resolves 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.

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.