---
title: "Contacts"
description: "The address book this mailbox writes to."
url: "https://nextmail.sh/docs/mcp/tools/contacts"
area: "MCP server"
category: "Tools"
---

# Contacts

The address book this mailbox writes to.

## Contacts tools

| Tool | What it does |
| --- | --- |
| listContacts | The people this mailbox writes to, newest correspondence first, a page at a time. Search by name or address, narrow to one audience, or separate the ones somebody added from the ones that were recorded. |
| getContact | One contact by email address, with its notes in full and every audience it sits in. |
| createContact | Add a contact by hand. One contact per address, so an address already here is refused rather than written twice. The new contact joins the default audience. |
| updateContact | Change a contact's name or the notes kept against it. Passing null clears a field, leaving it out leaves it alone. |
| deleteContact | Delete somebody from the contacts the way Delete does on the Contacts page: the saved contact goes with its notes, photo and audiences, and the address is hidden so a send does not record it again. It can be an address only ever seen in mail. |
| listPeople | Everyone on the Contacts page, a page at a time: the saved contacts and every address seen in mail, with thread counts and when mail last moved. Sort by recent, name or threads, search, or ask for only the blocked ones. |
| saveContact | Add to contacts or Keep in contacts: saves an address that is not a contact yet, keeps one recorded from a send as saved by hand, and brings back a deleted one. |
| deleteContacts | Delete up to 200 people in one call, each the way deleteContact deletes one. |
| blockContact | Put an address on the workspace blocklist so mail from it is refused. An address a rule already blocks is left as it is and the rule is named. |
| unblockContact | Take every workspace blocklist rule that blocks an address off the list. A whole-domain rule unblocks the whole domain, and the answer says so. |
| listContactThreads | The conversations with one person, in every folder, newest first, a page at a time, with a search inside them. |
| getContactActivity | How mail with one person has gone over a window: received and sent per day, hour or minute, threads waiting on your reply, and the median reply time each way. |
| setContactPhoto | Set the photo of a saved contact from an image in base64, replacing any there was. |
| removeContactPhoto | Remove the photo of a saved contact and delete the stored image. |
| listContactCards | The address book as cards, newest first, a page at a time: every saved contact with its phone numbers, addresses, organisation and birthday, plus the cards that have no email address. |
| getContactCard | One card in full, by its id or by the address of a saved contact. |
| createContactCard | Add a card. With an email address it is a saved contact as well; without one it keeps a name and a phone number on their own. |
| updateContactCard | Change a card. A list you pass, such as phones, replaces the whole list, and a saved contact keeps its address. |
| deleteContactCard | Delete a card from the address book and from every phone that syncs it. On a saved contact it deletes the contact too. |
| listContactImports | The contacts files and address books brought in, newest first, with how many contacts each added, found already here and left out. |
| getContactImport | One contacts import with its report: what it read and what it left out, and why. |
| undoContactImport | Remove every card one contacts import added. Contacts saved before it stay. In the app’s chat it always asks first. |
| findDuplicateContacts | Cards that look like the same person: a shared email address or phone number, or the same full name, with the most complete card first. |
| mergeContactCards | Fold the cards of one person into one and delete the rest, keeping every address, number and link. In the app’s chat it always asks first. |
| listBirthdays | The birthdays in the address book between two dates, with the age each person turns when the card holds the year. |

> The workspace owner sees and edits every contact. Anyone else, a team member or a password sign-in, sees and edits only the contacts they added or wrote to themselves, and adding an address somebody else already holds is refused. A contact is recorded automatically the first time a message goes out to an address from the app composer; mail arriving from an address writes nothing.

> The address is the identity and there is no id. `updateContact` therefore cannot change it, and moving somebody to a new address is a `createContact` and a `deleteContact`. `createContact` takes no `source`: anything made here is `manual`, and a send never downgrades that back to `auto`.

> None of this sends anything or subscribes anybody to anything, and `deleteContact` unsubscribes nobody, because this mailbox holds no subscription state at all. A deleted address stays hidden, so writing to it again does not record it again, until `createContact` or `saveContact` brings it back.

> `listPeople` lists the addresses seen in mail only for somebody who may read the mail and is not limited to some addresses; anyone else gets their saved contacts alone. `blockContact` and `unblockContact` change the workspace blocklist, so they need the permission to change settings rather than contacts. `deleteContacts` always asks before it runs, like `deleteContact`; saving, blocking and unblocking ask unless you asked for them. `setContactPhoto` takes the image in base64, and only the workspace owner sets or removes a contact photo from a client.

> Every saved contact is also a card in the address book that phones and computers sync over CardDAV, so a change made here reaches them on their next sync. `createContactCard` and `updateContactCard` ask unless you asked for them, and `deleteContactCard` always asks first.

> No tool uploads a contacts file, because a tool call carries no file. Upload a .vcf file on the Contacts page of the app or with `POST /contacts/imports`, then read or undo the import here. Imported contacts join no audience.

> Groups are cards too: `createContactCard` with `kind` set to `group` and `members` makes one, and `listContactCards` takes `kind` and `groupId`. `findDuplicateContacts` and `listBirthdays` only read, and `mergeContactCards` always asks first.

## Reference

### `listContacts`

The people this mailbox writes to. A contact is recorded automatically the first time a message goes out to an address, and one can also be added by hand. Newest correspondence first. Pass q to search the name and the address, audienceId to see one list only, and source to separate the ones somebody added from the ones that were recorded. The owner of the mailbox sees every contact; anyone else sees only the contacts they added or wrote to themselves. One page at a time: when more follow, the last line gives a cursor to pass back, with the same filters, for the next page.

- Scopes: `contacts:read`.
- The app's assistant runs it without asking.
- Toolkit: `contacts`.

**Inputs**

- `q` (`string`, up to 200 characters)
- `source` (`string`, one of `"manual"`, `"auto"`, `"form"`)
- `audienceId` (`string`)
- `limit` (`integer`, at least 1, at most 200, default `50`)
- `cursor` (`string`)

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), [`nextmail.contacts.listAll()`](https://nextmail.sh/docs/sdk/reference/contacts#listAll), [`nextmail.contacts.iterate()`](https://nextmail.sh/docs/sdk/reference/contacts#iterate); Python [`contacts.list()`](https://nextmail.sh/docs/python/reference/contacts#list), [`contacts.list_all()`](https://nextmail.sh/docs/python/reference/contacts#listAll), [`contacts.iterate()`](https://nextmail.sh/docs/python/reference/contacts#iterate); Ruby [`contacts.list`](https://nextmail.sh/docs/ruby/reference/contacts#list), [`contacts.list_all`](https://nextmail.sh/docs/ruby/reference/contacts#listAll), [`contacts.iterate`](https://nextmail.sh/docs/ruby/reference/contacts#iterate); PHP [`contacts->list`](https://nextmail.sh/docs/php/reference/contacts#list), [`contacts->listAll`](https://nextmail.sh/docs/php/reference/contacts#listAll), [`contacts->iterate`](https://nextmail.sh/docs/php/reference/contacts#iterate); Go [`Contacts.List`](https://nextmail.sh/docs/go/reference/contacts#list), [`Contacts.ListAll`](https://nextmail.sh/docs/go/reference/contacts#listAll), [`Contacts.Iterate`](https://nextmail.sh/docs/go/reference/contacts#iterate); Java [`contacts().list`](https://nextmail.sh/docs/java/reference/contacts#list), [`contacts().listAll`](https://nextmail.sh/docs/java/reference/contacts#listAll), [`contacts().iterate`](https://nextmail.sh/docs/java/reference/contacts#iterate); C# [`Contacts.ListAsync`](https://nextmail.sh/docs/csharp/reference/contacts#list), [`Contacts.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/contacts#listAll), [`Contacts.IterateAsync`](https://nextmail.sh/docs/csharp/reference/contacts#iterate).

### `getContact`

One contact, by email address. Contacts are addressed here by address and never by id, because the address is the part a person knows and the part the API publishes. Returns the notes in full, the custom fields and every audience the contact sits in. A connection that may also read forms gets the sign-ups this address sent through sign-up forms, newest first and at most 20: the form, whether the person was added or still has to confirm, the page it came from and every answer. Anybody but the workspace owner sees only the sign-ups of forms they made.

- Scopes: `contacts:read`.
- The app's assistant runs it without asking.
- Toolkit: `contacts`.

**Inputs**

- `email` (`string`, required, format `email`)

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

### `createContact`

Add a contact by hand. The address is the identity: one contact per address per mailbox, so this refuses an address that is already here rather than writing a second row, and updateContact changes the one that is there. The new contact joins the default audience, which holds every contact on the mailbox; addContactToAudience puts it in a list of your own. attributes sets custom fields, which automations can read and branch on. Adding a contact sends nothing and subscribes nobody to anything.

- Scopes: `contacts:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `contacts`.

**Inputs**

- `email` (`string`, required, format `email`)
- `name` (`string`, up to 200 characters)
- `notes` (`string`, up to 5000 characters)
- `attributes` (`Record<string, string>`): Custom fields to set on the contact, as an object of keys and text values. A key starts with a letter and holds up to 64 letters, digits and underscores, a value is text of at most 500 characters, and a contact holds at most 50 fields. Null or an empty string removes a field, and a field left out keeps its value.

Also available in: API [`PATCH /contacts/{email}`](https://nextmail.sh/docs/api/reference/contacts#patch-contacts-email), [`POST /contacts`](https://nextmail.sh/docs/api/reference/contacts#post-contacts), [`PUT /contacts/{email}`](https://nextmail.sh/docs/api/reference/contacts#put-contacts-email); TypeScript [`nextmail.contacts.update()`](https://nextmail.sh/docs/sdk/reference/contacts#update), [`nextmail.contacts.create()`](https://nextmail.sh/docs/sdk/reference/contacts#create), [`nextmail.contacts.save()`](https://nextmail.sh/docs/sdk/reference/contacts#save); Python [`contacts.update()`](https://nextmail.sh/docs/python/reference/contacts#update), [`contacts.create()`](https://nextmail.sh/docs/python/reference/contacts#create), [`contacts.save()`](https://nextmail.sh/docs/python/reference/contacts#save); Ruby [`contacts.update`](https://nextmail.sh/docs/ruby/reference/contacts#update), [`contacts.create`](https://nextmail.sh/docs/ruby/reference/contacts#create), [`contacts.save`](https://nextmail.sh/docs/ruby/reference/contacts#save); PHP [`contacts->update`](https://nextmail.sh/docs/php/reference/contacts#update), [`contacts->create`](https://nextmail.sh/docs/php/reference/contacts#create), [`contacts->save`](https://nextmail.sh/docs/php/reference/contacts#save); Go [`Contacts.Update`](https://nextmail.sh/docs/go/reference/contacts#update), [`Contacts.Create`](https://nextmail.sh/docs/go/reference/contacts#create), [`Contacts.Save`](https://nextmail.sh/docs/go/reference/contacts#save); Java [`contacts().update`](https://nextmail.sh/docs/java/reference/contacts#update), [`contacts().create`](https://nextmail.sh/docs/java/reference/contacts#create), [`contacts().save`](https://nextmail.sh/docs/java/reference/contacts#save); C# [`Contacts.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/contacts#update), [`Contacts.CreateAsync`](https://nextmail.sh/docs/csharp/reference/contacts#create), [`Contacts.SaveAsync`](https://nextmail.sh/docs/csharp/reference/contacts#save).

### `updateContact`

Change a contact’s name, the notes kept against it or its custom fields. Passing null clears a field; leaving it out leaves it alone. attributes changes only the custom fields it names. The address cannot be changed here. A contact IS its address, so a different address is a different contact: createContact makes it and deleteContact removes the old one.

- Scopes: `contacts:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `contacts`.

**Inputs**

- `email` (`string`, required, format `email`)
- `name` (`string`, nullable, up to 200 characters)
- `notes` (`string`, nullable, up to 5000 characters)
- `attributes` (`Record<string, string>`): Custom fields to set on the contact, as an object of keys and text values. A key starts with a letter and holds up to 64 letters, digits and underscores, a value is text of at most 500 characters, and a contact holds at most 50 fields. Null or an empty string removes a field, and a field left out keeps its value.

Also available in: API [`PATCH /contacts/{email}`](https://nextmail.sh/docs/api/reference/contacts#patch-contacts-email), [`POST /contacts`](https://nextmail.sh/docs/api/reference/contacts#post-contacts), [`PUT /contacts/{email}`](https://nextmail.sh/docs/api/reference/contacts#put-contacts-email); TypeScript [`nextmail.contacts.update()`](https://nextmail.sh/docs/sdk/reference/contacts#update), [`nextmail.contacts.create()`](https://nextmail.sh/docs/sdk/reference/contacts#create), [`nextmail.contacts.save()`](https://nextmail.sh/docs/sdk/reference/contacts#save); Python [`contacts.update()`](https://nextmail.sh/docs/python/reference/contacts#update), [`contacts.create()`](https://nextmail.sh/docs/python/reference/contacts#create), [`contacts.save()`](https://nextmail.sh/docs/python/reference/contacts#save); Ruby [`contacts.update`](https://nextmail.sh/docs/ruby/reference/contacts#update), [`contacts.create`](https://nextmail.sh/docs/ruby/reference/contacts#create), [`contacts.save`](https://nextmail.sh/docs/ruby/reference/contacts#save); PHP [`contacts->update`](https://nextmail.sh/docs/php/reference/contacts#update), [`contacts->create`](https://nextmail.sh/docs/php/reference/contacts#create), [`contacts->save`](https://nextmail.sh/docs/php/reference/contacts#save); Go [`Contacts.Update`](https://nextmail.sh/docs/go/reference/contacts#update), [`Contacts.Create`](https://nextmail.sh/docs/go/reference/contacts#create), [`Contacts.Save`](https://nextmail.sh/docs/go/reference/contacts#save); Java [`contacts().update`](https://nextmail.sh/docs/java/reference/contacts#update), [`contacts().create`](https://nextmail.sh/docs/java/reference/contacts#create), [`contacts().save`](https://nextmail.sh/docs/java/reference/contacts#save); C# [`Contacts.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/contacts#update), [`Contacts.CreateAsync`](https://nextmail.sh/docs/csharp/reference/contacts#create), [`Contacts.SaveAsync`](https://nextmail.sh/docs/csharp/reference/contacts#save).

### `deleteContact`

Delete somebody from the contacts, the way Delete does on the Contacts page. The saved contact goes, with its notes, its photo and every audience it was in, and the address is hidden: it leaves the people list and the recipient suggestions, and writing to it again does not record it again. The address can be somebody who was only ever seen in mail. createContact or saveContact brings it back. It deletes no mail and unsubscribes nobody, because this mailbox holds no subscription state. Anybody but the workspace owner deletes only contacts they added, and hides nothing.

- Scopes: `contacts:write`.
- The app's assistant always asks first.
- Toolkit: `contacts`.

**Inputs**

- `email` (`string`, required, format `email`)

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

### `listPeople`

Everyone on the Contacts page: the saved contacts and, for somebody who may read the mail, every address seen in it as a sender or a recipient, with how many threads each shares with the mailbox and when mail last moved. listContacts is only the saved ones. Sort by recent (the default), name or threads. Pass q to search names, addresses and notes, and blocked: true for only the people the workspace blocklist blocks, whole-domain rules included. Deleted addresses are left out, and so are the mailbox's own addresses. Anybody but the workspace owner sees only the saved contacts they added, and the addresses seen in mail are listed only for the owner, through an app that reaches every address. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

- Scopes: `contacts:read`.
- The app's assistant runs it without asking.
- Toolkit: `contacts`.

**Inputs**

- `q` (`string`, up to 200 characters)
- `sort` (`string`, one of `"recent"`, `"name"`, `"threads"`)
- `blocked` (`boolean`)
- `limit` (`integer`, at least 1, at most 100)
- `cursor` (`string`)

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), [`nextmail.contacts.listAllPeople()`](https://nextmail.sh/docs/sdk/reference/contacts#listAllPeople), [`nextmail.contacts.iteratePeople()`](https://nextmail.sh/docs/sdk/reference/contacts#iteratePeople); Python [`contacts.list_people()`](https://nextmail.sh/docs/python/reference/contacts#listPeople), [`contacts.list_all_people()`](https://nextmail.sh/docs/python/reference/contacts#listAllPeople), [`contacts.iterate_people()`](https://nextmail.sh/docs/python/reference/contacts#iteratePeople); Ruby [`contacts.list_people`](https://nextmail.sh/docs/ruby/reference/contacts#listPeople), [`contacts.list_all_people`](https://nextmail.sh/docs/ruby/reference/contacts#listAllPeople), [`contacts.iterate_people`](https://nextmail.sh/docs/ruby/reference/contacts#iteratePeople); PHP [`contacts->listPeople`](https://nextmail.sh/docs/php/reference/contacts#listPeople), [`contacts->listAllPeople`](https://nextmail.sh/docs/php/reference/contacts#listAllPeople), [`contacts->iteratePeople`](https://nextmail.sh/docs/php/reference/contacts#iteratePeople); Go [`Contacts.ListPeople`](https://nextmail.sh/docs/go/reference/contacts#listPeople), [`Contacts.ListAllPeople`](https://nextmail.sh/docs/go/reference/contacts#listAllPeople), [`Contacts.IteratePeople`](https://nextmail.sh/docs/go/reference/contacts#iteratePeople); Java [`contacts().listPeople`](https://nextmail.sh/docs/java/reference/contacts#listPeople), [`contacts().listAllPeople`](https://nextmail.sh/docs/java/reference/contacts#listAllPeople), [`contacts().iteratePeople`](https://nextmail.sh/docs/java/reference/contacts#iteratePeople); C# [`Contacts.ListPeopleAsync`](https://nextmail.sh/docs/csharp/reference/contacts#listPeople), [`Contacts.ListAllPeopleAsync`](https://nextmail.sh/docs/csharp/reference/contacts#listAllPeople), [`Contacts.IteratePeopleAsync`](https://nextmail.sh/docs/csharp/reference/contacts#iteratePeople).

### `saveContact`

Save somebody as a contact, the way Add to contacts and Keep in contacts do on the Contacts page. An address that is not a contact yet becomes one; one recorded from a send is kept as added by hand; one already saved stays as it is. A name given replaces the stored name and one left out keeps it; notes given replace the stored notes, null clears them. attributes sets the custom fields it names and keeps the rest. A deleted address is brought back. Adding a contact sends nothing and subscribes nobody.

- Scopes: `contacts:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `contacts`.

**Inputs**

- `email` (`string`, required, format `email`)
- `name` (`string`, up to 200 characters)
- `notes` (`string`, nullable, up to 5000 characters)
- `attributes` (`Record<string, string>`): Custom fields to set on the contact, as an object of keys and text values. A key starts with a letter and holds up to 64 letters, digits and underscores, a value is text of at most 500 characters, and a contact holds at most 50 fields. Null or an empty string removes a field, and a field left out keeps its value.

Also available in: API [`PATCH /contacts/{email}`](https://nextmail.sh/docs/api/reference/contacts#patch-contacts-email), [`POST /contacts`](https://nextmail.sh/docs/api/reference/contacts#post-contacts), [`PUT /contacts/{email}`](https://nextmail.sh/docs/api/reference/contacts#put-contacts-email); TypeScript [`nextmail.contacts.update()`](https://nextmail.sh/docs/sdk/reference/contacts#update), [`nextmail.contacts.create()`](https://nextmail.sh/docs/sdk/reference/contacts#create), [`nextmail.contacts.save()`](https://nextmail.sh/docs/sdk/reference/contacts#save); Python [`contacts.update()`](https://nextmail.sh/docs/python/reference/contacts#update), [`contacts.create()`](https://nextmail.sh/docs/python/reference/contacts#create), [`contacts.save()`](https://nextmail.sh/docs/python/reference/contacts#save); Ruby [`contacts.update`](https://nextmail.sh/docs/ruby/reference/contacts#update), [`contacts.create`](https://nextmail.sh/docs/ruby/reference/contacts#create), [`contacts.save`](https://nextmail.sh/docs/ruby/reference/contacts#save); PHP [`contacts->update`](https://nextmail.sh/docs/php/reference/contacts#update), [`contacts->create`](https://nextmail.sh/docs/php/reference/contacts#create), [`contacts->save`](https://nextmail.sh/docs/php/reference/contacts#save); Go [`Contacts.Update`](https://nextmail.sh/docs/go/reference/contacts#update), [`Contacts.Create`](https://nextmail.sh/docs/go/reference/contacts#create), [`Contacts.Save`](https://nextmail.sh/docs/go/reference/contacts#save); Java [`contacts().update`](https://nextmail.sh/docs/java/reference/contacts#update), [`contacts().create`](https://nextmail.sh/docs/java/reference/contacts#create), [`contacts().save`](https://nextmail.sh/docs/java/reference/contacts#save); C# [`Contacts.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/contacts#update), [`Contacts.CreateAsync`](https://nextmail.sh/docs/csharp/reference/contacts#create), [`Contacts.SaveAsync`](https://nextmail.sh/docs/csharp/reference/contacts#save).

### `deleteContacts`

Delete up to 200 people from the contacts in one call, the way deleteContact does one: each saved contact goes with its notes, photo and audiences, and each address is hidden so a send does not record it again. Addresses that were only seen in mail are hidden too. It cannot be undone, and it deletes no mail. Anybody but the workspace owner deletes only contacts they added, and hides nothing.

- Scopes: `contacts:write`.
- The app's assistant always asks first.
- Toolkit: `contacts`.

**Inputs**

- `emails` (`string[]`, required, 1 to 200 items)

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

### `blockContact`

Block an address, the way Block does on a contact: it goes on the workspace blocklist, and mail from it is refused from then on. A plus tag is dropped, so blocking ada+news@example.com blocks ada@example.com. An address that a rule already blocks, a whole-domain rule included, is left as it is and the rule is named.

- Scopes: `settings:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `contacts`.

**Inputs**

- `email` (`string`, required, format `email`)

### `unblockContact`

Unblock an address, the way Unblock does on a contact: every rule on the workspace blocklist that blocks it is taken off. When the rule is a whole domain, that unblocks everybody at the domain, and the answer says so. Rules set in the settings for one address or one domain are not touched.

- Scopes: `settings:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `contacts`.

**Inputs**

- `email` (`string`, required, format `email`)

### `listContactThreads`

The conversations with one person, the Mail tab on a contact: every thread they wrote or were written to, in every folder, newest first unless sort says otherwise. Pass q to search inside those threads. The address does not have to be a saved contact. A thread whose newest message arrived encrypted is marked on its line. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

- Scopes: `threads:read`.
- The app's assistant runs it without asking.
- Toolkit: `contacts`.

**Inputs**

- `email` (`string`, required, format `email`)
- `q` (`string`, up to 200 characters)
- `sort` (`string`, one of `"newest"`, `"oldest"`, `"sender"`, `"subject"`)
- `limit` (`integer`, at least 1, at most 100)
- `cursor` (`string`)

### `getContactActivity`

How mail with one person has gone over a window that ends now, the Activity tab on a contact: messages received from them and sent to them per day, hour or minute, the threads that moved, how many threads wait on a reply from you, when each side last wrote, and the median time each side takes to answer. minutes sets the window (90 days by default), and offsetMinutes is the reader's UTC offset so days fall on their calendar. Mail in the bin or spam is left out.

- Scopes: `threads:read`.
- The app's assistant runs it without asking.
- Toolkit: `contacts`.

**Inputs**

- `email` (`string`, required, format `email`)
- `minutes` (`integer`, at least 1, at most 10540800)
- `grain` (`string`, one of `"minute"`, `"hour"`, `"day"`)
- `offsetMinutes` (`integer`, at least -840, at most 840)

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

### `setContactPhoto`

Set the photo of a saved contact, replacing any there was, as the contact page does. Pass the picture in base64 as image, with its type as contentType, up to 5 MB. Only the workspace owner sets contact photos from an app.

- Scopes: `contacts:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `contacts`.

**Inputs**

- `email` (`string`, required, format `email`)
- `image` (`string`, required, 1 to 7340032 characters): The image in base64, or as a data: URL.
- `contentType` (`string`, required, 1 to 100 characters): The type of the image, such as image/png.

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

### `removeContactPhoto`

Remove the photo of a saved contact and delete the stored image. Removing a photo from a contact that has none changes nothing.

- Scopes: `contacts:write`.
- The app's assistant always asks first.
- Toolkit: `contacts`.

**Inputs**

- `email` (`string`, required, format `email`)

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

### `listContactCards`

The address book as cards: every saved contact with its phone numbers, postal addresses, organisation and birthday, plus cards that have no email address, such as a plumber saved on a phone. Newest first. Pass withoutEmail to list only the cards with no address. getContactCard finds the card of one contact by email. Groups are cards too: kind: group lists only the groups, and groupId lists the cards in one group. One page at a time: when more follow, the last line gives a cursor to pass back.

- Scopes: `contacts:read`.
- The app's assistant runs it without asking.
- Toolkit: `contacts`.

**Inputs**

- `withoutEmail` (`boolean`)
- `kind` (`string`, one of `"individual"`, `"group"`)
- `groupId` (`string`, 1 to 64 characters): Only the cards in the group with this id.
- `limit` (`integer`, at least 1, at most 200)
- `cursor` (`string`)

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), [`nextmail.contacts.listAllCards()`](https://nextmail.sh/docs/sdk/reference/contacts#listAllCards), [`nextmail.contacts.iterateCards()`](https://nextmail.sh/docs/sdk/reference/contacts#iterateCards); Python [`contacts.list_cards()`](https://nextmail.sh/docs/python/reference/contacts#listCards), [`contacts.list_all_cards()`](https://nextmail.sh/docs/python/reference/contacts#listAllCards), [`contacts.iterate_cards()`](https://nextmail.sh/docs/python/reference/contacts#iterateCards); Ruby [`contacts.list_cards`](https://nextmail.sh/docs/ruby/reference/contacts#listCards), [`contacts.list_all_cards`](https://nextmail.sh/docs/ruby/reference/contacts#listAllCards), [`contacts.iterate_cards`](https://nextmail.sh/docs/ruby/reference/contacts#iterateCards); PHP [`contacts->listCards`](https://nextmail.sh/docs/php/reference/contacts#listCards), [`contacts->listAllCards`](https://nextmail.sh/docs/php/reference/contacts#listAllCards), [`contacts->iterateCards`](https://nextmail.sh/docs/php/reference/contacts#iterateCards); Go [`Contacts.ListCards`](https://nextmail.sh/docs/go/reference/contacts#listCards), [`Contacts.ListAllCards`](https://nextmail.sh/docs/go/reference/contacts#listAllCards), [`Contacts.IterateCards`](https://nextmail.sh/docs/go/reference/contacts#iterateCards); Java [`contacts().listCards`](https://nextmail.sh/docs/java/reference/contacts#listCards), [`contacts().listAllCards`](https://nextmail.sh/docs/java/reference/contacts#listAllCards), [`contacts().iterateCards`](https://nextmail.sh/docs/java/reference/contacts#iterateCards); C# [`Contacts.ListCardsAsync`](https://nextmail.sh/docs/csharp/reference/contacts#listCards), [`Contacts.ListAllCardsAsync`](https://nextmail.sh/docs/csharp/reference/contacts#listAllCards), [`Contacts.IterateCardsAsync`](https://nextmail.sh/docs/csharp/reference/contacts#iterateCards).

### `getContactCard`

One card in full: phone numbers, other email addresses, postal addresses, websites, organisation, job title, birthday and notes. Pass id, or email for the card of a saved contact.

- Scopes: `contacts:read`.
- The app's assistant runs it without asking.
- Toolkit: `contacts`.

**Inputs**

- `id` (`string`, 1 to 64 characters)
- `email` (`string`, 1 to 320 characters)

Also available in: API [`GET /contacts/cards`](https://nextmail.sh/docs/api/reference/contacts#get-contacts-cards), [`GET /contacts/cards/{id}`](https://nextmail.sh/docs/api/reference/contacts#get-contacts-cards-id); TypeScript [`nextmail.contacts.listCards()`](https://nextmail.sh/docs/sdk/reference/contacts#listCards), [`nextmail.contacts.listAllCards()`](https://nextmail.sh/docs/sdk/reference/contacts#listAllCards), [`nextmail.contacts.iterateCards()`](https://nextmail.sh/docs/sdk/reference/contacts#iterateCards), [`nextmail.contacts.getCard()`](https://nextmail.sh/docs/sdk/reference/contacts#getCard); Python [`contacts.list_cards()`](https://nextmail.sh/docs/python/reference/contacts#listCards), [`contacts.list_all_cards()`](https://nextmail.sh/docs/python/reference/contacts#listAllCards), [`contacts.iterate_cards()`](https://nextmail.sh/docs/python/reference/contacts#iterateCards), [`contacts.get_card()`](https://nextmail.sh/docs/python/reference/contacts#getCard); Ruby [`contacts.list_cards`](https://nextmail.sh/docs/ruby/reference/contacts#listCards), [`contacts.list_all_cards`](https://nextmail.sh/docs/ruby/reference/contacts#listAllCards), [`contacts.iterate_cards`](https://nextmail.sh/docs/ruby/reference/contacts#iterateCards), [`contacts.get_card`](https://nextmail.sh/docs/ruby/reference/contacts#getCard); PHP [`contacts->listCards`](https://nextmail.sh/docs/php/reference/contacts#listCards), [`contacts->listAllCards`](https://nextmail.sh/docs/php/reference/contacts#listAllCards), [`contacts->iterateCards`](https://nextmail.sh/docs/php/reference/contacts#iterateCards), [`contacts->getCard`](https://nextmail.sh/docs/php/reference/contacts#getCard); Go [`Contacts.ListCards`](https://nextmail.sh/docs/go/reference/contacts#listCards), [`Contacts.ListAllCards`](https://nextmail.sh/docs/go/reference/contacts#listAllCards), [`Contacts.IterateCards`](https://nextmail.sh/docs/go/reference/contacts#iterateCards), [`Contacts.GetCard`](https://nextmail.sh/docs/go/reference/contacts#getCard); Java [`contacts().listCards`](https://nextmail.sh/docs/java/reference/contacts#listCards), [`contacts().listAllCards`](https://nextmail.sh/docs/java/reference/contacts#listAllCards), [`contacts().iterateCards`](https://nextmail.sh/docs/java/reference/contacts#iterateCards), [`contacts().getCard`](https://nextmail.sh/docs/java/reference/contacts#getCard); C# [`Contacts.ListCardsAsync`](https://nextmail.sh/docs/csharp/reference/contacts#listCards), [`Contacts.ListAllCardsAsync`](https://nextmail.sh/docs/csharp/reference/contacts#listAllCards), [`Contacts.IterateCardsAsync`](https://nextmail.sh/docs/csharp/reference/contacts#iterateCards), [`Contacts.GetCardAsync`](https://nextmail.sh/docs/csharp/reference/contacts#getCard).

### `createContactCard`

Add a card to the address book. With email it is also a saved contact, and an address already known from mail becomes saved. Without one it is a card on its own, for a name and phone number. A card needs a name, an email address, a phone number or an organisation. kind: group with a name and members (card ids) makes a group, the groups phones keep. Adding a card sends nothing.

- Scopes: `contacts:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `contacts`.

**Inputs**

- `email` (`string`, nullable, up to 320 characters, format `email`): The address Nextmail knows the contact by. Give it to a card that has none and the card becomes a saved contact. A saved contact keeps its address, so put any other address in emails.
- `name` (`string`, nullable, up to 200 characters): The full name the address book shows.
- `nameParts` (`object`, nullable): The name in parts, the way phones keep it. Left out, phones split name themselves.
  - `prefix` (`string`, nullable, up to 200 characters, default `null`): A title before the name, such as Dr.
  - `given` (`string`, nullable, up to 200 characters, default `null`): The first name.
  - `middle` (`string`, nullable, up to 200 characters, default `null`): Any middle names.
  - `family` (`string`, nullable, up to 200 characters, default `null`): The surname.
  - `suffix` (`string`, nullable, up to 200 characters, default `null`): Anything after the name, such as Jr.
- `nickname` (`string`, nullable, up to 200 characters): A nickname.
- `organization` (`string`, nullable, up to 200 characters): The company or organisation.
- `department` (`string`, nullable, up to 200 characters): The department within the organisation.
- `title` (`string`, nullable, up to 200 characters): The job title.
- `birthday` (`string`, nullable, pattern `^(?:\d{4}-|--)(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$`): YYYY-MM-DD, or --MM-DD when the year is not known.
- `notes` (`string`, nullable, up to 5000 characters): Free-form notes. On a saved contact these are the notes the contact page shows.
- `emails` (`object[]`, up to 50 items): Other email addresses, besides email. Given, it replaces the whole list.
  - `value` (`string`, required, up to 320 characters, format `email`): The email address.
  - `label` (`string`, one of `"home"`, `"work"`, `"mobile"`, `"main"`, `"fax"`, `"pager"`, `"other"`, default `"other"`): What the entry is for: home, work, mobile, main, fax, pager or other.
  - `customLabel` (`string`, nullable, up to 60 characters, default `null`): A label of your own, such as Assistant. Address books that support it show it instead of label.
- `phones` (`object[]`, up to 50 items): Phone numbers. Given, it replaces the whole list.
  - `value` (`string`, required, 1 to 320 characters): The number or the link.
  - `label` (`string`, one of `"home"`, `"work"`, `"mobile"`, `"main"`, `"fax"`, `"pager"`, `"other"`, default `"other"`): What the entry is for: home, work, mobile, main, fax, pager or other.
  - `customLabel` (`string`, nullable, up to 60 characters, default `null`): A label of your own, such as Assistant. Address books that support it show it instead of label.
- `addresses` (`object[]`, up to 50 items): Postal addresses. Given, it replaces the whole list.
  - `label` (`string`, one of `"home"`, `"work"`, `"mobile"`, `"main"`, `"fax"`, `"pager"`, `"other"`, default `"other"`): What the entry is for: home, work, mobile, main, fax, pager or other.
  - `customLabel` (`string`, nullable, up to 60 characters, default `null`): A label of your own, such as Assistant. Address books that support it show it instead of label.
  - `street` (`string`, nullable, up to 200 characters, default `null`): The street and house number, on as many lines as it needs.
  - `locality` (`string`, nullable, up to 200 characters, default `null`): The city or town.
  - `region` (`string`, nullable, up to 200 characters, default `null`): The state, county or province.
  - `postalCode` (`string`, nullable, up to 200 characters, default `null`): The postal code.
  - `country` (`string`, nullable, up to 200 characters, default `null`): The country.
- `urls` (`object[]`, up to 50 items): Websites and profile links. Given, it replaces the whole list.
  - `value` (`string`, required, 1 to 320 characters): The number or the link.
  - `label` (`string`, one of `"home"`, `"work"`, `"mobile"`, `"main"`, `"fax"`, `"pager"`, `"other"`, default `"other"`): What the entry is for: home, work, mobile, main, fax, pager or other.
  - `customLabel` (`string`, nullable, up to 60 characters, default `null`): A label of your own, such as Assistant. Address books that support it show it instead of label.
- `kind` (`string`, one of `"individual"`, `"group"`): `individual` for a person or a company, `group` for a list of other cards, the groups phones keep.
- `members` (`string[]`, up to 2000 items): The ids of the cards in the group. Only a group takes it, and a list you send replaces the whole list.

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

### `updateContactCard`

Change a card. Only the fields you pass change; null clears one, and a list you pass (emails, phones, addresses, urls) replaces the whole list, so read the card first with getContactCard and send the full list back with your change. On a saved contact, name and notes are the contact’s own. email can only be given to a card that has none: a saved contact keeps its address, so add another address to emails instead. On a group, members replaces the whole list of card ids, so send the ids already in it with the ones you add.

- Scopes: `contacts:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `contacts`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters)
- `email` (`string`, nullable, up to 320 characters, format `email`): The address Nextmail knows the contact by. Give it to a card that has none and the card becomes a saved contact. A saved contact keeps its address, so put any other address in emails.
- `name` (`string`, nullable, up to 200 characters): The full name the address book shows.
- `nameParts` (`object`, nullable): The name in parts, the way phones keep it. Left out, phones split name themselves.
  - `prefix` (`string`, nullable, up to 200 characters, default `null`): A title before the name, such as Dr.
  - `given` (`string`, nullable, up to 200 characters, default `null`): The first name.
  - `middle` (`string`, nullable, up to 200 characters, default `null`): Any middle names.
  - `family` (`string`, nullable, up to 200 characters, default `null`): The surname.
  - `suffix` (`string`, nullable, up to 200 characters, default `null`): Anything after the name, such as Jr.
- `nickname` (`string`, nullable, up to 200 characters): A nickname.
- `organization` (`string`, nullable, up to 200 characters): The company or organisation.
- `department` (`string`, nullable, up to 200 characters): The department within the organisation.
- `title` (`string`, nullable, up to 200 characters): The job title.
- `birthday` (`string`, nullable, pattern `^(?:\d{4}-|--)(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$`): YYYY-MM-DD, or --MM-DD when the year is not known.
- `notes` (`string`, nullable, up to 5000 characters): Free-form notes. On a saved contact these are the notes the contact page shows.
- `emails` (`object[]`, up to 50 items): Other email addresses, besides email. Given, it replaces the whole list.
  - `value` (`string`, required, up to 320 characters, format `email`): The email address.
  - `label` (`string`, one of `"home"`, `"work"`, `"mobile"`, `"main"`, `"fax"`, `"pager"`, `"other"`, default `"other"`): What the entry is for: home, work, mobile, main, fax, pager or other.
  - `customLabel` (`string`, nullable, up to 60 characters, default `null`): A label of your own, such as Assistant. Address books that support it show it instead of label.
- `phones` (`object[]`, up to 50 items): Phone numbers. Given, it replaces the whole list.
  - `value` (`string`, required, 1 to 320 characters): The number or the link.
  - `label` (`string`, one of `"home"`, `"work"`, `"mobile"`, `"main"`, `"fax"`, `"pager"`, `"other"`, default `"other"`): What the entry is for: home, work, mobile, main, fax, pager or other.
  - `customLabel` (`string`, nullable, up to 60 characters, default `null`): A label of your own, such as Assistant. Address books that support it show it instead of label.
- `addresses` (`object[]`, up to 50 items): Postal addresses. Given, it replaces the whole list.
  - `label` (`string`, one of `"home"`, `"work"`, `"mobile"`, `"main"`, `"fax"`, `"pager"`, `"other"`, default `"other"`): What the entry is for: home, work, mobile, main, fax, pager or other.
  - `customLabel` (`string`, nullable, up to 60 characters, default `null`): A label of your own, such as Assistant. Address books that support it show it instead of label.
  - `street` (`string`, nullable, up to 200 characters, default `null`): The street and house number, on as many lines as it needs.
  - `locality` (`string`, nullable, up to 200 characters, default `null`): The city or town.
  - `region` (`string`, nullable, up to 200 characters, default `null`): The state, county or province.
  - `postalCode` (`string`, nullable, up to 200 characters, default `null`): The postal code.
  - `country` (`string`, nullable, up to 200 characters, default `null`): The country.
- `urls` (`object[]`, up to 50 items): Websites and profile links. Given, it replaces the whole list.
  - `value` (`string`, required, 1 to 320 characters): The number or the link.
  - `label` (`string`, one of `"home"`, `"work"`, `"mobile"`, `"main"`, `"fax"`, `"pager"`, `"other"`, default `"other"`): What the entry is for: home, work, mobile, main, fax, pager or other.
  - `customLabel` (`string`, nullable, up to 60 characters, default `null`): A label of your own, such as Assistant. Address books that support it show it instead of label.
- `kind` (`string`, one of `"individual"`, `"group"`): `individual` for a person or a company, `group` for a list of other cards, the groups phones keep.
- `members` (`string[]`, up to 2000 items): The ids of the cards in the group. Only a group takes it, and a list you send replaces the whole list.

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

### `deleteContactCard`

Delete a card from the address book and from every phone and computer that syncs it. On a saved contact this deletes the contact too, the way deleteContact does: its notes, photo and audiences go and the address is hidden. A chat always asks first.

- Scopes: `contacts:write`.
- The app's assistant always asks first.
- Toolkit: `contacts`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters)

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

### `listContactImports`

The contact imports of this workspace, newest first, as Import on the Contacts page of the app lists them: a .vcf file somebody uploaded, the contacts inside a Google Takeout archive, or the address book pulled from an old mailbox. Each line says how many contacts it found, added, found already here and left out. Imported contacts join no audience. A member sees their own. Uploading a file takes bytes a tool call does not carry, so that is done in the app, over the REST API or with the CLI. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

- Scopes: `contacts:read`.
- The app's assistant runs it without asking.
- Toolkit: `contacts`.

**Inputs**

- `limit` (`integer`, at least 1, at most 100)
- `cursor` (`string`)

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), [`nextmail.contacts.listAllImports()`](https://nextmail.sh/docs/sdk/reference/contacts#listAllImports), [`nextmail.contacts.iterateImports()`](https://nextmail.sh/docs/sdk/reference/contacts#iterateImports); Python [`contacts.list_imports()`](https://nextmail.sh/docs/python/reference/contacts#listImports), [`contacts.list_all_imports()`](https://nextmail.sh/docs/python/reference/contacts#listAllImports), [`contacts.iterate_imports()`](https://nextmail.sh/docs/python/reference/contacts#iterateImports); Ruby [`contacts.list_imports`](https://nextmail.sh/docs/ruby/reference/contacts#listImports), [`contacts.list_all_imports`](https://nextmail.sh/docs/ruby/reference/contacts#listAllImports), [`contacts.iterate_imports`](https://nextmail.sh/docs/ruby/reference/contacts#iterateImports); PHP [`contacts->listImports`](https://nextmail.sh/docs/php/reference/contacts#listImports), [`contacts->listAllImports`](https://nextmail.sh/docs/php/reference/contacts#listAllImports), [`contacts->iterateImports`](https://nextmail.sh/docs/php/reference/contacts#iterateImports); Go [`Contacts.ListImports`](https://nextmail.sh/docs/go/reference/contacts#listImports), [`Contacts.ListAllImports`](https://nextmail.sh/docs/go/reference/contacts#listAllImports), [`Contacts.IterateImports`](https://nextmail.sh/docs/go/reference/contacts#iterateImports); Java [`contacts().listImports`](https://nextmail.sh/docs/java/reference/contacts#listImports), [`contacts().listAllImports`](https://nextmail.sh/docs/java/reference/contacts#listAllImports), [`contacts().iterateImports`](https://nextmail.sh/docs/java/reference/contacts#iterateImports); C# [`Contacts.ListImportsAsync`](https://nextmail.sh/docs/csharp/reference/contacts#listImports), [`Contacts.ListAllImportsAsync`](https://nextmail.sh/docs/csharp/reference/contacts#listAllImports), [`Contacts.IterateImportsAsync`](https://nextmail.sh/docs/csharp/reference/contacts#iterateImports).

### `getContactImport`

One contact import by its id, with its report: the address books the file held and how many cards each gave, how many were left out and why, and the first few that were not brought in.

- Scopes: `contacts:read`.
- The app's assistant runs it without asking.
- Toolkit: `contacts`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters)

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

### `undoContactImport`

Remove every card one contact import added, with the contact it created, as Remove imported contacts does in the app. Contacts that were saved before it stay. It cannot be taken back, though the same file can be imported again. A chat always asks first.

- Scopes: `contacts:write`.
- The app's assistant always asks first.
- Toolkit: `contacts`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters)

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

### `findDuplicateContacts`

Cards that look like the same person: they share an email address or a phone number, or have the same full name. Each group lists its cards, the most complete first, which is the one mergeContactCards should keep. Groups found by a shared address come first. It reads the address book and changes nothing.

- Scopes: `contacts:read`.
- The app's assistant runs it without asking.
- Toolkit: `contacts`.

**Inputs**

Takes no input.

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

### `mergeContactCards`

Merge cards of one person into a single card. id is the card to keep and cardIds the cards to fold into it. Folds the other cards into this one and deletes them. Fields this card leaves empty are filled from the others, and every email address, phone number, postal address and link is kept. Groups that held the others hold this card instead. A chat always asks first.

- Scopes: `contacts:write`.
- The app's assistant always asks first.
- Toolkit: `contacts`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters)
- `cardIds` (`string[]`, required, 1 to 10 items): The cards to fold into this one. They are deleted once their details are kept.

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

### `listBirthdays`

The birthdays of the people in the address book that fall between from and to, one entry for each date, with their age when the card holds the year of birth. Someone born on 29 February has their birthday on 28 February in other years. One line each with the date, the name, the card id and the age they turn. from and to are ISO 8601 with a zone, at most a year apart, and timezone (an IANA zone, UTC unless you say) decides which days the window covers.

- Scopes: `contacts:read`.
- The app's assistant runs it without asking.
- Toolkit: `contacts`.

**Inputs**

- `from` (`string`, required, format `date-time`)
- `to` (`string`, required, format `date-time`)
- `timezone` (`string`, 1 to 64 characters)

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