--- title: "client.Contacts" description: "Every method in this namespace: its signature, its parameters, what it returns and an example." url: "https://openemail.uk/docs/csharp/reference/contacts" area: "C#" category: "Reference" --- # client.Contacts Every method in this namespace: its signature, its parameters, what it returns and an example. ## Methods The workspace address book: the contacts somebody saved and the ones the app composer recorded, everyone seen in mail beside them, and for each person their audiences, photo, blocking, conversations and activity. ### `Contacts.ListAsync` List the workspace contacts, most recently seen first ```csharp Task ListAsync( string? source = null, string? q = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Returns one page of the workspace address book, ordered by `lastSeenAt` with the most recent first and contacts that have never been mailed last. `source` says where a row came from: `manual` for a contact somebody saved, in the app or through `Contacts.CreateAsync`, 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. `Contacts.ListPeopleAsync` 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. Scopes: `contacts:read`. **Parameters** - `source` (`string?`): `manual`, `auto` or `form`. Leave it out for the whole book. - `q` (`string?`): 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. - `limit` (`int?`): Rows per page, a whole number from 1 to 200. The server defaults to 50. - `cursor` (`string?`): The `nextCursor` from the previous page. Never build one yourself. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `Page` of contact objects, with `items`, `hasMore` and `nextCursor`. Each contact has `email`, `name`, `source`, `notes`, `photoUrl` and `lastSeenAt`. **Example** ```csharp var page = await client.Contacts.ListAsync(source: "manual", limit: 50); if (page.HasMore) { var next = await client.Contacts.ListAsync(source: "manual", limit: 50, cursor: page.NextCursor); Console.WriteLine($"{next.Count} more"); } ``` **Notes** - Mail sent through this API adds no contacts. Only sends from the app composer record recipients, and `Contacts.CreateAsync` is the way to add one deliberately. - Every member of the workspace reads and writes the same book, so a contact saved by one person is visible to the rest. - A contact that has never been mailed has `lastSeenAt` null and sorts last, after every contact with a date. - Addresses are stored lower cased. Also available in: API [`GET /contacts`](https://openemail.uk/docs/api/reference/contacts#get-contacts); TypeScript [`contacts.list()`](https://openemail.uk/docs/sdk/reference/contacts#list); Python [`contacts.list()`](https://openemail.uk/docs/python/reference/contacts#list); Ruby [`contacts.list`](https://openemail.uk/docs/ruby/reference/contacts#list); PHP [`contacts->list`](https://openemail.uk/docs/php/reference/contacts#list); Go [`Contacts.List`](https://openemail.uk/docs/go/reference/contacts#list); Java [`contacts().list`](https://openemail.uk/docs/java/reference/contacts#list); CLI [`openemail contacts list`](https://openemail.uk/docs/cli/reference/contacts#contacts-list). ### `Contacts.ListAllAsync` Collect the whole address book into one object ```csharp Task> ListAllAsync( string? source = null, string? q = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Follows `nextCursor` from page to page and returns every contact in the workspace, most recently seen first and never-mailed contacts last. It takes the same `source:` and `q:` filters as `Contacts.ListAsync`. Everything is held in memory before the call returns, and an address book grows with every recipient the composer records. Prefer `Contacts.IterateAsync` when you can stop early. `limit:` sets the page size of each request, not the total. Scopes: `contacts:read`. **Parameters** - `source` (`string?`): `manual`, `auto` or `form`. Leave it out for the whole book. - `q` (`string?`): 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. - `limit` (`int?`): Page size per request, from 1 to 200, defaulting to 50 on the server. - `cursor` (`string?`): A cursor from an earlier page to start after. - `apiKey` (`string?`): Overrides the client's API key for every page of this walk. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A list of contact objects holding every contact across all pages. **Example** ```csharp var saved = await client.Contacts.ListAllAsync(source: "manual", limit: 200); Console.WriteLine($"{saved.Count} contacts saved on purpose"); Console.WriteLine($"{string.Join(Environment.NewLine, saved.Select(row => row?["email"]))}"); ``` **Notes** - A failure on any page throws out of the whole call, and the contacts already fetched are discarded. Also available in: API [`GET /contacts`](https://openemail.uk/docs/api/reference/contacts#get-contacts); TypeScript [`contacts.listAll()`](https://openemail.uk/docs/sdk/reference/contacts#listAll); Python [`contacts.list_all()`](https://openemail.uk/docs/python/reference/contacts#listAll); Ruby [`contacts.list_all`](https://openemail.uk/docs/ruby/reference/contacts#listAll); PHP [`contacts->listAll`](https://openemail.uk/docs/php/reference/contacts#listAll); Go [`Contacts.ListAll`](https://openemail.uk/docs/go/reference/contacts#listAll); Java [`contacts().listAll`](https://openemail.uk/docs/java/reference/contacts#listAll). ### `Contacts.IterateAsync` Stream the address book one contact at a time ```csharp IAsyncEnumerable IterateAsync( string? source = null, string? q = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Returns an `IAsyncEnumerable` that yields contacts one at a time, most recently seen first, and requests the next page only once the current one is used up. Nothing is fetched until the loop starts, and breaking out of the `await foreach` stops the requests. Scopes: `contacts:read`. **Parameters** - `source` (`string?`): `manual`, `auto` or `form`. Leave it out for the whole book. - `q` (`string?`): 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. - `limit` (`int?`): Page size per request, from 1 to 200, defaulting to 50 on the server. - `cursor` (`string?`): A cursor from an earlier page to start after. - `apiKey` (`string?`): Overrides the client's API key for every page of this walk. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** An `IAsyncEnumerable` that yields one contact per step. **Example** ```csharp await foreach (var contact in client.Contacts.IterateAsync(source: "auto")) { if (contact["lastSeenAt"] is null) { break; } Console.WriteLine($"{contact["email"]} {contact["lastSeenAt"]}"); } ``` **Notes** - The generator is lazy, so an abandoned loop costs only the pages you consumed. Also available in: API [`GET /contacts`](https://openemail.uk/docs/api/reference/contacts#get-contacts); TypeScript [`contacts.iterate()`](https://openemail.uk/docs/sdk/reference/contacts#iterate); Python [`contacts.iterate()`](https://openemail.uk/docs/python/reference/contacts#iterate); Ruby [`contacts.iterate`](https://openemail.uk/docs/ruby/reference/contacts#iterate); PHP [`contacts->iterate`](https://openemail.uk/docs/php/reference/contacts#iterate); Go [`Contacts.Iterate`](https://openemail.uk/docs/go/reference/contacts#iterate); Java [`contacts().iterate`](https://openemail.uk/docs/java/reference/contacts#iterate). ### `Contacts.GetAsync` Read one contact by email address ```csharp Task GetAsync( string email, string? apiKey = null, CancellationToken cancellationToken = default) ``` 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`. **Parameters** - `email` (`string`, required): The contact's address, matched case insensitively. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` with `email`, `name`, `source`, `notes`, `photoUrl` and `lastSeenAt`, plus `audiences`, every audience the contact is in as an object with `id`, `name` and `builtin`. `builtin` is `default` on the audience every contact belongs to and null on one somebody created. A key that also holds `forms:read` gets `signUps`, what this address sent through sign-up forms, newest first and at most 20. Each is an object with `id`, `formId`, `formName`, `status` (`pending` or `added`), `answers`, `sourceUrl`, `createdAt` and `confirmedAt`. **Example** ```csharp try { var contact = await client.Contacts.GetAsync("Grace@Example.com"); } catch (OpenEmailApiException error) when (error.IsNotFound) { Console.WriteLine("Not in the address book"); } ``` **Notes** - `name` is null for an address recorded automatically without a display name, and `notes` is free text somebody set in the app or through `Contacts.UpdateAsync`. - The address is the contact's identity here and on every other contacts route. There is no id in the public contract. Also available in: API [`GET /contacts/{email}`](https://openemail.uk/docs/api/reference/contacts#get-contacts-email); TypeScript [`contacts.get()`](https://openemail.uk/docs/sdk/reference/contacts#get); Python [`contacts.get()`](https://openemail.uk/docs/python/reference/contacts#get); Ruby [`contacts.get`](https://openemail.uk/docs/ruby/reference/contacts#get); PHP [`contacts->get`](https://openemail.uk/docs/php/reference/contacts#get); Go [`Contacts.Get`](https://openemail.uk/docs/go/reference/contacts#get); Java [`contacts().get`](https://openemail.uk/docs/java/reference/contacts#get); CLI [`openemail contacts get`](https://openemail.uk/docs/cli/reference/contacts#contacts-get). ### `Contacts.CreateAsync` Save a contact in the workspace address book ```csharp Task CreateAsync( IReadOnlyDictionary body, string? apiKey = null, CancellationToken cancellationToken = default) ``` 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 `audienceIds` to put it in them in the same call, or add it later with `Audiences.AddContactAsync`. Sending `audienceIds` also requires the `audiences:write` scope, since it writes memberships as well as a contact. An address can be in the book once. A second create for an address that is already there is refused with 409 `contact_exists` rather than merged, so a retry cannot quietly overwrite a name somebody edited in the app. Read the existing row with `Contacts.GetAsync` and change it with `Contacts.UpdateAsync`. Scopes: `contacts:write`. **Parameters** - `email` (`string`, required): The address to save, trimmed and lower cased before it is stored. - `name` (`string`): Display name. Leave it out to save the contact without one. - `notes` (`string`): Free text kept with the contact and shown beside it in the app. - `audienceIds` (`IEnumerable`): 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. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` with `email`, `name`, `source` as `manual`, `notes` and `lastSeenAt`, which is null until mail goes to the address from the app composer, plus `audiences`, every audience the contact is now in, the default one included. **Example** ```csharp try { var contact = await client.Contacts.CreateAsync(new Body { ["email"] = "Grace@Example.com", ["name"] = "Grace Hopper", ["notes"] = "Met at the compiler workshop.", ["audienceIds"] = new[] { "aud_9f2c4b7e1a0d63d84c5f2e7b" }, }); Console.WriteLine($"Saved {contact["email"]} in {contact["audiences"]?.AsArray().Count} audiences"); } catch (OpenEmailApiException error) when (error.IsConflict) { Console.WriteLine("Already in the book, so change it with contacts->update"); } ``` **Notes** - The SDK does not retry a create after a network failure. If you retry by hand after a lost response, a 409 `contact_exists` means the first attempt landed. - Contacts belong to the workspace, so the contact this creates is the one every member and every other key sees. - An id in `audienceIds` that is not an audience of this workspace fails the whole create. Nothing is saved. Also available in: API [`POST /contacts`](https://openemail.uk/docs/api/reference/contacts#post-contacts); TypeScript [`contacts.create()`](https://openemail.uk/docs/sdk/reference/contacts#create); Python [`contacts.create()`](https://openemail.uk/docs/python/reference/contacts#create); Ruby [`contacts.create`](https://openemail.uk/docs/ruby/reference/contacts#create); PHP [`contacts->create`](https://openemail.uk/docs/php/reference/contacts#create); Go [`Contacts.Create`](https://openemail.uk/docs/go/reference/contacts#create); Java [`contacts().create`](https://openemail.uk/docs/java/reference/contacts#create); CLI [`openemail contacts create`](https://openemail.uk/docs/cli/reference/contacts#contacts-create). ### `Contacts.UpdateAsync` Change a contact's name or notes ```csharp Task UpdateAsync( string email, IReadOnlyDictionary patch, string? apiKey = null, CancellationToken cancellationToken = default) ``` 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 `new Body { ["notes"] = null }` empties the notes while `[]` changes nothing. The address cannot be changed. It is the contact's identity, its path segment and the unique key of the book, so moving a contact to a new address is a `Contacts.DeleteAsync` and a `Contacts.CreateAsync`, 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`. **Parameters** - `email` (`string`, required): The contact's address, matched case insensitively. - `name` (`string`): New display name. Null clears it. - `notes` (`string`): New notes. Null clears them. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` for the contact as it stands after the change, with `audiences` alongside it. **Example** ```csharp var contact = await client.Contacts.UpdateAsync("grace@example.com", new Body { ["name"] = "Grace Hopper", ["notes"] = null }); Console.WriteLine($"{contact["name"]}, notes {(contact["notes"] is null ? "cleared" : "kept")}"); ``` **Notes** - The SDK retries this call after a network failure, since the same patch sent twice leaves the same contact. - An address that is not in the book is a 404, the same as `Contacts.GetAsync`. - Audience membership is not touched here. Use `Contacts.SetAudiencesAsync` to set the whole list, or `Audiences.AddContactAsync` and `Audiences.RemoveContactAsync` for one audience. Also available in: API [`PATCH /contacts/{email}`](https://openemail.uk/docs/api/reference/contacts#patch-contacts-email); TypeScript [`contacts.update()`](https://openemail.uk/docs/sdk/reference/contacts#update); Python [`contacts.update()`](https://openemail.uk/docs/python/reference/contacts#update); Ruby [`contacts.update`](https://openemail.uk/docs/ruby/reference/contacts#update); PHP [`contacts->update`](https://openemail.uk/docs/php/reference/contacts#update); Go [`Contacts.Update`](https://openemail.uk/docs/go/reference/contacts#update); Java [`contacts().update`](https://openemail.uk/docs/java/reference/contacts#update); CLI [`openemail contacts update`](https://openemail.uk/docs/cli/reference/contacts#contacts-update). ### `Contacts.DeleteAsync` Delete somebody from the contacts and hide the address ```csharp Task DeleteAsync( string email, string? apiKey = null, CancellationToken cancellationToken = default) ``` Does what Delete does on the Contacts page in the app. A saved contact goes with its notes, its photo and every audience it was in, the default one included. The address is then hidden: `Contacts.ListPeopleAsync` leaves it out, and mail sent to it from the app composer no longer records it as a contact. The address can be one that was only ever seen in mail, which is how you take somebody off the people list, and `wasSaved` says which it was. Nothing else moves: the mail exchanged with the address stays in the mailbox, and the address can still be written to. There is no undo. `Contacts.CreateAsync` or `Contacts.SaveAsync` afterwards brings the address back as a new contact with no name, no notes and no membership beyond the default audience. Scopes: `contacts:write`. **Parameters** - `email` (`string`, required): The contact's address, matched case insensitively. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` with `object` set to `contact`, `email`, `deleted` set to true and `wasSaved`. **Example** ```csharp var removed = await client.Contacts.DeleteAsync("grace@example.com"); Console.WriteLine($"{removed["email"]}{((bool?)removed["wasSaved"] == true ? " was a saved contact" : " was only seen in mail")} and is now hidden"); ``` **Notes** - An address that is not in the book is no longer a 404: it is hidden and answers with `wasSaved` false. Something that is not an address is a 422 `invalid_contact`. - The SDK does not retry a delete, though a second attempt is harmless: it answers with `wasSaved` false. - `Contacts.DeleteManyAsync` deletes up to 200 addresses in one call. Also available in: API [`DELETE /contacts/{email}`](https://openemail.uk/docs/api/reference/contacts#delete-contacts-email); TypeScript [`contacts.delete()`](https://openemail.uk/docs/sdk/reference/contacts#delete); Python [`contacts.delete()`](https://openemail.uk/docs/python/reference/contacts#delete); Ruby [`contacts.delete`](https://openemail.uk/docs/ruby/reference/contacts#delete); PHP [`contacts->delete`](https://openemail.uk/docs/php/reference/contacts#delete); Go [`Contacts.Delete`](https://openemail.uk/docs/go/reference/contacts#delete); Java [`contacts().delete`](https://openemail.uk/docs/java/reference/contacts#delete); CLI [`openemail contacts delete`](https://openemail.uk/docs/cli/reference/contacts#contacts-delete). ### `Contacts.SetAudiencesAsync` Set exactly which audiences a contact is in ```csharp Task SetAudiencesAsync( string email, IReadOnlyDictionary body, string? apiKey = null, CancellationToken cancellationToken = default) ``` 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 `new Body { ["audienceIds"] = Array.Empty() }` leaves the contact in the default audience alone. To add or remove one audience without restating the rest, use `Audiences.AddContactAsync` or `Audiences.RemoveContactAsync`. The address is trimmed and lower cased, the SDK URL encodes it for the path, and it has to be a contact already: an address that is not in the book is a 404 `contact_not_found` on `email`. Create it with `Contacts.CreateAsync`, which takes `audienceIds` too. An id that is not an audience of this workspace is a 404 `audience_not_found` on `audienceIds`, and nothing is changed. Scopes: `audiences:write`. **Parameters** - `email` (`string`, required): The contact's address, matched case insensitively. - `audienceIds` (`IEnumerable`, required): 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 `audienceIds`, and an empty id is the same error on that entry, such as `audienceIds.0`. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` for the contact as it stands after the change, with `audiences`, every audience the contact is now in as an object with `id`, `name` and `builtin`, the default one included. **Example** ```csharp var contact = await client.Contacts.SetAudiencesAsync("grace@example.com", new Body { ["audienceIds"] = new[] { "aud_9f2c4b7e1a0d63d84c5f2e7b", "aud_1c4e7a9b2d0f36e85a7c1b4d" }, }); foreach (var audience in contact["audiences"]?.AsArray() ?? []) { Console.WriteLine($"{audience?["name"]}{((string?)audience?["builtin"] == "default" ? ", everyone" : "")}"); } ``` **Notes** - `audiences:write` is the only scope checked, because this writes memberships rather than the contact. - Safe to replay: sending the same list again changes nothing. The SDK retries it after a network failure. - Read the current list with `Contacts.GetAsync` first when you mean to add one audience to what the contact already has, or use `Audiences.AddContactAsync`. Also available in: API [`PUT /contacts/{email}/audiences`](https://openemail.uk/docs/api/reference/contacts#put-contacts-email-audiences); TypeScript [`contacts.setAudiences()`](https://openemail.uk/docs/sdk/reference/contacts#setAudiences); Python [`contacts.set_audiences()`](https://openemail.uk/docs/python/reference/contacts#setAudiences); Ruby [`contacts.set_audiences`](https://openemail.uk/docs/ruby/reference/contacts#setAudiences); PHP [`contacts->setAudiences`](https://openemail.uk/docs/php/reference/contacts#setAudiences); Go [`Contacts.SetAudiences`](https://openemail.uk/docs/go/reference/contacts#setAudiences); Java [`contacts().setAudiences`](https://openemail.uk/docs/java/reference/contacts#setAudiences); CLI [`openemail contacts set-audiences`](https://openemail.uk/docs/cli/reference/contacts#contacts-set-audiences). ### `Contacts.ListPeopleAsync` List everyone on the Contacts page, saved or seen in mail ```csharp Task ListPeopleAsync( string? q = null, string? email = null, string? sort = null, bool? blocked = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Returns one page of the people the Contacts page in the app lists: the saved contacts, and every address seen in mail as the sender or a recipient of a thread's newest message. Each row says whether it is `saved`, how many `threads` it shares with the mailbox and when mail last moved (`lastAt`). A person seen in mail and saved is one row. `Contacts.ListAsync` 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. Scopes: `contacts:read`. **Parameters** - `q` (`string?`): Searches names, addresses and notes, up to 200 characters. When nothing matches exactly on the first page, close spellings are returned instead. - `email` (`string?`): One address only, matched case insensitively: the way to read one person's thread count and last mail. - `sort` (`string?`): `recent` (the default), `name` or `threads`, also in `OpenEmail\Constants\PeopleSorts`. - `blocked` (`bool?`): `true` for only the people the workspace blocklist blocks, whole-domain rules included. - `limit` (`int?`): Rows per page, 1 to 100. The server defaults to 25. - `cursor` (`string?`): The `nextCursor` from the previous page. Never build one yourself. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `PeoplePage` with `items`, `hasMore`, `nextCursor` and `seen`. Each person is an object with `email`, `displayEmail`, `name`, `saved`, `source`, `notes`, `photoUrl`, `threads`, `lastAt`, `createdAt`, `updatedAt` and `blockedBy`. **Example** ```csharp using OpenEmail.Constants; var people = await client.Contacts.ListPeopleAsync(sort: PeopleSorts.Threads, limit: 50); if (!people.Seen) { Console.WriteLine("Saved contacts only, since this key cannot read the mail"); } ``` **Notes** - `email` is lower cased and is what every other contacts method takes. `displayEmail` keeps the capitals the newest message wrote. - A malformed or stale cursor is a 400 `invalid_cursor`. Start again without one. - A key limited to particular addresses or domains gets the saved contacts alone, with `seen` false, even when it holds `threads:read`, because the addresses seen in mail would be read from the mail of every address in the workspace. Also available in: API [`GET /contacts/people`](https://openemail.uk/docs/api/reference/contacts#get-contacts-people); TypeScript [`contacts.listPeople()`](https://openemail.uk/docs/sdk/reference/contacts#listPeople); Python [`contacts.list_people()`](https://openemail.uk/docs/python/reference/contacts#listPeople); Ruby [`contacts.list_people`](https://openemail.uk/docs/ruby/reference/contacts#listPeople); PHP [`contacts->listPeople`](https://openemail.uk/docs/php/reference/contacts#listPeople); Go [`Contacts.ListPeople`](https://openemail.uk/docs/go/reference/contacts#listPeople); Java [`contacts().listPeople`](https://openemail.uk/docs/java/reference/contacts#listPeople); CLI [`openemail contacts list-people`](https://openemail.uk/docs/cli/reference/contacts#contacts-list-people). ### `Contacts.ListAllPeopleAsync` Collect everyone on the Contacts page into one object ```csharp Task> ListAllPeopleAsync( string? q = null, string? email = null, string? sort = null, bool? blocked = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Follows `nextCursor` from page to page and returns every person `Contacts.ListPeopleAsync` would list, in the same order and with the same filters. It is how you count the people a blocklist blocks: `(await client.Contacts.ListAllPeopleAsync(blocked: true)).Count`. Everything is held in memory before the call returns, and a busy mailbox has seen a great many addresses. Prefer `Contacts.IteratePeopleAsync` when you can stop early. Scopes: `contacts:read`. **Parameters** - `q` (`string?`): Searches names, addresses and notes, up to 200 characters. When nothing matches exactly on the first page, close spellings are returned instead. - `email` (`string?`): One address only, matched case insensitively: the way to read one person's thread count and last mail. - `sort` (`string?`): `recent` (the default), `name` or `threads`. - `blocked` (`bool?`): `true` for only the people the workspace blocklist blocks, whole-domain rules included. - `limit` (`int?`): Page size per request, from 1 to 100, defaulting to 25 on the server. - `cursor` (`string?`): A cursor from an earlier page to start after. - `apiKey` (`string?`): Overrides the client's API key for every page of this walk. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A list of person objects holding every person across all pages. **Example** ```csharp var blocked = await client.Contacts.ListAllPeopleAsync(blocked: true, limit: 100); Console.WriteLine($"{blocked.Count} people are blocked"); foreach (var person in blocked) { Console.WriteLine($"{person["email"]} by {person["blockedBy"]?["rule"]} in {person["blockedBy"]?["list"]}"); } ``` **Notes** - A failure on any page throws out of the whole call, and the people already fetched are discarded. - `seen` is not reported here. Read one page with `Contacts.ListPeopleAsync` to learn whether the key reads the people seen in mail. Also available in: API [`GET /contacts/people`](https://openemail.uk/docs/api/reference/contacts#get-contacts-people); TypeScript [`contacts.listAllPeople()`](https://openemail.uk/docs/sdk/reference/contacts#listAllPeople); Python [`contacts.list_all_people()`](https://openemail.uk/docs/python/reference/contacts#listAllPeople); Ruby [`contacts.list_all_people`](https://openemail.uk/docs/ruby/reference/contacts#listAllPeople); PHP [`contacts->listAllPeople`](https://openemail.uk/docs/php/reference/contacts#listAllPeople); Go [`Contacts.ListAllPeople`](https://openemail.uk/docs/go/reference/contacts#listAllPeople); Java [`contacts().listAllPeople`](https://openemail.uk/docs/java/reference/contacts#listAllPeople). ### `Contacts.IteratePeopleAsync` Stream everyone on the Contacts page one person at a time ```csharp IAsyncEnumerable IteratePeopleAsync( string? q = null, string? email = null, string? sort = null, bool? blocked = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Returns an `IAsyncEnumerable` that yields the people `Contacts.ListPeopleAsync` lists, one at a time, and requests the next page only once the current one is used up. Nothing is fetched until the loop starts, and breaking out of the `await foreach` stops the requests. Scopes: `contacts:read`. **Parameters** - `q` (`string?`): Searches names, addresses and notes, up to 200 characters. When nothing matches exactly on the first page, close spellings are returned instead. - `email` (`string?`): One address only, matched case insensitively: the way to read one person's thread count and last mail. - `sort` (`string?`): `recent` (the default), `name` or `threads`. - `blocked` (`bool?`): `true` for only the people the workspace blocklist blocks, whole-domain rules included. - `limit` (`int?`): Page size per request, from 1 to 100, defaulting to 25 on the server. - `cursor` (`string?`): A cursor from an earlier page to start after. - `apiKey` (`string?`): Overrides the client's API key for every page of this walk. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** An `IAsyncEnumerable` that yields one person per step. **Example** ```csharp await foreach (var person in client.Contacts.IteratePeopleAsync(sort: "threads")) { if ((int?)person["threads"] < 5) { break; } if ((bool?)person["saved"] != true) { await client.Contacts.SaveAsync(person["email"]!.GetValue()); } } ``` **Notes** - The generator is lazy, so an abandoned loop costs only the pages you consumed. Also available in: API [`GET /contacts/people`](https://openemail.uk/docs/api/reference/contacts#get-contacts-people); TypeScript [`contacts.iteratePeople()`](https://openemail.uk/docs/sdk/reference/contacts#iteratePeople); Python [`contacts.iterate_people()`](https://openemail.uk/docs/python/reference/contacts#iteratePeople); Ruby [`contacts.iterate_people`](https://openemail.uk/docs/ruby/reference/contacts#iteratePeople); PHP [`contacts->iteratePeople`](https://openemail.uk/docs/php/reference/contacts#iteratePeople); Go [`Contacts.IteratePeople`](https://openemail.uk/docs/go/reference/contacts#iteratePeople); Java [`contacts().iteratePeople`](https://openemail.uk/docs/java/reference/contacts#iteratePeople). ### `Contacts.SaveAsync` Save an address as a contact, or keep one that was recorded ```csharp Task SaveAsync( string email, IReadOnlyDictionary? body = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Does what Add to contacts and Keep in contacts do in the app, and is safe to call whatever state the address is in. An address that is not a contact yet becomes one with `source` `manual`. A contact recorded from a send becomes `manual`. A contact already saved keeps what it has. A deleted address is brought back. `name` in the body replaces the stored name and leaving it out keeps it. `notes` replaces the stored notes and null clears them. Unlike `Contacts.CreateAsync`, an address already in the book is not an error, and unlike `Contacts.UpdateAsync`, an address not in the book is not one either. Scopes: `contacts:write`. **Parameters** - `email` (`string`, required): The address, trimmed and lower cased on the server. - `name` (`string`): Up to 200 characters. Left out, the stored name is kept. - `notes` (`string`): Up to 5,000 characters. Null clears the notes, and left out, they are kept. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` for the contact as it stands after the save, with `audiences`. **Example** ```csharp var contact = await client.Contacts.SaveAsync("grace@example.com", body: new Body { ["name"] = "Grace Hopper" }); Console.WriteLine(contact.ToJsonString()); ``` **Notes** - The server answers 201 for a new contact and 200 for one that was there. The SDK returns the same object for both, so compare `createdAt` with `updatedAt` if you need to tell them apart. - Safe to replay, so the SDK retries it after a network failure. - A new contact joins the default audience, as it does from `Contacts.CreateAsync`. Also available in: API [`PUT /contacts/{email}`](https://openemail.uk/docs/api/reference/contacts#put-contacts-email); TypeScript [`contacts.save()`](https://openemail.uk/docs/sdk/reference/contacts#save); Python [`contacts.save()`](https://openemail.uk/docs/python/reference/contacts#save); Ruby [`contacts.save`](https://openemail.uk/docs/ruby/reference/contacts#save); PHP [`contacts->save`](https://openemail.uk/docs/php/reference/contacts#save); Go [`Contacts.Save`](https://openemail.uk/docs/go/reference/contacts#save); Java [`contacts().save`](https://openemail.uk/docs/java/reference/contacts#save); CLI [`openemail contacts save`](https://openemail.uk/docs/cli/reference/contacts#contacts-save). ### `Contacts.DeleteManyAsync` Delete up to 200 contacts in one call ```csharp Task DeleteManyAsync( IEnumerable emails, string? apiKey = null, CancellationToken cancellationToken = default) ``` Deletes every address in `emails` the way `Contacts.DeleteAsync` 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`. **Parameters** - `emails` (`IEnumerable`, required): 1 to 200 addresses, matched case insensitively. More than 200, or none, is a 422 on `emails`. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` with `object` set to `contact_batch_delete`, `deleted`, `saved` and `invalid`. `deleted` counts the addresses deleted and hidden, `saved` how many of them were saved contacts. **Example** ```csharp var result = await client.Contacts.DeleteManyAsync(new[] { "ada@example.com", "grace@example.com", "not an address" }); Console.WriteLine($"{result["deleted"]} deleted, {result["saved"]} of them saved contacts"); if ((result["invalid"]?.AsArray().Count ?? 0) > 0) { Console.WriteLine($"Skipped: {string.Join(", ", result["invalid"]?.AsArray() ?? [])}"); } ``` **Notes** - Safe to replay: deleting an address twice leaves it deleted and hidden, so the SDK retries it after a network failure. - No mail is deleted, and nobody is unsubscribed from anything. Also available in: API [`POST /contacts/batch-delete`](https://openemail.uk/docs/api/reference/contacts#post-contacts-batch-delete); TypeScript [`contacts.deleteMany()`](https://openemail.uk/docs/sdk/reference/contacts#deleteMany); Python [`contacts.delete_many()`](https://openemail.uk/docs/python/reference/contacts#deleteMany); Ruby [`contacts.delete_many`](https://openemail.uk/docs/ruby/reference/contacts#deleteMany); PHP [`contacts->deleteMany`](https://openemail.uk/docs/php/reference/contacts#deleteMany); Go [`Contacts.DeleteMany`](https://openemail.uk/docs/go/reference/contacts#deleteMany); Java [`contacts().deleteMany`](https://openemail.uk/docs/java/reference/contacts#deleteMany); CLI [`openemail contacts delete-many`](https://openemail.uk/docs/cli/reference/contacts#contacts-delete-many). ### `Contacts.SetPhotoAsync` Upload the photo shown for a contact ```csharp Task SetPhotoAsync( string email, Stream data, string? contentType = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` 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 readable `Stream`. The type is read from `contentType:`. Without it the bytes go as `application/octet-stream` and the server refuses them with 422 `invalid_image`. The address has to be a saved contact already: `Contacts.SaveAsync` it first. Scopes: `contacts:write`. **Parameters** - `email` (`string`, required): The contact's address, matched case insensitively. - `data` (`Stream`, required): The image: a readable `Stream`. - `contentType` (`string?`): `image/png`, `image/jpeg`, `image/webp` or `image/gif`. Required, because a `Stream` carries no type of its own. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` for the contact with the new `photoUrl`. **Example** ```csharp await client.Contacts.SaveAsync("grace@example.com"); await using var photo = File.OpenRead("photo.jpg"); var contact = await client.Contacts.SetPhotoAsync("grace@example.com", photo, contentType: "image/jpeg"); Console.WriteLine($"Photo at {contact["photoUrl"]}"); ``` **Notes** - An address that is not a saved contact is a 404 `contact_not_found`. - A busy image service answers 503 `image_busy`, which the SDK retries like any other 503. - Every upload gets a new URL, so a cached old photo never shows under the new one. Also available in: API [`PUT /contacts/{email}/photo`](https://openemail.uk/docs/api/reference/contacts#put-contacts-email-photo); TypeScript [`contacts.setPhoto()`](https://openemail.uk/docs/sdk/reference/contacts#setPhoto); Python [`contacts.set_photo()`](https://openemail.uk/docs/python/reference/contacts#setPhoto); Ruby [`contacts.set_photo`](https://openemail.uk/docs/ruby/reference/contacts#setPhoto); PHP [`contacts->setPhoto`](https://openemail.uk/docs/php/reference/contacts#setPhoto); Go [`Contacts.SetPhoto`](https://openemail.uk/docs/go/reference/contacts#setPhoto); Java [`contacts().setPhoto`](https://openemail.uk/docs/java/reference/contacts#setPhoto); CLI [`openemail contacts set-photo`](https://openemail.uk/docs/cli/reference/contacts#contacts-set-photo). ### `Contacts.RemovePhotoAsync` Remove a contact photo ```csharp Task RemovePhotoAsync( string email, string? apiKey = null, CancellationToken cancellationToken = default) ``` 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`. **Parameters** - `email` (`string`, required): The contact's address, matched case insensitively. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` for the contact with `photoUrl` null. **Example** ```csharp var contact = await client.Contacts.RemovePhotoAsync("grace@example.com"); Console.WriteLine($"{contact["email"]} now shows {contact["photoUrl"]?.ToString() ?? "initials"}"); ``` **Notes** - An address that is not a saved contact is a 404 `contact_not_found`. - Safe to replay, so the SDK retries it after a network failure. Also available in: API [`DELETE /contacts/{email}/photo`](https://openemail.uk/docs/api/reference/contacts#delete-contacts-email-photo); TypeScript [`contacts.removePhoto()`](https://openemail.uk/docs/sdk/reference/contacts#removePhoto); Python [`contacts.remove_photo()`](https://openemail.uk/docs/python/reference/contacts#removePhoto); Ruby [`contacts.remove_photo`](https://openemail.uk/docs/ruby/reference/contacts#removePhoto); PHP [`contacts->removePhoto`](https://openemail.uk/docs/php/reference/contacts#removePhoto); Go [`Contacts.RemovePhoto`](https://openemail.uk/docs/go/reference/contacts#removePhoto); Java [`contacts().removePhoto`](https://openemail.uk/docs/java/reference/contacts#removePhoto); CLI [`openemail contacts remove-photo`](https://openemail.uk/docs/cli/reference/contacts#contacts-remove-photo). ### `Contacts.BlockAsync` Block an address ```csharp Task BlockAsync( string email, string? apiKey = null, CancellationToken cancellationToken = default) ``` Puts the address on the workspace blocklist, the same list `Settings.UpdateAsync` 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`. **Parameters** - `email` (`string`, required): The address to block. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` with `object` set to `contact_block`, `email`, `blocked` set to true, `blockedBy` and `created`. **Example** ```csharp var block = await client.Contacts.BlockAsync("ada+news@example.com"); if ((bool?)block["created"] == true) { Console.WriteLine($"Blocked {block["email"]}"); } else { Console.WriteLine($"Already blocked by {block["blockedBy"]?["rule"]} in {block["blockedBy"]?["list"]}"); } ``` **Notes** - It needs `settings:write` rather than `contacts:write`, because it writes the blocklist rather than the contact. - Safe to replay, so the SDK retries it after a network failure. - An address with fewer than two letters or numbers is refused with 422 `blocklist_entry_too_broad`. - A key limited to particular addresses or domains gets 422 `capability_unsupported` on `addressAllowlist`, because the blocklist belongs to the whole workspace and filters the mail of every address in it. Also available in: API [`POST /contacts/{email}/block`](https://openemail.uk/docs/api/reference/contacts#post-contacts-email-block); TypeScript [`contacts.block()`](https://openemail.uk/docs/sdk/reference/contacts#block); Python [`contacts.block()`](https://openemail.uk/docs/python/reference/contacts#block); Ruby [`contacts.block`](https://openemail.uk/docs/ruby/reference/contacts#block); PHP [`contacts->block`](https://openemail.uk/docs/php/reference/contacts#block); Go [`Contacts.Block`](https://openemail.uk/docs/go/reference/contacts#block); Java [`contacts().block`](https://openemail.uk/docs/java/reference/contacts#block); CLI [`openemail contacts block`](https://openemail.uk/docs/cli/reference/contacts#contacts-block). ### `Contacts.UnblockAsync` Unblock an address ```csharp Task UnblockAsync( string email, string? apiKey = null, CancellationToken cancellationToken = default) ``` 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`. **Parameters** - `email` (`string`, required): The address to unblock. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` with `object` set to `contact_block`, `email`, `blocked` set to false and `removed`, each entry of which is an object with `rule` and `ListAsync`. **Example** ```csharp using OpenEmail.Constants; var unblock = await client.Contacts.UnblockAsync("ada@example.com"); foreach (var removed in unblock["removed"]?.AsArray() ?? []) { if ((string?)removed?["list"] == ContactBlockLists.BlockedDomains) { Console.WriteLine($"Everybody at {removed?["rule"]} is unblocked too"); } } ``` **Notes** - Safe to replay, so the SDK retries it after a network failure. - A key limited to particular addresses or domains gets 422 `capability_unsupported` on `addressAllowlist`, because the blocklist belongs to the whole workspace and filters the mail of every address in it. Also available in: API [`DELETE /contacts/{email}/block`](https://openemail.uk/docs/api/reference/contacts#delete-contacts-email-block); TypeScript [`contacts.unblock()`](https://openemail.uk/docs/sdk/reference/contacts#unblock); Python [`contacts.unblock()`](https://openemail.uk/docs/python/reference/contacts#unblock); Ruby [`contacts.unblock`](https://openemail.uk/docs/ruby/reference/contacts#unblock); PHP [`contacts->unblock`](https://openemail.uk/docs/php/reference/contacts#unblock); Go [`Contacts.Unblock`](https://openemail.uk/docs/go/reference/contacts#unblock); Java [`contacts().unblock`](https://openemail.uk/docs/java/reference/contacts#unblock); CLI [`openemail contacts unblock`](https://openemail.uk/docs/cli/reference/contacts#contacts-unblock). ### `Contacts.ListThreadsAsync` List the conversations with one person ```csharp Task ListThreadsAsync( string email, string? q = null, string? sort = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` 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.GetAsync` 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. Scopes: `threads:read`. **Parameters** - `email` (`string`, required): The address. It does not have to be a saved contact. - `q` (`string?`): Searches inside those threads, with the mailbox search syntax, up to 200 characters. - `sort` (`string?`): `newest` (the default), `oldest`, `sender` or `subject`, also in `OpenEmail\Constants\ContactThreadSorts`. - `limit` (`int?`): Threads per page, 1 to 100. The server defaults to 25. - `cursor` (`string?`): The `nextCursor` from the previous page. Never build one yourself. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `Page` of thread summary objects, with `items`, `hasMore` and `nextCursor`. **Example** ```csharp var threads = await client.Contacts.ListThreadsAsync("grace@example.com", q: "invoice", limit: 10); foreach (var thread in threads) { Console.WriteLine($"{thread["receivedAt"]} {thread["subject"]} ({thread["messageCount"]}){((bool?)thread["hasUnread"] == true ? ", unread" : "")}"); } ``` **Notes** - It needs `threads:read`, because it reads mail rather than the contact. - A key limited to particular addresses or domains gets 422 `capability_unsupported` on `addressAllowlist`, because a contact's threads and activity are read from the mail of every address in the workspace. Also available in: API [`GET /contacts/{email}/threads`](https://openemail.uk/docs/api/reference/contacts#get-contacts-email-threads); TypeScript [`contacts.listThreads()`](https://openemail.uk/docs/sdk/reference/contacts#listThreads); Python [`contacts.list_threads()`](https://openemail.uk/docs/python/reference/contacts#listThreads); Ruby [`contacts.list_threads`](https://openemail.uk/docs/ruby/reference/contacts#listThreads); PHP [`contacts->listThreads`](https://openemail.uk/docs/php/reference/contacts#listThreads); Go [`Contacts.ListThreads`](https://openemail.uk/docs/go/reference/contacts#listThreads); Java [`contacts().listThreads`](https://openemail.uk/docs/java/reference/contacts#listThreads); CLI [`openemail contacts list-threads`](https://openemail.uk/docs/cli/reference/contacts#contacts-list-threads). ### `Contacts.ListAllThreadsAsync` Collect every conversation with one person into one object ```csharp Task> ListAllThreadsAsync( string email, string? q = null, string? sort = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Follows `nextCursor` from page to page and returns every thread `Contacts.ListThreadsAsync` would list for the address, in the same order. Everything is held in memory before the call returns. Prefer `Contacts.IterateThreadsAsync` when you can stop early. Scopes: `threads:read`. **Parameters** - `email` (`string`, required): The address. It does not have to be a saved contact. - `q` (`string?`): Searches inside those threads, with the mailbox search syntax, up to 200 characters. - `sort` (`string?`): `newest` (the default), `oldest`, `sender` or `subject`. - `limit` (`int?`): Page size per request, from 1 to 100, defaulting to 25 on the server. - `cursor` (`string?`): A cursor from an earlier page to start after. - `apiKey` (`string?`): Overrides the client's API key for every page of this walk. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A list of thread summary objects holding every thread across all pages. **Example** ```csharp var threads = await client.Contacts.ListAllThreadsAsync("grace@example.com", sort: "oldest", limit: 100); Console.WriteLine(threads.Count); ``` **Notes** - A failure on any page throws out of the whole call, and the threads already fetched are discarded. Also available in: API [`GET /contacts/{email}/threads`](https://openemail.uk/docs/api/reference/contacts#get-contacts-email-threads); TypeScript [`contacts.listAllThreads()`](https://openemail.uk/docs/sdk/reference/contacts#listAllThreads); Python [`contacts.list_all_threads()`](https://openemail.uk/docs/python/reference/contacts#listAllThreads); Ruby [`contacts.list_all_threads`](https://openemail.uk/docs/ruby/reference/contacts#listAllThreads); PHP [`contacts->listAllThreads`](https://openemail.uk/docs/php/reference/contacts#listAllThreads); Go [`Contacts.ListAllThreads`](https://openemail.uk/docs/go/reference/contacts#listAllThreads); Java [`contacts().listAllThreads`](https://openemail.uk/docs/java/reference/contacts#listAllThreads). ### `Contacts.IterateThreadsAsync` Stream the conversations with one person one thread at a time ```csharp IAsyncEnumerable IterateThreadsAsync( string email, string? q = null, string? sort = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Returns an `IAsyncEnumerable` that yields the threads `Contacts.ListThreadsAsync` lists for the address, one at a time, and requests the next page only once the current one is used up. Nothing is fetched until the loop starts, and breaking out of the `await foreach` stops the requests. Scopes: `threads:read`. **Parameters** - `email` (`string`, required): The address. It does not have to be a saved contact. - `q` (`string?`): Searches inside those threads, with the mailbox search syntax, up to 200 characters. - `sort` (`string?`): `newest` (the default), `oldest`, `sender` or `subject`. - `limit` (`int?`): Page size per request, from 1 to 100, defaulting to 25 on the server. - `cursor` (`string?`): A cursor from an earlier page to start after. - `apiKey` (`string?`): Overrides the client's API key for every page of this walk. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** An `IAsyncEnumerable` that yields one thread summary per step. **Example** ```csharp await foreach (var thread in client.Contacts.IterateThreadsAsync("grace@example.com")) { if ((bool?)thread["hasUnread"] == true) { Console.WriteLine($"Newest unread: {thread["subject"]} from {thread["from"]?["email"]}"); break; } } ``` **Notes** - The generator is lazy, so an abandoned loop costs only the pages you consumed. Also available in: API [`GET /contacts/{email}/threads`](https://openemail.uk/docs/api/reference/contacts#get-contacts-email-threads); TypeScript [`contacts.iterateThreads()`](https://openemail.uk/docs/sdk/reference/contacts#iterateThreads); Python [`contacts.iterate_threads()`](https://openemail.uk/docs/python/reference/contacts#iterateThreads); Ruby [`contacts.iterate_threads`](https://openemail.uk/docs/ruby/reference/contacts#iterateThreads); PHP [`contacts->iterateThreads`](https://openemail.uk/docs/php/reference/contacts#iterateThreads); Go [`Contacts.IterateThreads`](https://openemail.uk/docs/go/reference/contacts#iterateThreads); Java [`contacts().iterateThreads`](https://openemail.uk/docs/java/reference/contacts#iterateThreads). ### `Contacts.ActivityAsync` Read how mail with one person has gone over a window ```csharp Task ActivityAsync( string email, int? minutes = null, string? grain = null, int? offsetMinutes = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Returns the numbers behind the Activity tab on a contact in the app, over a window that ends now: messages received from the address and sent to it per bucket, the threads that moved, the threads whose newest message is theirs and so waits on a reply from the mailbox, when each side last wrote, and the median time each side takes to answer, in milliseconds. `minutes:` sets how far back the window reaches, 90 days by default. `grain:` sets the bucket width and the key shape, `YYYY-MM-DD`, `YYYY-MM-DDTHH` or `YYYY-MM-DDTHH:MM`, and `offsetMinutes:` shifts the boundaries so days break where the reader's day does. `buckets` is sparse and oldest first. Mail in the bin or in spam is left out. Scopes: `threads:read`. **Parameters** - `email` (`string`, required): The address. It does not have to be a saved contact. - `minutes` (`int?`): Window length in minutes, from 1 to about 20 years. The server defaults to 90 days. - `grain` (`string?`): Bucket width: `minute`, `hour` or `day`, defaulting to `day`. - `offsetMinutes` (`int?`): Minutes east of UTC to cut the buckets in, from -840 to 840, defaulting to 0. Pass `(int)TimeZoneInfo.Local.GetUtcOffset(DateTimeOffset.Now).TotalMinutes` for the local zone. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` with `object` set to `contact_activity`, `email`, `since`, `until`, `grain`, `buckets`, `totals` and `replyTime`. `totals` has `received`, `sent`, `threads`, `waiting`, `lastReceivedAt` and `lastSentAt`, and `replyTime` has `yours` and `theirs`, each null when there is no reply to measure. **Example** ```csharp var activity = await client.Contacts.ActivityAsync( "grace@example.com", minutes: 30 * 24 * 60, offsetMinutes: (int)TimeZoneInfo.Local.GetUtcOffset(DateTimeOffset.Now).TotalMinutes); var totals = activity["totals"]; Console.WriteLine($"{totals?["received"]} received, {totals?["sent"]} sent, {totals?["waiting"]} waiting on a reply"); if ((double?)activity["replyTime"]?["yours"] is { } milliseconds) { Console.WriteLine($"You answer in {Math.Round(milliseconds / 3600000, 1)} hours"); } ``` **Notes** - It needs `threads:read`, because it reads mail rather than the contact. - Read only, so the SDK retries it after a network failure like any other read. - A key limited to particular addresses or domains gets 422 `capability_unsupported` on `addressAllowlist`, because a contact's threads and activity are read from the mail of every address in the workspace. Also available in: API [`GET /contacts/{email}/activity`](https://openemail.uk/docs/api/reference/contacts#get-contacts-email-activity); TypeScript [`contacts.activity()`](https://openemail.uk/docs/sdk/reference/contacts#activity); Python [`contacts.activity()`](https://openemail.uk/docs/python/reference/contacts#activity); Ruby [`contacts.activity`](https://openemail.uk/docs/ruby/reference/contacts#activity); PHP [`contacts->activity`](https://openemail.uk/docs/php/reference/contacts#activity); Go [`Contacts.Activity`](https://openemail.uk/docs/go/reference/contacts#activity); Java [`contacts().activity`](https://openemail.uk/docs/java/reference/contacts#activity); CLI [`openemail contacts activity`](https://openemail.uk/docs/cli/reference/contacts#contacts-activity). ### `Contacts.ListEventsAsync` List the events recorded for one contact ```csharp Task ListEventsAsync( string email, string? name = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Returns one page of the events `Events.SendAsync` 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. `ListAllEventsAsync` and `IterateEventsAsync` do that walk for you. Scopes: `contacts:read`. **Parameters** - `email` (`string`, required): The contact, by email address, compared without case. The `contactId` an event or an enrollment carries works here too. - `name` (`string?`): Only events with exactly this name. - `limit` (`int?`): Events per page, a whole number from 1 to 200. The server defaults to 50. - `cursor` (`string?`): 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`. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `Page` with `items`, `hasMore` and `nextCursor`. Each item has `id`, `contactId`, `email`, `name`, `properties`, `occurredAt`, `mode` and `createdAt`. **Example** ```csharp var page = await client.Contacts.ListEventsAsync("ada@example.com", name: "order.placed"); foreach (var entry in page) { Console.WriteLine($"{entry["occurredAt"]} {entry["name"]} {entry["properties"]}"); } ``` **Notes** - An address or id nobody you can reach has is 404 `contact_not_found`. An app a member connected reads only the contacts that member added. - Read only, so the SDK retries it after a network failure like any other read. Also available in: API [`GET /contacts/{email}/events`](https://openemail.uk/docs/api/reference/events#get-contacts-email-events); TypeScript [`contacts.listEvents()`](https://openemail.uk/docs/sdk/reference/contacts#listEvents); Python [`contacts.list_events()`](https://openemail.uk/docs/python/reference/contacts#listEvents); Ruby [`contacts.list_events`](https://openemail.uk/docs/ruby/reference/contacts#listEvents); PHP [`contacts->listEvents`](https://openemail.uk/docs/php/reference/contacts#listEvents); Go [`Contacts.ListEvents`](https://openemail.uk/docs/go/reference/contacts#listEvents); Java [`contacts().listEvents`](https://openemail.uk/docs/java/reference/contacts#listEvents); CLI [`openemail contacts list-events`](https://openemail.uk/docs/cli/reference/contacts#contacts-list-events). ### `Contacts.ListAllEventsAsync` Collect every event of one contact into one list ```csharp Task> ListAllEventsAsync( string email, string? name = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Follows `nextCursor` from page to page and returns every event recorded for the contact in the last 90 days, the most recent first, in the shape `ListEventsAsync` returns. `limit` sets the page size of each request, not the total. Scopes: `contacts:read`. **Parameters** - `email` (`string`, required): The contact, by email address, compared without case. The `contactId` an event or an enrollment carries works here too. - `name` (`string?`): Only events with exactly this name. - `limit` (`int?`): Page size per request, from 1 to 200, defaulting to 50 on the server. - `cursor` (`string?`): A `nextCursor` from an earlier page to start after. - `apiKey` (`string?`): Overrides the client's API key for every page of this walk. - `cancellationToken` (`CancellationToken`): Cancels the request in flight and ends the whole walk. **Returns** A list of `JsonObject` items holding every matching event across all pages, each shaped like an item of `ListEventsAsync`. **Example** ```csharp var events = await client.Contacts.ListAllEventsAsync("ada@example.com"); var names = events.Select(entry => (string?)entry["name"]).Distinct(); Console.WriteLine($"{events.Count} events: {string.Join(", ", names)}"); ``` **Notes** - A failure on any page throws out of the whole call. Also available in: API [`GET /contacts/{email}/events`](https://openemail.uk/docs/api/reference/events#get-contacts-email-events); TypeScript [`contacts.listAllEvents()`](https://openemail.uk/docs/sdk/reference/contacts#listAllEvents); Python [`contacts.list_all_events()`](https://openemail.uk/docs/python/reference/contacts#listAllEvents); Ruby [`contacts.list_all_events`](https://openemail.uk/docs/ruby/reference/contacts#listAllEvents); PHP [`contacts->listAllEvents`](https://openemail.uk/docs/php/reference/contacts#listAllEvents); Go [`Contacts.ListAllEvents`](https://openemail.uk/docs/go/reference/contacts#listAllEvents); Java [`contacts().listAllEvents`](https://openemail.uk/docs/java/reference/contacts#listAllEvents). ### `Contacts.IterateEventsAsync` Stream the events of one contact one at a time ```csharp IAsyncEnumerable IterateEventsAsync( string email, string? name = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Returns an `IAsyncEnumerable` that yields the events of a contact one by one, the most recent first, and requests the next page only once the current one is drained. Breaking out of the loop stops the requests. Scopes: `contacts:read`. **Parameters** - `email` (`string`, required): The contact, by email address, compared without case. The `contactId` an event or an enrollment carries works here too. - `name` (`string?`): Only events with exactly this name. - `limit` (`int?`): Page size per request, from 1 to 200, defaulting to 50 on the server. - `cursor` (`string?`): A `nextCursor` from an earlier page to start after. - `apiKey` (`string?`): Overrides the client's API key for every page of this walk. - `cancellationToken` (`CancellationToken`): Cancels the request in flight and ends the whole walk. **Returns** An `IAsyncEnumerable` that yields one event per step. **Example** ```csharp await foreach (var entry in client.Contacts.IterateEventsAsync("ada@example.com")) { if ((string?)entry["name"] == "plan.cancelled") { Console.WriteLine($"Cancelled on {entry["occurredAt"]}"); break; } } ``` **Notes** - The enumerable is lazy, so an abandoned loop costs only the pages you consumed. Also available in: API [`GET /contacts/{email}/events`](https://openemail.uk/docs/api/reference/events#get-contacts-email-events); TypeScript [`contacts.iterateEvents()`](https://openemail.uk/docs/sdk/reference/contacts#iterateEvents); Python [`contacts.iterate_events()`](https://openemail.uk/docs/python/reference/contacts#iterateEvents); Ruby [`contacts.iterate_events`](https://openemail.uk/docs/ruby/reference/contacts#iterateEvents); PHP [`contacts->iterateEvents`](https://openemail.uk/docs/php/reference/contacts#iterateEvents); Go [`Contacts.IterateEvents`](https://openemail.uk/docs/go/reference/contacts#iterateEvents); Java [`contacts().iterateEvents`](https://openemail.uk/docs/java/reference/contacts#iterateEvents). ### `Contacts.ListCardsAsync` List the address book as contact cards ```csharp Task ListCardsAsync( string? email = null, bool? withoutEmail = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Returns one page of contact cards, newest first. A card is a saved contact with everything an address book keeps for it: phone numbers, other email addresses, postal addresses, websites, organisation, department, job title, birthday, nickname and the name in parts. Cards with no email address, such as a plumber saved on a phone, are listed too. It is the address book phones and computers sync over CardDAV. `email:` finds the card of one saved contact, and `withoutEmail: true` lists only the cards with no address. An address that was only ever mailed, and never saved, has no card. Paging is keyset. `limit:` takes 1 to 200 and defaults to 50, and `nextCursor` goes back as `cursor:` while `hasMore` is true. Never build a cursor yourself. Scopes: `contacts:read`. **Parameters** - `email` (`string?`): Only the card of the saved contact with this address. - `withoutEmail` (`bool?`): True lists only the cards that have no email address. - `limit` (`int?`): Cards per page, a whole number from 1 to 200. The server defaults to 50. - `cursor` (`string?`): The `nextCursor` from the previous page. Never build one yourself. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `Page` of card objects, with `items`, `hasMore` and `nextCursor`. Each card has `id`, `uid`, `email`, `name`, `nameParts`, `nickname`, `organization`, `department`, `title`, `birthday`, `notes`, the lists `emails`, `phones`, `addresses` and `urls`, `photoUrl`, `createdAt` and `updatedAt`. **Example** ```csharp var page = await client.Contacts.ListCardsAsync(withoutEmail: true); foreach (var card in page) { Console.WriteLine($"{card["name"]?.ToString() ?? "No name"}: {string.Join(", ", (card["phones"]?.AsArray() ?? []).Select(row => row?["value"]))}"); } if (page.HasMore) { var next = await client.Contacts.ListCardsAsync(withoutEmail: true, cursor: page.NextCursor); Console.WriteLine($"{next.Count} more"); } ``` **Notes** - Every member reads the same address book through a key, since a key acts for the workspace owner. - A cursor that names no card is a 400 `invalid_cursor`. Start again without one. Also available in: API [`GET /contacts/cards`](https://openemail.uk/docs/api/reference/contacts#get-contacts-cards); TypeScript [`contacts.listCards()`](https://openemail.uk/docs/sdk/reference/contacts#listCards); Python [`contacts.list_cards()`](https://openemail.uk/docs/python/reference/contacts#listCards); Ruby [`contacts.list_cards`](https://openemail.uk/docs/ruby/reference/contacts#listCards); PHP [`contacts->listCards`](https://openemail.uk/docs/php/reference/contacts#listCards); Go [`Contacts.ListCards`](https://openemail.uk/docs/go/reference/contacts#listCards); Java [`contacts().listCards`](https://openemail.uk/docs/java/reference/contacts#listCards); CLI [`openemail contacts list-cards`](https://openemail.uk/docs/cli/reference/contacts#contacts-list-cards). ### `Contacts.ListAllCardsAsync` Collect every contact card into one object ```csharp Task> ListAllCardsAsync( string? email = null, bool? withoutEmail = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Follows `nextCursor` from page to page and returns every card in the address book, newest first. It takes the same `email:` and `withoutEmail:` filters as `Contacts.ListCardsAsync`. Everything is held in memory before the call returns. Prefer `Contacts.IterateCardsAsync` when you can stop early. `limit:` sets the page size of each request, not the total. Scopes: `contacts:read`. **Parameters** - `email` (`string?`): Only the card of the saved contact with this address. - `withoutEmail` (`bool?`): True lists only the cards that have no email address. - `limit` (`int?`): Page size per request, from 1 to 200, defaulting to 50 on the server. - `cursor` (`string?`): A cursor from an earlier page to start after. - `apiKey` (`string?`): Overrides the client's API key for every page of this walk. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A list of card objects holding every card across all pages. **Example** ```csharp var cards = await client.Contacts.ListAllCardsAsync(); Console.WriteLine($"{cards.Count} cards in the address book"); ``` **Notes** - A failure on any page throws out of the whole call, and the cards already fetched are discarded. Also available in: API [`GET /contacts/cards`](https://openemail.uk/docs/api/reference/contacts#get-contacts-cards); TypeScript [`contacts.listAllCards()`](https://openemail.uk/docs/sdk/reference/contacts#listAllCards); Python [`contacts.list_all_cards()`](https://openemail.uk/docs/python/reference/contacts#listAllCards); Ruby [`contacts.list_all_cards`](https://openemail.uk/docs/ruby/reference/contacts#listAllCards); PHP [`contacts->listAllCards`](https://openemail.uk/docs/php/reference/contacts#listAllCards); Go [`Contacts.ListAllCards`](https://openemail.uk/docs/go/reference/contacts#listAllCards); Java [`contacts().listAllCards`](https://openemail.uk/docs/java/reference/contacts#listAllCards). ### `Contacts.IterateCardsAsync` Stream the address book one card at a time ```csharp IAsyncEnumerable IterateCardsAsync( string? email = null, bool? withoutEmail = null, int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Returns an `IAsyncEnumerable` that yields cards one at a time, newest first, and requests the next page only once the current one is used up. Nothing is fetched until the loop starts, and breaking out of the `await foreach` stops the requests. It takes the same `email:` and `withoutEmail:` filters as `Contacts.ListCardsAsync`. Scopes: `contacts:read`. **Parameters** - `email` (`string?`): Only the card of the saved contact with this address. - `withoutEmail` (`bool?`): True lists only the cards that have no email address. - `limit` (`int?`): Page size per request, from 1 to 200, defaulting to 50 on the server. - `cursor` (`string?`): A cursor from an earlier page to start after. - `apiKey` (`string?`): Overrides the client's API key for every page of this walk. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** An `IAsyncEnumerable` that yields one card per step. **Example** ```csharp await foreach (var card in client.Contacts.IterateCardsAsync()) { if (card["birthday"] is not null) { Console.WriteLine($"{card["name"]}: {card["birthday"]}"); } } ``` **Notes** - The generator is lazy, so an abandoned loop costs only the pages you consumed. Also available in: API [`GET /contacts/cards`](https://openemail.uk/docs/api/reference/contacts#get-contacts-cards); TypeScript [`contacts.iterateCards()`](https://openemail.uk/docs/sdk/reference/contacts#iterateCards); Python [`contacts.iterate_cards()`](https://openemail.uk/docs/python/reference/contacts#iterateCards); Ruby [`contacts.iterate_cards`](https://openemail.uk/docs/ruby/reference/contacts#iterateCards); PHP [`contacts->iterateCards`](https://openemail.uk/docs/php/reference/contacts#iterateCards); Go [`Contacts.IterateCards`](https://openemail.uk/docs/go/reference/contacts#iterateCards); Java [`contacts().iterateCards`](https://openemail.uk/docs/java/reference/contacts#iterateCards). ### `Contacts.GetCardAsync` Get one contact card ```csharp Task GetCardAsync( string id, string? apiKey = null, CancellationToken cancellationToken = default) ``` Returns one card with everything it holds. To find the card of a saved contact by its address, pass `email:` to `Contacts.ListCardsAsync`. Scopes: `contacts:read`. **Parameters** - `id` (`string`, required): The card id, `ccd_` followed by 24 characters, from `Contacts.ListCardsAsync` or `Contacts.GetCardAsync`. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` with `id`, `uid`, the vCard UID that phones and computers know the card by, `email`, null on a card with no address, `name`, `nameParts`, `nickname`, `organization`, `department`, `title`, `birthday`, `notes`, `photoUrl`, `createdAt` and `updatedAt`. `emails`, `phones` and `urls` are lists of objects with `value`, `label` and `customLabel`, and `addresses` is a list of objects with `label`, `customLabel`, `street`, `locality`, `region`, `postalCode` and `country`. **Example** ```csharp try { var card = await client.Contacts.GetCardAsync("ccd_0123456789abcdef01234567"); Console.WriteLine($"{card["name"]}, {card["organization"]?.ToString() ?? "no organisation"}"); } catch (OpenEmailApiException error) when (error.IsNotFound) { Console.WriteLine("No card has that id"); } ``` **Notes** - An id that names no card is a 404 `contact_card_not_found`, thrown as an `OpenEmailApiException` whose `IsNotFound` is true. Also available in: API [`GET /contacts/cards/{id}`](https://openemail.uk/docs/api/reference/contacts#get-contacts-cards-id); TypeScript [`contacts.getCard()`](https://openemail.uk/docs/sdk/reference/contacts#getCard); Python [`contacts.get_card()`](https://openemail.uk/docs/python/reference/contacts#getCard); Ruby [`contacts.get_card`](https://openemail.uk/docs/ruby/reference/contacts#getCard); PHP [`contacts->getCard`](https://openemail.uk/docs/php/reference/contacts#getCard); Go [`Contacts.GetCard`](https://openemail.uk/docs/go/reference/contacts#getCard); Java [`contacts().getCard`](https://openemail.uk/docs/java/reference/contacts#getCard); CLI [`openemail contacts get-card`](https://openemail.uk/docs/cli/reference/contacts#contacts-get-card). ### `Contacts.CreateCardAsync` Add a card to the address book ```csharp Task CreateCardAsync( IReadOnlyDictionary body, string? apiKey = null, CancellationToken cancellationToken = default) ``` Adds a contact card. With `email` the card is a saved contact as well, the same one `Contacts.CreateAsync` makes, and an address the workspace already knows from mail becomes saved. Without one it is a card on its own, kept for its name, phone numbers and the rest. A card needs at least a name, an email address, a phone number or an organisation. Each entry in `emails`, `phones` and `urls` is an object with `value`, and optionally `label`, one of `OpenEmail\Constants\ContactCardLabels`, and `customLabel`, a label of your own. Phones and computers that sync the address book over CardDAV get the new card on their next sync. Scopes: `contacts:write`. **Parameters** - `email` (`string`): The address OpenEmail knows the contact by. With it the card is a saved contact as well. A saved contact keeps its address, so put any other address in `emails`. - `name` (`string`): The full name the address book shows, up to 200 characters. - `nameParts` (`dictionary`): The name in parts, a dictionary with `prefix`, `given`, `middle`, `family` and `suffix`, the way phones keep it. - `nickname` (`string`): A nickname. - `organization` (`string`): The company or organisation. - `department` (`string`): The department within the organisation. - `title` (`string`): The job title. - `birthday` (`string`): `YYYY-MM-DD`, or `--MM-DD` when the year is not known. - `notes` (`string`): Free-form notes. On a saved contact these are the notes the contact page shows. - `emails` (`list`): Other email addresses besides `email`, each a dictionary with `value`, and optionally `label` and `customLabel`. - `phones` (`list`): Phone numbers, each a dictionary with `value`, and optionally `label` and `customLabel`. - `addresses` (`list`): Postal addresses, each a dictionary with any of `label`, `customLabel`, `street`, `locality`, `region`, `postalCode` and `country`. - `urls` (`list`): Websites and profile links, each a dictionary with `value`, and optionally `label` and `customLabel`. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` for the new card, with the fields `Contacts.GetCardAsync` returns. **Example** ```csharp using OpenEmail.Constants; var card = await client.Contacts.CreateCardAsync(new Body { ["email"] = "ada@example.com", ["name"] = "Ada Lovelace", ["organization"] = "Analytical Engines", ["phones"] = new[] { new Body { ["value"] = "+44 20 7946 0000", ["label"] = ContactCardLabels.Work }, }, ["birthday"] = "1815-12-10", }); Console.WriteLine($"{card["id"]} {card["email"]}"); ``` **Notes** - The SDK does not retry it after a network failure, because a second call would make a second card. - An address that already belongs to another card is a 409 `contact_card_email_taken`, and a card with nothing to keep a 422 `invalid_contact_card`. - A workspace that already keeps as many cards as it may gets a 409 `contact_card_limit`. Delete some before you add more. Also available in: API [`POST /contacts/cards`](https://openemail.uk/docs/api/reference/contacts#post-contacts-cards); TypeScript [`contacts.createCard()`](https://openemail.uk/docs/sdk/reference/contacts#createCard); Python [`contacts.create_card()`](https://openemail.uk/docs/python/reference/contacts#createCard); Ruby [`contacts.create_card`](https://openemail.uk/docs/ruby/reference/contacts#createCard); PHP [`contacts->createCard`](https://openemail.uk/docs/php/reference/contacts#createCard); Go [`Contacts.CreateCard`](https://openemail.uk/docs/go/reference/contacts#createCard); Java [`contacts().createCard`](https://openemail.uk/docs/java/reference/contacts#createCard); CLI [`openemail contacts create-card`](https://openemail.uk/docs/cli/reference/contacts#contacts-create-card). ### `Contacts.UpdateCardAsync` Change a contact card ```csharp Task UpdateCardAsync( string id, IReadOnlyDictionary patch, string? apiKey = null, CancellationToken cancellationToken = default) ``` Changes the fields you send and leaves the rest alone. Null clears a field, and a list you send (`emails`, `phones`, `addresses` or `urls`) replaces the whole list, so read the card first when you mean to add one entry. On a saved contact, `name` and `notes` are the contact's own, so the contact page shows the change. `email` can only be given to a card that has none, which makes it a saved contact. A saved contact keeps its address: add another address to `emails` instead. Phones and computers that sync the address book over CardDAV get the change on their next sync. Scopes: `contacts:write`. **Parameters** - `id` (`string`, required): The card id, `ccd_` followed by 24 characters, from `Contacts.ListCardsAsync` or `Contacts.GetCardAsync`. - `email` (`string`): The address OpenEmail knows the contact by. Given to a card that has none, it makes the card a saved contact. A saved contact keeps its address, so put any other address in `emails`. - `name` (`string`): The full name the address book shows, up to 200 characters. - `nameParts` (`dictionary`): The name in parts, a dictionary with `prefix`, `given`, `middle`, `family` and `suffix`, the way phones keep it. - `nickname` (`string`): A nickname. - `organization` (`string`): The company or organisation. - `department` (`string`): The department within the organisation. - `title` (`string`): The job title. - `birthday` (`string`): `YYYY-MM-DD`, or `--MM-DD` when the year is not known. - `notes` (`string`): Free-form notes. On a saved contact these are the notes the contact page shows. - `emails` (`list`): Other email addresses besides `email`, each a dictionary with `value`, and optionally `label` and `customLabel`. The list replaces the one the card has. - `phones` (`list`): Phone numbers, each a dictionary with `value`, and optionally `label` and `customLabel`. The list replaces the one the card has. - `addresses` (`list`): Postal addresses, each a dictionary with any of `label`, `customLabel`, `street`, `locality`, `region`, `postalCode` and `country`. The list replaces the one the card has. - `urls` (`list`): Websites and profile links, each a dictionary with `value`, and optionally `label` and `customLabel`. The list replaces the one the card has. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` for the card as it stands after the change. **Example** ```csharp using OpenEmail.Constants; var card = await client.Contacts.GetCardAsync("ccd_0123456789abcdef01234567"); var phones = new List(card["phones"]?.AsArray() ?? []) { new Body { ["value"] = "+1 555 0100", ["label"] = ContactCardLabels.Mobile }, }; var updated = await client.Contacts.UpdateCardAsync(card["id"]!.GetValue(), new Body { ["phones"] = phones }); Console.WriteLine($"{updated["phones"]?.AsArray().Count} phone numbers"); ``` **Notes** - The SDK retries this call after a network failure, since the same patch sent twice leaves the same card. - Changing the address of a saved contact is a 422 `invalid_contact_card`, and an address that already belongs to another card a 409 `contact_card_email_taken`. - An id that names no card is a 404 `contact_card_not_found`. Also available in: API [`PATCH /contacts/cards/{id}`](https://openemail.uk/docs/api/reference/contacts#patch-contacts-cards-id); TypeScript [`contacts.updateCard()`](https://openemail.uk/docs/sdk/reference/contacts#updateCard); Python [`contacts.update_card()`](https://openemail.uk/docs/python/reference/contacts#updateCard); Ruby [`contacts.update_card`](https://openemail.uk/docs/ruby/reference/contacts#updateCard); PHP [`contacts->updateCard`](https://openemail.uk/docs/php/reference/contacts#updateCard); Go [`Contacts.UpdateCard`](https://openemail.uk/docs/go/reference/contacts#updateCard); Java [`contacts().updateCard`](https://openemail.uk/docs/java/reference/contacts#updateCard); CLI [`openemail contacts update-card`](https://openemail.uk/docs/cli/reference/contacts#contacts-update-card). ### `Contacts.DeleteCardAsync` Delete a contact card ```csharp Task DeleteCardAsync( string id, string? apiKey = null, CancellationToken cancellationToken = default) ``` Removes the card from the address book and from every phone and computer that syncs it. On a saved contact it is the same as `Contacts.DeleteAsync`: the contact goes with its notes, photo and audiences, and the address is hidden from the people list and the suggestions. Scopes: `contacts:write`. **Parameters** - `id` (`string`, required): The card id, `ccd_` followed by 24 characters, from `Contacts.ListCardsAsync` or `Contacts.GetCardAsync`. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` with `object` set to `contact_card`, `id` and `deleted` set to true. **Example** ```csharp var removed = await client.Contacts.DeleteCardAsync("ccd_0123456789abcdef01234567"); Console.WriteLine($"{removed["id"]} deleted"); ``` **Notes** - There is no undo, and the SDK does not retry it after a network failure. - An id that names no card is a 404 `contact_card_not_found`. Also available in: API [`DELETE /contacts/cards/{id}`](https://openemail.uk/docs/api/reference/contacts#delete-contacts-cards-id); TypeScript [`contacts.deleteCard()`](https://openemail.uk/docs/sdk/reference/contacts#deleteCard); Python [`contacts.delete_card()`](https://openemail.uk/docs/python/reference/contacts#deleteCard); Ruby [`contacts.delete_card`](https://openemail.uk/docs/ruby/reference/contacts#deleteCard); PHP [`contacts->deleteCard`](https://openemail.uk/docs/php/reference/contacts#deleteCard); Go [`Contacts.DeleteCard`](https://openemail.uk/docs/go/reference/contacts#deleteCard); Java [`contacts().deleteCard`](https://openemail.uk/docs/java/reference/contacts#deleteCard); CLI [`openemail contacts delete-card`](https://openemail.uk/docs/cli/reference/contacts#contacts-delete-card). ### `Contacts.ImportVcfAsync` Import a contacts file ```csharp Task ImportVcfAsync( Stream data, string? filename = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` 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 `GetImportAsync` 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 readable `Stream`, and it goes out as `text/vcard`. Scopes: `contacts:write`. **Parameters** - `data` (`Stream`, required): The .vcf file: a readable `Stream`. - `filename` (`string?`): The name to show for the file in the list of imports, at most 255 characters. - `cancellationToken` (`CancellationToken`): Cancels the request. - `apiKey` (`string?`): Overrides the client's API key for this call only. **Returns** A `JsonObject` with `status: queued`. **Example** ```csharp await using var file = File.OpenRead("contacts.vcf"); var import = await client.Contacts.ImportVcfAsync(file, filename: "contacts.vcf"); Console.WriteLine($"{import["id"]} is {import["status"]}"); ``` **Notes** - A body that holds no vCard is a 400 `not_a_contacts_file`, and an empty one a 400 `item_import_empty`. - A file over 20 MB is a 413 `item_import_too_large`. - To send text you already hold, encode it first with `new TextEncoder().encode(text)`. - An upload that outlasts the client `Timeout` fails as a network error, so raise it on the client for a large file on a slow connection. - Not retried automatically. Also available in: API [`POST /contacts/imports`](https://openemail.uk/docs/api/reference/contacts#post-contacts-imports); TypeScript [`contacts.importVcf()`](https://openemail.uk/docs/sdk/reference/contacts#importVcf); Python [`contacts.import_vcf()`](https://openemail.uk/docs/python/reference/contacts#importVcf); Ruby [`contacts.import_vcf`](https://openemail.uk/docs/ruby/reference/contacts#importVcf); PHP [`contacts->importVcf`](https://openemail.uk/docs/php/reference/contacts#importVcf); Go [`Contacts.ImportVcf`](https://openemail.uk/docs/go/reference/contacts#importVcf); Java [`contacts().importVcf`](https://openemail.uk/docs/java/reference/contacts#importVcf); CLI [`openemail contacts import-vcf`](https://openemail.uk/docs/cli/reference/contacts#contacts-import-vcf). ### `Contacts.ListImportsAsync` List contacts imports ```csharp Task ListImportsAsync( int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` 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 `ImportVcfAsync` 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. `ListAllImportsAsync` and `IterateImportsAsync` do that walk for you. Scopes: `contacts:read`. **Parameters** - `limit` (`int?`): Imports per page, a whole number from 1 to 100. The server defaults to 25. - `cursor` (`string?`): The `nextCursor` from the previous page. Never build one yourself. - `cancellationToken` (`CancellationToken`): Cancels the request. - `apiKey` (`string?`): Overrides the client's API key for this call only. **Returns** A `Page` with `items`, `hasMore` and `nextCursor`. **Example** ```csharp var page = await client.Contacts.ListImportsAsync(limit: 10); foreach (var import in page) { Console.WriteLine($"{import["id"]} {import["source"]} {import["status"]}: {import["counts"]?["imported"]} cards added"); } ``` **Notes** - `source` is `file` for an upload. `takeout`, `carddav` and `microsoft` came with a mailbox import. - A cursor that names no import is a 400 `invalid_cursor`. - A GET is retried automatically on network failure and on 408, 500, 502, 503 and 504 responses, up to the client `MaxRetries`, and on a 429 only when it carries a `Retry-After` of a minute or less. Also available in: API [`GET /contacts/imports`](https://openemail.uk/docs/api/reference/contacts#get-contacts-imports); TypeScript [`contacts.listImports()`](https://openemail.uk/docs/sdk/reference/contacts#listImports); Python [`contacts.list_imports()`](https://openemail.uk/docs/python/reference/contacts#listImports); Ruby [`contacts.list_imports`](https://openemail.uk/docs/ruby/reference/contacts#listImports); PHP [`contacts->listImports`](https://openemail.uk/docs/php/reference/contacts#listImports); Go [`Contacts.ListImports`](https://openemail.uk/docs/go/reference/contacts#listImports); Java [`contacts().listImports`](https://openemail.uk/docs/java/reference/contacts#listImports); CLI [`openemail contacts list-imports`](https://openemail.uk/docs/cli/reference/contacts#contacts-list-imports). ### `Contacts.ListAllImportsAsync` Collect every contacts import into one list ```csharp Task> ListAllImportsAsync( int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Follows `nextCursor` from page to page and returns every contacts import, newest first. Everything is held in memory before the call returns. Prefer `IterateImportsAsync` when you can stop early. `limit` sets the page size of each request, not the total. Scopes: `contacts:read`. **Parameters** - `limit` (`int?`): Page size per request, from 1 to 100, defaulting to 25 on the server. - `cursor` (`string?`): A cursor from an earlier page to start after. - `cancellationToken` (`CancellationToken`): Cancels the request in flight and rejects the whole walk. - `apiKey` (`string?`): Overrides the client's API key for every page of this walk. **Returns** A list of `JsonObject` items holding every import across all pages. **Example** ```csharp var imports = await client.Contacts.ListAllImportsAsync(); Console.WriteLine($"{imports.Count} contacts imports, {imports.Count(import => (bool?)import["undoable"] == true)} of them can be undone"); ``` **Notes** - A failure on any page rejects the whole call, and the imports already fetched are discarded. Also available in: API [`GET /contacts/imports`](https://openemail.uk/docs/api/reference/contacts#get-contacts-imports); TypeScript [`contacts.listAllImports()`](https://openemail.uk/docs/sdk/reference/contacts#listAllImports); Python [`contacts.list_all_imports()`](https://openemail.uk/docs/python/reference/contacts#listAllImports); Ruby [`contacts.list_all_imports`](https://openemail.uk/docs/ruby/reference/contacts#listAllImports); PHP [`contacts->listAllImports`](https://openemail.uk/docs/php/reference/contacts#listAllImports); Go [`Contacts.ListAllImports`](https://openemail.uk/docs/go/reference/contacts#listAllImports); Java [`contacts().listAllImports`](https://openemail.uk/docs/java/reference/contacts#listAllImports). ### `Contacts.IterateImportsAsync` Stream contacts imports one at a time ```csharp IAsyncEnumerable IterateImportsAsync( int? limit = null, string? cursor = null, string? apiKey = null, CancellationToken cancellationToken = default) ``` Returns an `IAsyncEnumerable` that yields contacts imports one by one, newest first, and requests the next page only once the current one is drained. Nothing is fetched until you consume it, and breaking out of the loop stops the requests. Scopes: `contacts:read`. **Parameters** - `limit` (`int?`): Page size per request, from 1 to 100, defaulting to 25 on the server. - `cursor` (`string?`): A cursor from an earlier page to start after. - `cancellationToken` (`CancellationToken`): Cancels the request in flight and rejects the whole walk. - `apiKey` (`string?`): Overrides the client's API key for every page of this walk. **Returns** An `IAsyncEnumerable` yielding one import per step. **Example** ```csharp await foreach (var import in client.Contacts.IterateImportsAsync(limit: 50)) { if ((string?)import["status"] == "failed") { Console.WriteLine($"{import["id"]} failed"); break; } } ``` **Notes** - The generator is lazy, so an abandoned loop costs only the pages you consumed. Also available in: API [`GET /contacts/imports`](https://openemail.uk/docs/api/reference/contacts#get-contacts-imports); TypeScript [`contacts.iterateImports()`](https://openemail.uk/docs/sdk/reference/contacts#iterateImports); Python [`contacts.iterate_imports()`](https://openemail.uk/docs/python/reference/contacts#iterateImports); Ruby [`contacts.iterate_imports`](https://openemail.uk/docs/ruby/reference/contacts#iterateImports); PHP [`contacts->iterateImports`](https://openemail.uk/docs/php/reference/contacts#iterateImports); Go [`Contacts.IterateImports`](https://openemail.uk/docs/go/reference/contacts#iterateImports); Java [`contacts().iterateImports`](https://openemail.uk/docs/java/reference/contacts#iterateImports). ### `Contacts.GetImportAsync` Get a contacts import ```csharp Task GetImportAsync( string id, string? apiKey = null, CancellationToken cancellationToken = default) ``` Returns one contacts import with its counts and its report: the files it read, how many cards it left out and why, and up to 20 of the cards it left out. Poll it after `ImportVcfAsync` 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`. **Parameters** - `id` (`string`, required): Contacts import id, `iimp_` followed by 24 hex characters. - `cancellationToken` (`CancellationToken`): Cancels the request. - `apiKey` (`string?`): Overrides the client's API key for this call only. **Returns** A `JsonObject` with `status`, `counts`, `report`, `undoable` and when it started, finished and was undone. **Example** ```csharp var import = await client.Contacts.GetImportAsync("iimp_3f9a1c07d2b84e6a9c5b1f20"); Console.WriteLine($"{import["status"]}: {import["counts"]?["imported"]} added, {import["counts"]?["skipped"]} left out"); ``` **Notes** - An id that names no contacts import is a 404 `item_import_not_found`. - A GET is retried automatically on network failure and on 408, 500, 502, 503 and 504 responses, up to the client `MaxRetries`, and on a 429 only when it carries a `Retry-After` of a minute or less. Also available in: API [`GET /contacts/imports/{id}`](https://openemail.uk/docs/api/reference/contacts#get-contacts-imports-id); TypeScript [`contacts.getImport()`](https://openemail.uk/docs/sdk/reference/contacts#getImport); Python [`contacts.get_import()`](https://openemail.uk/docs/python/reference/contacts#getImport); Ruby [`contacts.get_import`](https://openemail.uk/docs/ruby/reference/contacts#getImport); PHP [`contacts->getImport`](https://openemail.uk/docs/php/reference/contacts#getImport); Go [`Contacts.GetImport`](https://openemail.uk/docs/go/reference/contacts#getImport); Java [`contacts().getImport`](https://openemail.uk/docs/java/reference/contacts#getImport); CLI [`openemail contacts get-import`](https://openemail.uk/docs/cli/reference/contacts#contacts-get-import). ### `Contacts.UndoImportAsync` Remove what a contacts import added ```csharp Task UndoImportAsync( string id, string? apiKey = null, CancellationToken cancellationToken = default) ``` 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`. **Parameters** - `id` (`string`, required): Contacts import id, `iimp_` followed by 24 hex characters. - `cancellationToken` (`CancellationToken`): Cancels the request. - `apiKey` (`string?`): Overrides the client's API key for this call only. **Returns** A `JsonObject` with `status: undone` and `undoneAt` set. **Example** ```csharp try { var undone = await client.Contacts.UndoImportAsync("iimp_3f9a1c07d2b84e6a9c5b1f20"); Console.WriteLine($"{undone["id"]} is {undone["status"]} since {undone["undoneAt"]}"); } catch (OpenEmailApiException error) when (error.IsConflict) { Console.WriteLine("That import is still running or was already removed"); } ``` **Notes** - An import that is still running, or was already removed, is a 409 `item_import_not_undoable`. `undoable` on the import says whether the call would remove anything. - An id that names no contacts import is a 404 `item_import_not_found`. - Not retried automatically. Also available in: API [`POST /contacts/imports/{id}/undo`](https://openemail.uk/docs/api/reference/contacts#post-contacts-imports-id-undo); TypeScript [`contacts.undoImport()`](https://openemail.uk/docs/sdk/reference/contacts#undoImport); Python [`contacts.undo_import()`](https://openemail.uk/docs/python/reference/contacts#undoImport); Ruby [`contacts.undo_import`](https://openemail.uk/docs/ruby/reference/contacts#undoImport); PHP [`contacts->undoImport`](https://openemail.uk/docs/php/reference/contacts#undoImport); Go [`Contacts.UndoImport`](https://openemail.uk/docs/go/reference/contacts#undoImport); Java [`contacts().undoImport`](https://openemail.uk/docs/java/reference/contacts#undoImport); CLI [`openemail contacts undo-import`](https://openemail.uk/docs/cli/reference/contacts#contacts-undo-import).