--- title: "nextmail contacts" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://nextmail.sh/docs/cli/reference/contacts" area: "CLI" category: "Reference" --- # nextmail contacts Every command in this namespace, with its arguments, flags and examples. ## Commands ### `nextmail contacts list` List the workspace contacts, most recently seen first ```bash nextmail contacts list [flags] ``` 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 ` stops after that many items. - Scopes: `contacts:read`. - Needs a sign-in. - Aliases: `ls`. **Flags** - `--limit ` (default `50`): Rows per page, a whole number from 1 to 200. The server defaults to 50. - `--cursor `: The `nextCursor` from the previous page. Never build one yourself. - `--source `: `manual`, `auto` or `form`. Leave it out for the whole book. - `--q `: Searches 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. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** ```bash nextmail contacts list ``` With optional flags ```bash nextmail contacts list --limit 200 --source manual ``` Walk every page and stop after 100 items ```bash nextmail contacts list --all --max 100 ``` One JSON object per line when piped ```bash nextmail contacts list --all > contacts.ndjson ``` Also available in: API [`GET /contacts`](https://nextmail.sh/docs/api/reference/contacts#get-contacts); TypeScript [`nextmail.contacts.list()`](https://nextmail.sh/docs/sdk/reference/contacts#list); Python [`contacts.list()`](https://nextmail.sh/docs/python/reference/contacts#list); Ruby [`contacts.list`](https://nextmail.sh/docs/ruby/reference/contacts#list); PHP [`contacts->list`](https://nextmail.sh/docs/php/reference/contacts#list); Go [`Contacts.List`](https://nextmail.sh/docs/go/reference/contacts#list); Java [`contacts().list`](https://nextmail.sh/docs/java/reference/contacts#list); C# [`Contacts.ListAsync`](https://nextmail.sh/docs/csharp/reference/contacts#list). ### `nextmail contacts get` Read one contact by email address ```bash nextmail contacts get [flags] ``` 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. - Scopes: `contacts:read`. - Needs a sign-in. - Aliases: `show`, `view`. **Arguments** - `` (required): The contact's address, matched case insensitively. **Examples** ```bash nextmail contacts get grace@example.com ``` Print the raw JSON ```bash nextmail contacts get grace@example.com --json ``` Also available in: API [`GET /contacts/{email}`](https://nextmail.sh/docs/api/reference/contacts#get-contacts-email); TypeScript [`nextmail.contacts.get()`](https://nextmail.sh/docs/sdk/reference/contacts#get); Python [`contacts.get()`](https://nextmail.sh/docs/python/reference/contacts#get); Ruby [`contacts.get`](https://nextmail.sh/docs/ruby/reference/contacts#get); PHP [`contacts->get`](https://nextmail.sh/docs/php/reference/contacts#get); Go [`Contacts.Get`](https://nextmail.sh/docs/go/reference/contacts#get); Java [`contacts().get`](https://nextmail.sh/docs/java/reference/contacts#get); C# [`Contacts.GetAsync`](https://nextmail.sh/docs/csharp/reference/contacts#get). ### `nextmail contacts create` Save a contact in the workspace address book ```bash nextmail contacts create --email [flags] nextmail contacts create --data [flags] ``` 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`. - Scopes: `contacts:write`. - Needs a sign-in. - Aliases: `new`, `add`. **Flags** - `--email `: The address to save, trimmed and lower cased before it is stored. Required, here or in `--data`. - `--name `: Display name. Leave it out to save the contact without one. - `--notes `: Free text kept with the contact and shown beside it in the app. - `--attributes `: Custom fields to set, as an object of keys and text values such as `{ plan: 'team' }`. A key starts with a letter and holds up to 64 letters, digits and underscores, and a value is text of up to 500 characters, trimmed before it is stored. Null removes a field, a field you leave out keeps its value, and a contact holds at most 50. JSON shaped as `Record`, inline or from a file with @path. - `--audience-ids ` (repeatable): 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. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash nextmail contacts create --email grace@example.com ``` With optional flags ```bash nextmail contacts create --email grace@example.com --name 'Grace Hopper' --notes 'Met at the compiler workshop' ``` Read the whole body from a JSON file ```bash nextmail contacts create --data @contact.json ``` Also available in: API [`POST /contacts`](https://nextmail.sh/docs/api/reference/contacts#post-contacts); TypeScript [`nextmail.contacts.create()`](https://nextmail.sh/docs/sdk/reference/contacts#create); Python [`contacts.create()`](https://nextmail.sh/docs/python/reference/contacts#create); Ruby [`contacts.create`](https://nextmail.sh/docs/ruby/reference/contacts#create); PHP [`contacts->create`](https://nextmail.sh/docs/php/reference/contacts#create); Go [`Contacts.Create`](https://nextmail.sh/docs/go/reference/contacts#create); Java [`contacts().create`](https://nextmail.sh/docs/java/reference/contacts#create); C# [`Contacts.CreateAsync`](https://nextmail.sh/docs/csharp/reference/contacts#create). ### `nextmail contacts update` Change a contact's name, notes or custom fields ```bash nextmail contacts update [flags] ``` 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. - Scopes: `contacts:write`. - Needs a sign-in. - Aliases: `edit`. **Arguments** - `` (required): The contact's address, matched case insensitively. **Flags** - `--name `: New display name. Null clears it. - `--notes `: New notes. Null clears them. - `--attributes `: Custom fields to set, as an object of keys and text values such as `{ plan: 'team' }`. A key starts with a letter and holds up to 64 letters, digits and underscores, and a value is text of up to 500 characters, trimmed before it is stored. Null removes a field, a field you leave out keeps its value, and a contact holds at most 50. JSON shaped as `Record`, inline or from a file with @path. - `--data `: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** With optional flags ```bash nextmail contacts update grace@example.com --name 'Grace Hopper' ``` Print the raw JSON ```bash nextmail contacts update grace@example.com --name 'Grace Hopper' --json ``` Also available in: API [`PATCH /contacts/{email}`](https://nextmail.sh/docs/api/reference/contacts#patch-contacts-email); TypeScript [`nextmail.contacts.update()`](https://nextmail.sh/docs/sdk/reference/contacts#update); Python [`contacts.update()`](https://nextmail.sh/docs/python/reference/contacts#update); Ruby [`contacts.update`](https://nextmail.sh/docs/ruby/reference/contacts#update); PHP [`contacts->update`](https://nextmail.sh/docs/php/reference/contacts#update); Go [`Contacts.Update`](https://nextmail.sh/docs/go/reference/contacts#update); Java [`contacts().update`](https://nextmail.sh/docs/java/reference/contacts#update); C# [`Contacts.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/contacts#update). ### `nextmail contacts delete` Delete somebody from the contacts and hide the address ```bash nextmail contacts delete [flags] ``` 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. - Scopes: `contacts:write`. - Needs a sign-in. - Asks you to confirm. - Aliases: `rm`, `del`, `remove`. **Arguments** - `` (required): The contact's address, matched case insensitively. **Examples** ```bash nextmail contacts delete grace@example.com ``` Skip the confirmation, for scripts ```bash nextmail contacts delete grace@example.com --yes ``` Also available in: API [`DELETE /contacts/{email}`](https://nextmail.sh/docs/api/reference/contacts#delete-contacts-email); TypeScript [`nextmail.contacts.delete()`](https://nextmail.sh/docs/sdk/reference/contacts#delete); Python [`contacts.delete()`](https://nextmail.sh/docs/python/reference/contacts#delete); Ruby [`contacts.delete`](https://nextmail.sh/docs/ruby/reference/contacts#delete); PHP [`contacts->delete`](https://nextmail.sh/docs/php/reference/contacts#delete); Go [`Contacts.Delete`](https://nextmail.sh/docs/go/reference/contacts#delete); Java [`contacts().delete`](https://nextmail.sh/docs/java/reference/contacts#delete); C# [`Contacts.DeleteAsync`](https://nextmail.sh/docs/csharp/reference/contacts#delete). ### `nextmail contacts set-audiences` Set exactly which audiences a contact is in ```bash nextmail contacts set-audiences --audience-ids [flags] nextmail contacts set-audiences --data [flags] ``` 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. - Scopes: `audiences:write`. - Needs a sign-in. **Arguments** - `` (required): The contact's address, matched case insensitively. **Flags** - `--audience-ids ` (repeatable): Every audience the contact should be in, up to 100 ids. A repeated id counts once. More than 100 is a 422 `invalid_parameter` on `--audience-ids`, and an empty id is the same error on that entry, such as `audienceIds.0`. Required, here or in `--data`. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash nextmail contacts set-audiences grace@example.com --audience-ids aud_9f2c4b7e1a0d63d84c5f2e7b,aud_1c4e7a9b2d0f36e85a7c1b4d ``` Read the whole body from a JSON file ```bash nextmail contacts set-audiences grace@example.com --data @contact.json ``` Also available in: API [`PUT /contacts/{email}/audiences`](https://nextmail.sh/docs/api/reference/contacts#put-contacts-email-audiences); TypeScript [`nextmail.contacts.setAudiences()`](https://nextmail.sh/docs/sdk/reference/contacts#setAudiences); Python [`contacts.set_audiences()`](https://nextmail.sh/docs/python/reference/contacts#setAudiences); Ruby [`contacts.set_audiences`](https://nextmail.sh/docs/ruby/reference/contacts#setAudiences); PHP [`contacts->setAudiences`](https://nextmail.sh/docs/php/reference/contacts#setAudiences); Go [`Contacts.SetAudiences`](https://nextmail.sh/docs/go/reference/contacts#setAudiences); Java [`contacts().setAudiences`](https://nextmail.sh/docs/java/reference/contacts#setAudiences); C# [`Contacts.SetAudiencesAsync`](https://nextmail.sh/docs/csharp/reference/contacts#setAudiences). ### `nextmail contacts list-people` List everyone on the Contacts page, saved or seen in mail ```bash nextmail contacts list-people [flags] ``` 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 ` stops after that many items. - Scopes: `contacts:read`. - Needs a sign-in. **Flags** - `--q `: Searches names, addresses and notes, up to 200 characters. When nothing matches exactly on the first page, close spellings are returned instead. - `--email `: One address only, matched case insensitively: the way to read one person's thread count and last mail. - `--sort ` (default `"recent"`): `recent` (the default), `name` or `threads`. - `--blocked`: `true` for only the people the workspace blocklist blocks, whole-domain rules included. - `--limit ` (default `25`): Rows per page, 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` from the previous page. Never build one yourself. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** ```bash nextmail contacts list-people ``` With optional flags ```bash nextmail contacts list-people --sort threads --limit 50 ``` Walk every page and stop after 100 items ```bash nextmail contacts list-people --all --max 100 ``` One JSON object per line when piped ```bash nextmail contacts list-people --all > contacts.ndjson ``` Also available in: API [`GET /contacts/people`](https://nextmail.sh/docs/api/reference/contacts#get-contacts-people); TypeScript [`nextmail.contacts.listPeople()`](https://nextmail.sh/docs/sdk/reference/contacts#listPeople); Python [`contacts.list_people()`](https://nextmail.sh/docs/python/reference/contacts#listPeople); Ruby [`contacts.list_people`](https://nextmail.sh/docs/ruby/reference/contacts#listPeople); PHP [`contacts->listPeople`](https://nextmail.sh/docs/php/reference/contacts#listPeople); Go [`Contacts.ListPeople`](https://nextmail.sh/docs/go/reference/contacts#listPeople); Java [`contacts().listPeople`](https://nextmail.sh/docs/java/reference/contacts#listPeople); C# [`Contacts.ListPeopleAsync`](https://nextmail.sh/docs/csharp/reference/contacts#listPeople). ### `nextmail contacts save` Save an address as a contact, or keep one that was recorded ```bash nextmail contacts save [flags] ``` 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. - Scopes: `contacts:write`. - Needs a sign-in. **Arguments** - `` (required): The address, trimmed and lower cased on the server. **Flags** - `--name `: Up to 200 characters. Left out, the stored name is kept. - `--notes `: Up to 5,000 characters. `null` clears the notes; left out, they are kept. - `--attributes `: Custom fields to set, as an object of keys and text values such as `{ plan: 'team' }`. A key starts with a letter and holds up to 64 letters, digits and underscores, and a value is text of up to 500 characters, trimmed before it is stored. Null removes a field, a field you leave out keeps its value, and a contact holds at most 50. JSON shaped as `Record`, inline or from a file with @path. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash nextmail contacts save grace@example.com ``` With optional flags ```bash nextmail contacts save grace@example.com --name 'Grace Hopper' ``` Also available in: API [`PUT /contacts/{email}`](https://nextmail.sh/docs/api/reference/contacts#put-contacts-email); TypeScript [`nextmail.contacts.save()`](https://nextmail.sh/docs/sdk/reference/contacts#save); Python [`contacts.save()`](https://nextmail.sh/docs/python/reference/contacts#save); Ruby [`contacts.save`](https://nextmail.sh/docs/ruby/reference/contacts#save); PHP [`contacts->save`](https://nextmail.sh/docs/php/reference/contacts#save); Go [`Contacts.Save`](https://nextmail.sh/docs/go/reference/contacts#save); Java [`contacts().save`](https://nextmail.sh/docs/java/reference/contacts#save); C# [`Contacts.SaveAsync`](https://nextmail.sh/docs/csharp/reference/contacts#save). ### `nextmail contacts delete-many` Delete up to 200 contacts in one call ```bash nextmail contacts delete-many [flags] ``` 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. - Scopes: `contacts:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): 1 to 200 addresses, matched case insensitively. More than 200, or none, is a 422 on `emails`. **Examples** ```bash nextmail contacts delete-many ada@example.com grace@example.com ``` Skip the confirmation, for scripts ```bash nextmail contacts delete-many ada@example.com grace@example.com --yes ``` Also available in: API [`POST /contacts/batch-delete`](https://nextmail.sh/docs/api/reference/contacts#post-contacts-batch-delete); TypeScript [`nextmail.contacts.deleteMany()`](https://nextmail.sh/docs/sdk/reference/contacts#deleteMany); Python [`contacts.delete_many()`](https://nextmail.sh/docs/python/reference/contacts#deleteMany); Ruby [`contacts.delete_many`](https://nextmail.sh/docs/ruby/reference/contacts#deleteMany); PHP [`contacts->deleteMany`](https://nextmail.sh/docs/php/reference/contacts#deleteMany); Go [`Contacts.DeleteMany`](https://nextmail.sh/docs/go/reference/contacts#deleteMany); Java [`contacts().deleteMany`](https://nextmail.sh/docs/java/reference/contacts#deleteMany); C# [`Contacts.DeleteManyAsync`](https://nextmail.sh/docs/csharp/reference/contacts#deleteMany). ### `nextmail contacts set-photo` Upload the photo shown for a contact ```bash nextmail contacts set-photo [flags] ``` 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. - Scopes: `contacts:write`. - Needs a sign-in. **Arguments** - `` (required): The contact's address, matched case insensitively. - `` (required): The image: a `Blob`, `ArrayBuffer` or `Uint8Array`. **Flags** - `--content-type `: `image/png`, `image/jpeg`, `image/webp` or `image/gif`. Required unless `data` is a `Blob` with a type. **Examples** The required values only ```bash nextmail contacts set-photo grace@example.com ./photo.jpg ``` With optional flags ```bash nextmail contacts set-photo grace@example.com ./photo.jpg --content-type image/jpeg ``` Also available in: API [`PUT /contacts/{email}/photo`](https://nextmail.sh/docs/api/reference/contacts#put-contacts-email-photo); TypeScript [`nextmail.contacts.setPhoto()`](https://nextmail.sh/docs/sdk/reference/contacts#setPhoto); Python [`contacts.set_photo()`](https://nextmail.sh/docs/python/reference/contacts#setPhoto); Ruby [`contacts.set_photo`](https://nextmail.sh/docs/ruby/reference/contacts#setPhoto); PHP [`contacts->setPhoto`](https://nextmail.sh/docs/php/reference/contacts#setPhoto); Go [`Contacts.SetPhoto`](https://nextmail.sh/docs/go/reference/contacts#setPhoto); Java [`contacts().setPhoto`](https://nextmail.sh/docs/java/reference/contacts#setPhoto); C# [`Contacts.SetPhotoAsync`](https://nextmail.sh/docs/csharp/reference/contacts#setPhoto). ### `nextmail contacts remove-photo` Remove a contact photo ```bash nextmail contacts remove-photo [flags] ``` 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. - Scopes: `contacts:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): The contact's address, matched case insensitively. **Examples** ```bash nextmail contacts remove-photo grace@example.com ``` Skip the confirmation, for scripts ```bash nextmail contacts remove-photo grace@example.com --yes ``` Also available in: API [`DELETE /contacts/{email}/photo`](https://nextmail.sh/docs/api/reference/contacts#delete-contacts-email-photo); TypeScript [`nextmail.contacts.removePhoto()`](https://nextmail.sh/docs/sdk/reference/contacts#removePhoto); Python [`contacts.remove_photo()`](https://nextmail.sh/docs/python/reference/contacts#removePhoto); Ruby [`contacts.remove_photo`](https://nextmail.sh/docs/ruby/reference/contacts#removePhoto); PHP [`contacts->removePhoto`](https://nextmail.sh/docs/php/reference/contacts#removePhoto); Go [`Contacts.RemovePhoto`](https://nextmail.sh/docs/go/reference/contacts#removePhoto); Java [`contacts().removePhoto`](https://nextmail.sh/docs/java/reference/contacts#removePhoto); C# [`Contacts.RemovePhotoAsync`](https://nextmail.sh/docs/csharp/reference/contacts#removePhoto). ### `nextmail contacts block` Block an address ```bash nextmail contacts block [flags] ``` 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. - Scopes: `settings:write`. - Needs a sign-in. **Arguments** - `` (required): The address to block. **Examples** ```bash nextmail contacts block spammer@example.com ``` Print the raw JSON ```bash nextmail contacts block spammer@example.com --json ``` Also available in: API [`POST /contacts/{email}/block`](https://nextmail.sh/docs/api/reference/contacts#post-contacts-email-block); TypeScript [`nextmail.contacts.block()`](https://nextmail.sh/docs/sdk/reference/contacts#block); Python [`contacts.block()`](https://nextmail.sh/docs/python/reference/contacts#block); Ruby [`contacts.block`](https://nextmail.sh/docs/ruby/reference/contacts#block); PHP [`contacts->block`](https://nextmail.sh/docs/php/reference/contacts#block); Go [`Contacts.Block`](https://nextmail.sh/docs/go/reference/contacts#block); Java [`contacts().block`](https://nextmail.sh/docs/java/reference/contacts#block); C# [`Contacts.BlockAsync`](https://nextmail.sh/docs/csharp/reference/contacts#block). ### `nextmail contacts unblock` Unblock an address ```bash nextmail contacts unblock [flags] ``` 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. - Scopes: `settings:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): The address to unblock. **Examples** ```bash nextmail contacts unblock friend@example.com ``` Skip the confirmation, for scripts ```bash nextmail contacts unblock friend@example.com --yes ``` Also available in: API [`DELETE /contacts/{email}/block`](https://nextmail.sh/docs/api/reference/contacts#delete-contacts-email-block); TypeScript [`nextmail.contacts.unblock()`](https://nextmail.sh/docs/sdk/reference/contacts#unblock); Python [`contacts.unblock()`](https://nextmail.sh/docs/python/reference/contacts#unblock); Ruby [`contacts.unblock`](https://nextmail.sh/docs/ruby/reference/contacts#unblock); PHP [`contacts->unblock`](https://nextmail.sh/docs/php/reference/contacts#unblock); Go [`Contacts.Unblock`](https://nextmail.sh/docs/go/reference/contacts#unblock); Java [`contacts().unblock`](https://nextmail.sh/docs/java/reference/contacts#unblock); C# [`Contacts.UnblockAsync`](https://nextmail.sh/docs/csharp/reference/contacts#unblock). ### `nextmail contacts list-threads` List the conversations with one person ```bash nextmail contacts list-threads [flags] ``` 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 ` stops after that many items. - Scopes: `threads:read`. - Needs a sign-in. **Arguments** - `` (required): The address. It does not have to be a saved contact. **Flags** - `--q `: Searches inside those threads, with the mailbox search syntax, up to 200 characters. - `--sort ` (default `"newest"`): `newest` (the default), `oldest`, `sender` or `subject`. - `--limit ` (default `25`): Threads per page, 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` from the previous page. Never build one yourself. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** The required values only ```bash nextmail contacts list-threads ada@example.com ``` With optional flags ```bash nextmail contacts list-threads ada@example.com --q invoice ``` Walk every page and stop after 100 items ```bash nextmail contacts list-threads ada@example.com --all --max 100 ``` One JSON object per line when piped ```bash nextmail contacts list-threads ada@example.com --all > contacts.ndjson ``` Also available in: API [`GET /contacts/{email}/threads`](https://nextmail.sh/docs/api/reference/contacts#get-contacts-email-threads); TypeScript [`nextmail.contacts.listThreads()`](https://nextmail.sh/docs/sdk/reference/contacts#listThreads); Python [`contacts.list_threads()`](https://nextmail.sh/docs/python/reference/contacts#listThreads); Ruby [`contacts.list_threads`](https://nextmail.sh/docs/ruby/reference/contacts#listThreads); PHP [`contacts->listThreads`](https://nextmail.sh/docs/php/reference/contacts#listThreads); Go [`Contacts.ListThreads`](https://nextmail.sh/docs/go/reference/contacts#listThreads); Java [`contacts().listThreads`](https://nextmail.sh/docs/java/reference/contacts#listThreads); C# [`Contacts.ListThreadsAsync`](https://nextmail.sh/docs/csharp/reference/contacts#listThreads). ### `nextmail contacts activity` Read how mail with one person has gone over a window ```bash nextmail contacts activity [flags] ``` 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. - Scopes: `threads:read`. - Needs a sign-in. **Arguments** - `` (required): The address. It does not have to be a saved contact. **Flags** - `--minutes ` (default `129600`): Window length in minutes, from 1 to about 20 years. The server defaults to 90 days. - `--grain ` (default `"day"`): Bucket width: `minute`, `hour` or `day`, defaulting to `day`. - `--offset-minutes ` (default `0`): Minutes east of UTC to cut the buckets in, from -840 to 840, defaulting to 0. Pass `-new Date().getTimezoneOffset()` for the local zone. **Examples** ```bash nextmail contacts activity ada@example.com ``` Print the raw JSON ```bash nextmail contacts activity ada@example.com --json ``` Also available in: API [`GET /contacts/{email}/activity`](https://nextmail.sh/docs/api/reference/contacts#get-contacts-email-activity); TypeScript [`nextmail.contacts.activity()`](https://nextmail.sh/docs/sdk/reference/contacts#activity); Python [`contacts.activity()`](https://nextmail.sh/docs/python/reference/contacts#activity); Ruby [`contacts.activity`](https://nextmail.sh/docs/ruby/reference/contacts#activity); PHP [`contacts->activity`](https://nextmail.sh/docs/php/reference/contacts#activity); Go [`Contacts.Activity`](https://nextmail.sh/docs/go/reference/contacts#activity); Java [`contacts().activity`](https://nextmail.sh/docs/java/reference/contacts#activity); C# [`Contacts.ActivityAsync`](https://nextmail.sh/docs/csharp/reference/contacts#activity). ### `nextmail contacts list-events` List the events recorded for one contact ```bash nextmail contacts list-events [flags] ``` 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 ` stops after that many items. - Scopes: `contacts:read`. - Needs a sign-in. **Arguments** - `` (required): The contact, by email address, compared without case. The `contactId` an event or an enrollment carries works here too. **Flags** - `--name `: Only events with exactly this name. - `--limit ` (default `50`): Events per page, a whole number from 1 to 200. The server defaults to 50. - `--cursor `: The `nextCursor` from the previous page, passed back exactly as it came. One that names no event of this contact is a 400 `invalid_cursor`. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** The required values only ```bash nextmail contacts list-events ada@example.com ``` With optional flags ```bash nextmail contacts list-events ada@example.com --name order.placed ``` Walk every page and stop after 100 items ```bash nextmail contacts list-events ada@example.com --all --max 100 ``` One JSON object per line when piped ```bash nextmail contacts list-events ada@example.com --all > contacts.ndjson ``` Also available in: API [`GET /contacts/{email}/events`](https://nextmail.sh/docs/api/reference/events#get-contacts-email-events); TypeScript [`nextmail.contacts.listEvents()`](https://nextmail.sh/docs/sdk/reference/contacts#listEvents); Python [`contacts.list_events()`](https://nextmail.sh/docs/python/reference/contacts#listEvents); Ruby [`contacts.list_events`](https://nextmail.sh/docs/ruby/reference/contacts#listEvents); PHP [`contacts->listEvents`](https://nextmail.sh/docs/php/reference/contacts#listEvents); Go [`Contacts.ListEvents`](https://nextmail.sh/docs/go/reference/contacts#listEvents); Java [`contacts().listEvents`](https://nextmail.sh/docs/java/reference/contacts#listEvents); C# [`Contacts.ListEventsAsync`](https://nextmail.sh/docs/csharp/reference/contacts#listEvents). ### `nextmail contacts list-cards` List the address book as contact cards ```bash nextmail contacts list-cards [flags] ``` 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 ` stops after that many items. - Scopes: `contacts:read`. - Needs a sign-in. **Flags** - `--limit `: Cards per page, a whole number from 1 to 200. The server defaults to 50. - `--cursor `: The `nextCursor` from the previous page. Never build one yourself. - `--email `: Only the card of the saved contact with this address. - `--without-email`: True lists only the cards that have no email address. - `--kind `: `group` lists only the groups, `individual` only the people and companies. - `--group-id `: Only the cards in the group with this id. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** ```bash nextmail contacts list-cards ``` With optional flags ```bash nextmail contacts list-cards --without-email ``` Walk every page and stop after 100 items ```bash nextmail contacts list-cards --all --max 100 ``` One JSON object per line when piped ```bash nextmail contacts list-cards --all > contacts.ndjson ``` Also available in: API [`GET /contacts/cards`](https://nextmail.sh/docs/api/reference/contacts#get-contacts-cards); TypeScript [`nextmail.contacts.listCards()`](https://nextmail.sh/docs/sdk/reference/contacts#listCards); Python [`contacts.list_cards()`](https://nextmail.sh/docs/python/reference/contacts#listCards); Ruby [`contacts.list_cards`](https://nextmail.sh/docs/ruby/reference/contacts#listCards); PHP [`contacts->listCards`](https://nextmail.sh/docs/php/reference/contacts#listCards); Go [`Contacts.ListCards`](https://nextmail.sh/docs/go/reference/contacts#listCards); Java [`contacts().listCards`](https://nextmail.sh/docs/java/reference/contacts#listCards); C# [`Contacts.ListCardsAsync`](https://nextmail.sh/docs/csharp/reference/contacts#listCards). ### `nextmail contacts get-card` Get one contact card ```bash nextmail contacts get-card [flags] ``` Resolves one card with everything it holds. To find the card of a saved contact by its address, list the cards with `email`. - Scopes: `contacts:read`. - Needs a sign-in. **Arguments** - `` (required): The card id, `ccd_` and 24 characters, from `listCards` or `getCard`. **Examples** ```bash nextmail contacts get-card ccd_0123456789abcdef01234567 ``` Print the raw JSON ```bash nextmail contacts get-card ccd_0123456789abcdef01234567 --json ``` Also available in: API [`GET /contacts/cards/{id}`](https://nextmail.sh/docs/api/reference/contacts#get-contacts-cards-id); TypeScript [`nextmail.contacts.getCard()`](https://nextmail.sh/docs/sdk/reference/contacts#getCard); Python [`contacts.get_card()`](https://nextmail.sh/docs/python/reference/contacts#getCard); Ruby [`contacts.get_card`](https://nextmail.sh/docs/ruby/reference/contacts#getCard); PHP [`contacts->getCard`](https://nextmail.sh/docs/php/reference/contacts#getCard); Go [`Contacts.GetCard`](https://nextmail.sh/docs/go/reference/contacts#getCard); Java [`contacts().getCard`](https://nextmail.sh/docs/java/reference/contacts#getCard); C# [`Contacts.GetCardAsync`](https://nextmail.sh/docs/csharp/reference/contacts#getCard). ### `nextmail contacts create-card` Add a card to the address book ```bash nextmail contacts create-card [flags] ``` 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. - Scopes: `contacts:write`. - Needs a sign-in. **Flags** - `--email `: The address Nextmail 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`. - `--name `: The full name the address book shows, up to 200 characters. - `--name-parts `: The name in parts, `{ prefix, given, middle, family, suffix }`, the way phones keep it. JSON shaped as `ContactCardNameInput | null`, inline or from a file with @path. - `--nickname `: A nickname. - `--organization `: The company or organisation. - `--department `: The department within the organisation. - `--title `: The job title. - `--birthday `: `YYYY-MM-DD`, or `--MM-DD` when the year is not known. - `--notes `: Free-form notes. On a saved contact these are the notes the contact page shows. - `--emails `: Other email addresses besides `email`, each `{ value, label?, customLabel? }`. JSON shaped as `Array`, inline or from a file with @path. - `--phones `: Phone numbers, each `{ value, label?, customLabel? }`. JSON shaped as `Array`, inline or from a file with @path. - `--addresses `: Postal addresses, each `{ label?, customLabel?, street?, locality?, region?, postalCode?, country? }`. JSON shaped as `Array`, inline or from a file with @path. - `--urls `: Websites and profile links, each `{ value, label?, customLabel? }`. JSON shaped as `Array`, inline or from a file with @path. - `--kind `: `group` makes a group, the kind phones keep, which needs `name` and takes `members` instead of an address. `individual` when left out. - `--members ` (repeatable): For a group, the ids of the cards in it, up to 2,000. Groups cannot hold other groups. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash nextmail contacts create-card ``` With optional flags ```bash nextmail contacts create-card --email ada@example.com --name 'Ada Lovelace' --organization 'Analytical Engines' ``` Also available in: API [`POST /contacts/cards`](https://nextmail.sh/docs/api/reference/contacts#post-contacts-cards); TypeScript [`nextmail.contacts.createCard()`](https://nextmail.sh/docs/sdk/reference/contacts#createCard); Python [`contacts.create_card()`](https://nextmail.sh/docs/python/reference/contacts#createCard); Ruby [`contacts.create_card`](https://nextmail.sh/docs/ruby/reference/contacts#createCard); PHP [`contacts->createCard`](https://nextmail.sh/docs/php/reference/contacts#createCard); Go [`Contacts.CreateCard`](https://nextmail.sh/docs/go/reference/contacts#createCard); Java [`contacts().createCard`](https://nextmail.sh/docs/java/reference/contacts#createCard); C# [`Contacts.CreateCardAsync`](https://nextmail.sh/docs/csharp/reference/contacts#createCard). ### `nextmail contacts update-card` Change a contact card ```bash nextmail contacts update-card [flags] ``` 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. - Scopes: `contacts:write`. - Needs a sign-in. **Arguments** - `` (required): The card id, `ccd_` and 24 characters, from `listCards` or `getCard`. **Flags** - `--email `: The address Nextmail 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`. - `--name `: The full name the address book shows, up to 200 characters. - `--name-parts `: The name in parts, `{ prefix, given, middle, family, suffix }`, the way phones keep it. JSON shaped as `ContactCardNameInput | null`, inline or from a file with @path. - `--nickname `: A nickname. - `--organization `: The company or organisation. - `--department `: The department within the organisation. - `--title `: The job title. - `--birthday `: `YYYY-MM-DD`, or `--MM-DD` when the year is not known. - `--notes `: Free-form notes. On a saved contact these are the notes the contact page shows. - `--emails `: Other email addresses besides `email`, each `{ value, label?, customLabel? }`. JSON shaped as `Array`, inline or from a file with @path. - `--phones `: Phone numbers, each `{ value, label?, customLabel? }`. JSON shaped as `Array`, inline or from a file with @path. - `--addresses `: Postal addresses, each `{ label?, customLabel?, street?, locality?, region?, postalCode?, country? }`. JSON shaped as `Array`, inline or from a file with @path. - `--urls `: Websites and profile links, each `{ value, label?, customLabel? }`. JSON shaped as `Array`, inline or from a file with @path. - `--kind `: What the card already is. A person cannot become a group or a group a person, so any other value is a 422 `invalid_contact_card`. - `--members ` (repeatable): For a group, the ids of the cards in it. Given, it replaces the whole list, so send the ids already in it with the ones you add. - `--data `: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash nextmail contacts update-card ccd_0123456789abcdef01234567 ``` Print the raw JSON ```bash nextmail contacts update-card ccd_0123456789abcdef01234567 --json ``` Also available in: API [`PATCH /contacts/cards/{id}`](https://nextmail.sh/docs/api/reference/contacts#patch-contacts-cards-id); TypeScript [`nextmail.contacts.updateCard()`](https://nextmail.sh/docs/sdk/reference/contacts#updateCard); Python [`contacts.update_card()`](https://nextmail.sh/docs/python/reference/contacts#updateCard); Ruby [`contacts.update_card`](https://nextmail.sh/docs/ruby/reference/contacts#updateCard); PHP [`contacts->updateCard`](https://nextmail.sh/docs/php/reference/contacts#updateCard); Go [`Contacts.UpdateCard`](https://nextmail.sh/docs/go/reference/contacts#updateCard); Java [`contacts().updateCard`](https://nextmail.sh/docs/java/reference/contacts#updateCard); C# [`Contacts.UpdateCardAsync`](https://nextmail.sh/docs/csharp/reference/contacts#updateCard). ### `nextmail contacts delete-card` Delete a contact card ```bash nextmail contacts delete-card [flags] ``` 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. - Scopes: `contacts:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): The card id, `ccd_` and 24 characters, from `listCards` or `getCard`. **Examples** ```bash nextmail contacts delete-card ccd_0123456789abcdef01234567 ``` Skip the confirmation, for scripts ```bash nextmail contacts delete-card ccd_0123456789abcdef01234567 --yes ``` Also available in: API [`DELETE /contacts/cards/{id}`](https://nextmail.sh/docs/api/reference/contacts#delete-contacts-cards-id); TypeScript [`nextmail.contacts.deleteCard()`](https://nextmail.sh/docs/sdk/reference/contacts#deleteCard); Python [`contacts.delete_card()`](https://nextmail.sh/docs/python/reference/contacts#deleteCard); Ruby [`contacts.delete_card`](https://nextmail.sh/docs/ruby/reference/contacts#deleteCard); PHP [`contacts->deleteCard`](https://nextmail.sh/docs/php/reference/contacts#deleteCard); Go [`Contacts.DeleteCard`](https://nextmail.sh/docs/go/reference/contacts#deleteCard); Java [`contacts().deleteCard`](https://nextmail.sh/docs/java/reference/contacts#deleteCard); C# [`Contacts.DeleteCardAsync`](https://nextmail.sh/docs/csharp/reference/contacts#deleteCard). ### `nextmail contacts find-duplicate-cards` Find duplicate contact cards ```bash nextmail contacts find-duplicate-cards [flags] ``` 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. - Scopes: `contacts:read`. - Needs a sign-in. **Examples** ```bash nextmail contacts find-duplicate-cards ``` Print the raw JSON ```bash nextmail contacts find-duplicate-cards --json ``` Also available in: API [`GET /contacts/cards/duplicates`](https://nextmail.sh/docs/api/reference/contacts#get-contacts-cards-duplicates); TypeScript [`nextmail.contacts.findDuplicateCards()`](https://nextmail.sh/docs/sdk/reference/contacts#findDuplicateCards); Python [`contacts.find_duplicate_cards()`](https://nextmail.sh/docs/python/reference/contacts#findDuplicateCards); Ruby [`contacts.find_duplicate_cards`](https://nextmail.sh/docs/ruby/reference/contacts#findDuplicateCards); PHP [`contacts->findDuplicateCards`](https://nextmail.sh/docs/php/reference/contacts#findDuplicateCards); Go [`Contacts.FindDuplicateCards`](https://nextmail.sh/docs/go/reference/contacts#findDuplicateCards); Java [`contacts().findDuplicateCards`](https://nextmail.sh/docs/java/reference/contacts#findDuplicateCards); C# [`Contacts.FindDuplicateCardsAsync`](https://nextmail.sh/docs/csharp/reference/contacts#findDuplicateCards). ### `nextmail contacts merge-cards` Merge contact cards ```bash nextmail contacts merge-cards --card-ids [flags] nextmail contacts merge-cards --data [flags] ``` 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. - Scopes: `contacts:write`. - Needs a sign-in. **Arguments** - `` (required): The card to keep, from `listCards`, `getCard` or `findDuplicateCards`. **Flags** - `--card-ids ` (repeatable): The cards to fold into it, 1 to 10 of them. They are deleted once their details are kept. Required, here or in `--data`. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash nextmail contacts merge-cards ccd_0123456789abcdef01234567 --card-ids first,second ``` Read the whole body from a JSON file ```bash nextmail contacts merge-cards ccd_0123456789abcdef01234567 --data @contact.json ``` Also available in: API [`POST /contacts/cards/{id}/merge`](https://nextmail.sh/docs/api/reference/contacts#post-contacts-cards-id-merge); TypeScript [`nextmail.contacts.mergeCards()`](https://nextmail.sh/docs/sdk/reference/contacts#mergeCards); Python [`contacts.merge_cards()`](https://nextmail.sh/docs/python/reference/contacts#mergeCards); Ruby [`contacts.merge_cards`](https://nextmail.sh/docs/ruby/reference/contacts#mergeCards); PHP [`contacts->mergeCards`](https://nextmail.sh/docs/php/reference/contacts#mergeCards); Go [`Contacts.MergeCards`](https://nextmail.sh/docs/go/reference/contacts#mergeCards); Java [`contacts().mergeCards`](https://nextmail.sh/docs/java/reference/contacts#mergeCards); C# [`Contacts.MergeCardsAsync`](https://nextmail.sh/docs/csharp/reference/contacts#mergeCards). ### `nextmail contacts list-birthdays` List birthdays ```bash nextmail contacts list-birthdays --from --to [flags] ``` 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. - Scopes: `contacts:read`. - Needs a sign-in. **Flags** - `--from `: The start of the window. Required. - `--to `: The end of the window, after `from` and at most 366 days later. Required. - `--timezone ` (default `"UTC"`): IANA zone such as `Europe/London`, at most 64 characters. Defaults to `UTC`. **Examples** The required values only ```bash nextmail contacts list-birthdays --from 2026-10-01T00:00:00Z --to 2026-10-31T23:59:59Z ``` With optional flags ```bash nextmail contacts list-birthdays --from 2026-10-01T00:00:00Z --to 2026-10-31T23:59:59Z --timezone Europe/London ``` Also available in: API [`GET /contacts/birthdays`](https://nextmail.sh/docs/api/reference/contacts#get-contacts-birthdays); TypeScript [`nextmail.contacts.listBirthdays()`](https://nextmail.sh/docs/sdk/reference/contacts#listBirthdays); Python [`contacts.list_birthdays()`](https://nextmail.sh/docs/python/reference/contacts#listBirthdays); Ruby [`contacts.list_birthdays`](https://nextmail.sh/docs/ruby/reference/contacts#listBirthdays); PHP [`contacts->listBirthdays`](https://nextmail.sh/docs/php/reference/contacts#listBirthdays); Go [`Contacts.ListBirthdays`](https://nextmail.sh/docs/go/reference/contacts#listBirthdays); Java [`contacts().listBirthdays`](https://nextmail.sh/docs/java/reference/contacts#listBirthdays); C# [`Contacts.ListBirthdaysAsync`](https://nextmail.sh/docs/csharp/reference/contacts#listBirthdays). ### `nextmail contacts import-vcf` Import a contacts file ```bash nextmail contacts import-vcf [flags] ``` 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`. - Scopes: `contacts:write`. - Needs a sign-in. **Arguments** - `` (required): The .vcf file: a `Blob`, `ArrayBuffer` or `Uint8Array`. **Flags** - `--filename `: The name to show for the file in the list of imports, at most 255 characters. **Examples** The required values only ```bash nextmail contacts import-vcf ./contacts.vcf ``` With optional flags ```bash nextmail contacts import-vcf ./contacts.vcf --filename contacts.vcf ``` Also available in: API [`POST /contacts/imports`](https://nextmail.sh/docs/api/reference/contacts#post-contacts-imports); TypeScript [`nextmail.contacts.importVcf()`](https://nextmail.sh/docs/sdk/reference/contacts#importVcf); Python [`contacts.import_vcf()`](https://nextmail.sh/docs/python/reference/contacts#importVcf); Ruby [`contacts.import_vcf`](https://nextmail.sh/docs/ruby/reference/contacts#importVcf); PHP [`contacts->importVcf`](https://nextmail.sh/docs/php/reference/contacts#importVcf); Go [`Contacts.ImportVcf`](https://nextmail.sh/docs/go/reference/contacts#importVcf); Java [`contacts().importVcf`](https://nextmail.sh/docs/java/reference/contacts#importVcf); C# [`Contacts.ImportVcfAsync`](https://nextmail.sh/docs/csharp/reference/contacts#importVcf). ### `nextmail contacts list-imports` List contacts imports ```bash nextmail contacts list-imports [flags] ``` 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 ` stops after that many items. - Scopes: `contacts:read`. - Needs a sign-in. **Flags** - `--limit ` (default `25`): Imports per page, a whole number from 1 to 100. The server defaults to 25. - `--cursor `: The `nextCursor` from the previous page. Never build one yourself. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** ```bash nextmail contacts list-imports ``` With optional flags ```bash nextmail contacts list-imports --limit 50 ``` Walk every page and stop after 100 items ```bash nextmail contacts list-imports --all --max 100 ``` One JSON object per line when piped ```bash nextmail contacts list-imports --all > contacts.ndjson ``` Also available in: API [`GET /contacts/imports`](https://nextmail.sh/docs/api/reference/contacts#get-contacts-imports); TypeScript [`nextmail.contacts.listImports()`](https://nextmail.sh/docs/sdk/reference/contacts#listImports); Python [`contacts.list_imports()`](https://nextmail.sh/docs/python/reference/contacts#listImports); Ruby [`contacts.list_imports`](https://nextmail.sh/docs/ruby/reference/contacts#listImports); PHP [`contacts->listImports`](https://nextmail.sh/docs/php/reference/contacts#listImports); Go [`Contacts.ListImports`](https://nextmail.sh/docs/go/reference/contacts#listImports); Java [`contacts().listImports`](https://nextmail.sh/docs/java/reference/contacts#listImports); C# [`Contacts.ListImportsAsync`](https://nextmail.sh/docs/csharp/reference/contacts#listImports). ### `nextmail contacts get-import` Get a contacts import ```bash nextmail contacts get-import [flags] ``` 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. - Scopes: `contacts:read`. - Needs a sign-in. **Arguments** - `` (required): Contacts import id, `iimp_` followed by 24 hex characters. **Examples** ```bash nextmail contacts get-import iimp_7b1e4d8f60a5c7b92d3f9c2a ``` Print the raw JSON ```bash nextmail contacts get-import iimp_7b1e4d8f60a5c7b92d3f9c2a --json ``` Also available in: API [`GET /contacts/imports/{id}`](https://nextmail.sh/docs/api/reference/contacts#get-contacts-imports-id); TypeScript [`nextmail.contacts.getImport()`](https://nextmail.sh/docs/sdk/reference/contacts#getImport); Python [`contacts.get_import()`](https://nextmail.sh/docs/python/reference/contacts#getImport); Ruby [`contacts.get_import`](https://nextmail.sh/docs/ruby/reference/contacts#getImport); PHP [`contacts->getImport`](https://nextmail.sh/docs/php/reference/contacts#getImport); Go [`Contacts.GetImport`](https://nextmail.sh/docs/go/reference/contacts#getImport); Java [`contacts().getImport`](https://nextmail.sh/docs/java/reference/contacts#getImport); C# [`Contacts.GetImportAsync`](https://nextmail.sh/docs/csharp/reference/contacts#getImport). ### `nextmail contacts undo-import` Remove what a contacts import added ```bash nextmail contacts undo-import [flags] ``` 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. - Scopes: `contacts:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Contacts import id, `iimp_` followed by 24 hex characters. **Examples** ```bash nextmail contacts undo-import iimp_7b1e4d8f60a5c7b92d3f9c2a ``` Skip the confirmation, for scripts ```bash nextmail contacts undo-import iimp_7b1e4d8f60a5c7b92d3f9c2a --yes ``` Also available in: API [`POST /contacts/imports/{id}/undo`](https://nextmail.sh/docs/api/reference/contacts#post-contacts-imports-id-undo); TypeScript [`nextmail.contacts.undoImport()`](https://nextmail.sh/docs/sdk/reference/contacts#undoImport); Python [`contacts.undo_import()`](https://nextmail.sh/docs/python/reference/contacts#undoImport); Ruby [`contacts.undo_import`](https://nextmail.sh/docs/ruby/reference/contacts#undoImport); PHP [`contacts->undoImport`](https://nextmail.sh/docs/php/reference/contacts#undoImport); Go [`Contacts.UndoImport`](https://nextmail.sh/docs/go/reference/contacts#undoImport); Java [`contacts().undoImport`](https://nextmail.sh/docs/java/reference/contacts#undoImport); C# [`Contacts.UndoImportAsync`](https://nextmail.sh/docs/csharp/reference/contacts#undoImport).