Contacts
The address book this mailbox writes to.
Contacts tools
| Tool | What it does |
|---|---|
| listContacts | The people this mailbox writes to, newest correspondence first, a page at a time. Search by name or address, narrow to one audience, or separate the ones somebody added from the ones that were recorded. |
| getContact | One contact by email address, with its notes in full and every audience it sits in. |
| createContact | Add a contact by hand. One contact per address, so an address already here is refused rather than written twice. The new contact joins the default audience. |
| updateContact | Change a contact's name or the notes kept against it. Passing null clears a field, leaving it out leaves it alone. |
| deleteContact | Delete somebody from the contacts the way Delete does on the Contacts page: the saved contact goes with its notes, photo and audiences, and the address is hidden so a send does not record it again. It can be an address only ever seen in mail. |
| listPeople | Everyone on the Contacts page, a page at a time: the saved contacts and every address seen in mail, with thread counts and when mail last moved. Sort by recent, name or threads, search, or ask for only the blocked ones. |
| saveContact | Add to contacts or Keep in contacts: saves an address that is not a contact yet, keeps one recorded from a send as saved by hand, and brings back a deleted one. |
| deleteContacts | Delete up to 200 people in one call, each the way deleteContact deletes one. |
| blockContact | Put an address on the workspace blocklist so mail from it is refused. An address a rule already blocks is left as it is and the rule is named. |
| unblockContact | Take every workspace blocklist rule that blocks an address off the list. A whole-domain rule unblocks the whole domain, and the answer says so. |
| listContactThreads | The conversations with one person, in every folder, newest first, a page at a time, with a search inside them. |
| getContactActivity | How mail with one person has gone over a window: received and sent per day, hour or minute, threads waiting on your reply, and the median reply time each way. |
| setContactPhoto | Set the photo of a saved contact from an image in base64, replacing any there was. |
| removeContactPhoto | Remove the photo of a saved contact and delete the stored image. |
| listContactCards | The address book as cards, newest first, a page at a time: every saved contact with its phone numbers, addresses, organisation and birthday, plus the cards that have no email address. |
| getContactCard | One card in full, by its id or by the address of a saved contact. |
| createContactCard | Add a card. With an email address it is a saved contact as well; without one it keeps a name and a phone number on their own. |
| updateContactCard | Change a card. A list you pass, such as phones, replaces the whole list, and a saved contact keeps its address. |
| deleteContactCard | Delete a card from the address book and from every phone that syncs it. On a saved contact it deletes the contact too. |
| listContactImports | The contacts files and address books brought in, newest first, with how many contacts each added, found already here and left out. |
| getContactImport | One contacts import with its report: what it read and what it left out, and why. |
| undoContactImport | Remove every card one contacts import added. Contacts saved before it stay. In the app’s chat it always asks first. |
| findDuplicateContacts | Cards that look like the same person: a shared email address or phone number, or the same full name, with the most complete card first. |
| mergeContactCards | Fold the cards of one person into one and delete the rest, keeping every address, number and link. In the app’s chat it always asks first. |
| listBirthdays | The birthdays in the address book between two dates, with the age each person turns when the card holds the year. |
The workspace owner sees and edits every contact. Anyone else, a team member or a password sign-in, sees and edits only the contacts they added or wrote to themselves, and adding an address somebody else already holds is refused. A contact is recorded automatically the first time a message goes out to an address from the app composer; mail arriving from an address writes nothing.
The address is the identity and there is no id. updateContact therefore cannot change it, and moving somebody to a new address is a createContact and a deleteContact. createContact takes no source: anything made here is manual, and a send never downgrades that back to auto.
None of this sends anything or subscribes anybody to anything, and deleteContact unsubscribes nobody, because this mailbox holds no subscription state at all. A deleted address stays hidden, so writing to it again does not record it again, until createContact or saveContact brings it back.
listPeople lists the addresses seen in mail only for somebody who may read the mail and is not limited to some addresses; anyone else gets their saved contacts alone. blockContact and unblockContact change the workspace blocklist, so they need the permission to change settings rather than contacts. deleteContacts always asks before it runs, like deleteContact; saving, blocking and unblocking ask unless you asked for them. setContactPhoto takes the image in base64, and only the workspace owner sets or removes a contact photo from a client.
Every saved contact is also a card in the address book that phones and computers sync over CardDAV, so a change made here reaches them on their next sync. createContactCard and updateContactCard ask unless you asked for them, and deleteContactCard always asks first.
No tool uploads a contacts file, because a tool call carries no file. Upload a .vcf file on the Contacts page of the app or with POST /contacts/imports, then read or undo the import here. Imported contacts join no audience.
Groups are cards too: createContactCard with kind set to group and members makes one, and listContactCards takes kind and groupId. findDuplicateContacts and listBirthdays only read, and mergeContactCards always asks first.
Reference
listContacts
The people this mailbox writes to. A contact is recorded automatically the first time a message goes out to an address, and one can also be added by hand. Newest correspondence first. Pass q to search the name and the address, audienceId to see one list only, and source to separate the ones somebody added from the ones that were recorded. The owner of the mailbox sees every contact; anyone else sees only the contacts they added or wrote to themselves. One page at a time: when more follow, the last line gives a cursor to pass back, with the same filters, for the next page.
Inputs
qstring- Up to 200 characters
sourcestring- One of
"manual""auto""form" audienceIdstringlimitinteger- At least 1At most 200Default
50 cursorstring
Also available in
- API
GET /contacts- TypeScript
nextmail.contacts.list()nextmail.contacts.listAll()nextmail.contacts.iterate()- Python
contacts.list()contacts.list_all()contacts.iterate()- Ruby
contacts.listcontacts.list_allcontacts.iterate- PHP
contacts->listcontacts->listAllcontacts->iterate- Go
Contacts.ListContacts.ListAllContacts.Iterate- Java
contacts().listcontacts().listAllcontacts().iterate- C#
Contacts.ListAsyncContacts.ListAllAsyncContacts.IterateAsync
getContact
One contact, by email address. Contacts are addressed here by address and never by id, because the address is the part a person knows and the part the API publishes. Returns the notes in full, the custom fields and every audience the contact sits in. A connection that may also read forms gets the sign-ups this address sent through sign-up forms, newest first and at most 20: the form, whether the person was added or still has to confirm, the page it came from and every answer. Anybody but the workspace owner sees only the sign-ups of forms they made.
Inputs
emailstringRequired- Format
email
Also available in
- API
GET /contacts/{email}- TypeScript
nextmail.contacts.get()- Python
contacts.get()- Ruby
contacts.get- PHP
contacts->get- Go
Contacts.Get- Java
contacts().get- C#
Contacts.GetAsync
createContact
Add a contact by hand. The address is the identity: one contact per address per mailbox, so this refuses an address that is already here rather than writing a second row, and updateContact changes the one that is there. The new contact joins the default audience, which holds every contact on the mailbox; addContactToAudience puts it in a list of your own. attributes sets custom fields, which automations can read and branch on. Adding a contact sends nothing and subscribes nobody to anything.
Inputs
emailstringRequired- Format
email namestring- Up to 200 characters
notesstring- Up to 5000 characters
attributesRecord<string, string>Custom fields to set on the contact, as an object of keys and text values. A key starts with a letter and holds up to 64 letters, digits and underscores, a value is text of at most 500 characters, and a contact holds at most 50 fields. Null or an empty string removes a field, and a field left out keeps its value.
Also available in
- API
PATCH /contacts/{email}POST /contactsPUT /contacts/{email}- TypeScript
nextmail.contacts.update()nextmail.contacts.create()nextmail.contacts.save()- Python
contacts.update()contacts.create()contacts.save()- Ruby
contacts.updatecontacts.createcontacts.save- PHP
contacts->updatecontacts->createcontacts->save- Go
Contacts.UpdateContacts.CreateContacts.Save- Java
contacts().updatecontacts().createcontacts().save- C#
Contacts.UpdateAsyncContacts.CreateAsyncContacts.SaveAsync
updateContact
Change a contact’s name, the notes kept against it or its custom fields. Passing null clears a field; leaving it out leaves it alone. attributes changes only the custom fields it names. The address cannot be changed here. A contact IS its address, so a different address is a different contact: createContact makes it and deleteContact removes the old one.
Inputs
emailstringRequired- Format
email namestring- Can be nullUp to 200 characters
notesstring- Can be nullUp to 5000 characters
attributesRecord<string, string>Custom fields to set on the contact, as an object of keys and text values. A key starts with a letter and holds up to 64 letters, digits and underscores, a value is text of at most 500 characters, and a contact holds at most 50 fields. Null or an empty string removes a field, and a field left out keeps its value.
Also available in
- API
PATCH /contacts/{email}POST /contactsPUT /contacts/{email}- TypeScript
nextmail.contacts.update()nextmail.contacts.create()nextmail.contacts.save()- Python
contacts.update()contacts.create()contacts.save()- Ruby
contacts.updatecontacts.createcontacts.save- PHP
contacts->updatecontacts->createcontacts->save- Go
Contacts.UpdateContacts.CreateContacts.Save- Java
contacts().updatecontacts().createcontacts().save- C#
Contacts.UpdateAsyncContacts.CreateAsyncContacts.SaveAsync
deleteContact
Delete somebody from the contacts, the way Delete does on the Contacts page. The saved contact goes, with its notes, its photo and every audience it was in, and the address is hidden: it leaves the people list and the recipient suggestions, and writing to it again does not record it again. The address can be somebody who was only ever seen in mail. createContact or saveContact brings it back. It deletes no mail and unsubscribes nobody, because this mailbox holds no subscription state. Anybody but the workspace owner deletes only contacts they added, and hides nothing.
Inputs
emailstringRequired- Format
email
Also available in
listPeople
Everyone on the Contacts page: the saved contacts and, for somebody who may read the mail, every address seen in it as a sender or a recipient, with how many threads each shares with the mailbox and when mail last moved. listContacts is only the saved ones. Sort by recent (the default), name or threads. Pass q to search names, addresses and notes, and blocked: true for only the people the workspace blocklist blocks, whole-domain rules included. Deleted addresses are left out, and so are the mailbox's own addresses. Anybody but the workspace owner sees only the saved contacts they added, and the addresses seen in mail are listed only for the owner, through an app that reaches every address. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.
Inputs
qstring- Up to 200 characters
sortstring- One of
"recent""name""threads" blockedbooleanlimitinteger- At least 1At most 100
cursorstring
Also available in
- API
GET /contacts/people- TypeScript
nextmail.contacts.listPeople()nextmail.contacts.listAllPeople()nextmail.contacts.iteratePeople()- Python
contacts.list_people()contacts.list_all_people()contacts.iterate_people()- Ruby
contacts.list_peoplecontacts.list_all_peoplecontacts.iterate_people- PHP
contacts->listPeoplecontacts->listAllPeoplecontacts->iteratePeople- Go
Contacts.ListPeopleContacts.ListAllPeopleContacts.IteratePeople- Java
contacts().listPeoplecontacts().listAllPeoplecontacts().iteratePeople- C#
Contacts.ListPeopleAsyncContacts.ListAllPeopleAsyncContacts.IteratePeopleAsync
saveContact
Save somebody as a contact, the way Add to contacts and Keep in contacts do on the Contacts page. An address that is not a contact yet becomes one; one recorded from a send is kept as added by hand; one already saved stays as it is. A name given replaces the stored name and one left out keeps it; notes given replace the stored notes, null clears them. attributes sets the custom fields it names and keeps the rest. A deleted address is brought back. Adding a contact sends nothing and subscribes nobody.
Inputs
emailstringRequired- Format
email namestring- Up to 200 characters
notesstring- Can be nullUp to 5000 characters
attributesRecord<string, string>Custom fields to set on the contact, as an object of keys and text values. A key starts with a letter and holds up to 64 letters, digits and underscores, a value is text of at most 500 characters, and a contact holds at most 50 fields. Null or an empty string removes a field, and a field left out keeps its value.
Also available in
- API
PATCH /contacts/{email}POST /contactsPUT /contacts/{email}- TypeScript
nextmail.contacts.update()nextmail.contacts.create()nextmail.contacts.save()- Python
contacts.update()contacts.create()contacts.save()- Ruby
contacts.updatecontacts.createcontacts.save- PHP
contacts->updatecontacts->createcontacts->save- Go
Contacts.UpdateContacts.CreateContacts.Save- Java
contacts().updatecontacts().createcontacts().save- C#
Contacts.UpdateAsyncContacts.CreateAsyncContacts.SaveAsync
deleteContacts
Delete up to 200 people from the contacts in one call, the way deleteContact does one: each saved contact goes with its notes, photo and audiences, and each address is hidden so a send does not record it again. Addresses that were only seen in mail are hidden too. It cannot be undone, and it deletes no mail. Anybody but the workspace owner deletes only contacts they added, and hides nothing.
Inputs
emailsstring[]Required- 1 to 200 items
Also available in
blockContact
Block an address, the way Block does on a contact: it goes on the workspace blocklist, and mail from it is refused from then on. A plus tag is dropped, so blocking ada+news@example.com blocks ada@example.com. An address that a rule already blocks, a whole-domain rule included, is left as it is and the rule is named.
Inputs
emailstringRequired- Format
email
unblockContact
Unblock an address, the way Unblock does on a contact: every rule on the workspace blocklist that blocks it is taken off. When the rule is a whole domain, that unblocks everybody at the domain, and the answer says so. Rules set in the settings for one address or one domain are not touched.
Inputs
emailstringRequired- Format
email
listContactThreads
The conversations with one person, the Mail tab on a contact: every thread they wrote or were written to, in every folder, newest first unless sort says otherwise. Pass q to search inside those threads. The address does not have to be a saved contact. A thread whose newest message arrived encrypted is marked on its line. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.
Inputs
emailstringRequired- Format
email qstring- Up to 200 characters
sortstring- One of
"newest""oldest""sender""subject" limitinteger- At least 1At most 100
cursorstring
getContactActivity
How mail with one person has gone over a window that ends now, the Activity tab on a contact: messages received from them and sent to them per day, hour or minute, the threads that moved, how many threads wait on a reply from you, when each side last wrote, and the median time each side takes to answer. minutes sets the window (90 days by default), and offsetMinutes is the reader's UTC offset so days fall on their calendar. Mail in the bin or spam is left out.
Inputs
emailstringRequired- Format
email minutesinteger- At least 1At most 10540800
grainstring- One of
"minute""hour""day" offsetMinutesinteger- At least -840At most 840
Also available in
setContactPhoto
Set the photo of a saved contact, replacing any there was, as the contact page does. Pass the picture in base64 as image, with its type as contentType, up to 5 MB. Only the workspace owner sets contact photos from an app.
Inputs
emailstringRequired- Format
email imagestringRequiredThe image in base64, or as a data: URL.
1 to 7340032 characterscontentTypestringRequiredThe type of the image, such as image/png.
1 to 100 characters
Also available in
removeContactPhoto
Remove the photo of a saved contact and delete the stored image. Removing a photo from a contact that has none changes nothing.
Inputs
emailstringRequired- Format
email
Also available in
listContactCards
The address book as cards: every saved contact with its phone numbers, postal addresses, organisation and birthday, plus cards that have no email address, such as a plumber saved on a phone. Newest first. Pass withoutEmail to list only the cards with no address. getContactCard finds the card of one contact by email. Groups are cards too: kind: group lists only the groups, and groupId lists the cards in one group. One page at a time: when more follow, the last line gives a cursor to pass back.
Inputs
withoutEmailbooleankindstring- One of
"individual""group" groupIdstringOnly the cards in the group with this id.
1 to 64 characterslimitinteger- At least 1At most 200
cursorstring
Also available in
- API
GET /contacts/cards- TypeScript
nextmail.contacts.listCards()nextmail.contacts.listAllCards()nextmail.contacts.iterateCards()- Python
contacts.list_cards()contacts.list_all_cards()contacts.iterate_cards()- Ruby
contacts.list_cardscontacts.list_all_cardscontacts.iterate_cards- PHP
contacts->listCardscontacts->listAllCardscontacts->iterateCards- Go
Contacts.ListCardsContacts.ListAllCardsContacts.IterateCards- Java
contacts().listCardscontacts().listAllCardscontacts().iterateCards- C#
Contacts.ListCardsAsyncContacts.ListAllCardsAsyncContacts.IterateCardsAsync
getContactCard
One card in full: phone numbers, other email addresses, postal addresses, websites, organisation, job title, birthday and notes. Pass id, or email for the card of a saved contact.
Inputs
idstring- 1 to 64 characters
emailstring- 1 to 320 characters
Also available in
- API
GET /contacts/cardsGET /contacts/cards/{id}- TypeScript
nextmail.contacts.listCards()nextmail.contacts.listAllCards()nextmail.contacts.iterateCards()nextmail.contacts.getCard()- Python
contacts.list_cards()contacts.list_all_cards()contacts.iterate_cards()contacts.get_card()- Ruby
contacts.list_cardscontacts.list_all_cardscontacts.iterate_cardscontacts.get_card- PHP
contacts->listCardscontacts->listAllCardscontacts->iterateCardscontacts->getCard- Go
Contacts.ListCardsContacts.ListAllCardsContacts.IterateCardsContacts.GetCard- Java
contacts().listCardscontacts().listAllCardscontacts().iterateCardscontacts().getCard- C#
Contacts.ListCardsAsyncContacts.ListAllCardsAsyncContacts.IterateCardsAsyncContacts.GetCardAsync
createContactCard
Add a card to the address book. With email it is also a saved contact, and an address already known from mail becomes saved. Without one it is a card on its own, for a name and phone number. A card needs a name, an email address, a phone number or an organisation. kind: group with a name and members (card ids) makes a group, the groups phones keep. Adding a card sends nothing.
Inputs
emailstringThe address Nextmail knows the contact by. Give it to a card that has none and the card becomes a saved contact. A saved contact keeps its address, so put any other address in emails.
Can be nullUp to 320 charactersFormatemailnamestringThe full name the address book shows.
Can be nullUp to 200 charactersnamePartsobjectThe name in parts, the way phones keep it. Left out, phones split name themselves.
Can be nullprefixstringA title before the name, such as Dr.
Can be nullUp to 200 charactersDefaultnullgivenstringThe first name.
Can be nullUp to 200 charactersDefaultnullmiddlestringAny middle names.
Can be nullUp to 200 charactersDefaultnullfamilystringThe surname.
Can be nullUp to 200 charactersDefaultnullsuffixstringAnything after the name, such as Jr.
Can be nullUp to 200 charactersDefaultnull
nicknamestringA nickname.
Can be nullUp to 200 charactersorganizationstringThe company or organisation.
Can be nullUp to 200 charactersdepartmentstringThe department within the organisation.
Can be nullUp to 200 characterstitlestringThe job title.
Can be nullUp to 200 charactersbirthdaystringYYYY-MM-DD, or --MM-DD when the year is not known.
Can be nullPattern^(?:\d{4}-|--)(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$notesstringFree-form notes. On a saved contact these are the notes the contact page shows.
Can be nullUp to 5000 charactersemailsobject[]Other email addresses, besides email. Given, it replaces the whole list.
Up to 50 itemsvaluestringRequiredThe email address.
Up to 320 charactersFormatemaillabelstringWhat the entry is for: home, work, mobile, main, fax, pager or other.
One of"home""work""mobile""main""fax""pager""other"Default"other"customLabelstringA label of your own, such as Assistant. Address books that support it show it instead of label.
Can be nullUp to 60 charactersDefaultnull
phonesobject[]Phone numbers. Given, it replaces the whole list.
Up to 50 itemsvaluestringRequiredThe number or the link.
1 to 320 characterslabelstringWhat the entry is for: home, work, mobile, main, fax, pager or other.
One of"home""work""mobile""main""fax""pager""other"Default"other"customLabelstringA label of your own, such as Assistant. Address books that support it show it instead of label.
Can be nullUp to 60 charactersDefaultnull
addressesobject[]Postal addresses. Given, it replaces the whole list.
Up to 50 itemslabelstringWhat the entry is for: home, work, mobile, main, fax, pager or other.
One of"home""work""mobile""main""fax""pager""other"Default"other"customLabelstringA label of your own, such as Assistant. Address books that support it show it instead of label.
Can be nullUp to 60 charactersDefaultnullstreetstringThe street and house number, on as many lines as it needs.
Can be nullUp to 200 charactersDefaultnulllocalitystringThe city or town.
Can be nullUp to 200 charactersDefaultnullregionstringThe state, county or province.
Can be nullUp to 200 charactersDefaultnullpostalCodestringThe postal code.
Can be nullUp to 200 charactersDefaultnullcountrystringThe country.
Can be nullUp to 200 charactersDefaultnull
urlsobject[]Websites and profile links. Given, it replaces the whole list.
Up to 50 itemsvaluestringRequiredThe number or the link.
1 to 320 characterslabelstringWhat the entry is for: home, work, mobile, main, fax, pager or other.
One of"home""work""mobile""main""fax""pager""other"Default"other"customLabelstringA label of your own, such as Assistant. Address books that support it show it instead of label.
Can be nullUp to 60 charactersDefaultnull
kindstringindividualfor a person or a company,groupfor a list of other cards, the groups phones keep.One of"individual""group"membersstring[]The ids of the cards in the group. Only a group takes it, and a list you send replaces the whole list.
Up to 2000 items
Also available in
updateContactCard
Change a card. Only the fields you pass change; null clears one, and a list you pass (emails, phones, addresses, urls) replaces the whole list, so read the card first with getContactCard and send the full list back with your change. On a saved contact, name and notes are the contact’s own. email can only be given to a card that has none: a saved contact keeps its address, so add another address to emails instead. On a group, members replaces the whole list of card ids, so send the ids already in it with the ones you add.
Inputs
idstringRequired- 1 to 64 characters
emailstringThe address Nextmail knows the contact by. Give it to a card that has none and the card becomes a saved contact. A saved contact keeps its address, so put any other address in emails.
Can be nullUp to 320 charactersFormatemailnamestringThe full name the address book shows.
Can be nullUp to 200 charactersnamePartsobjectThe name in parts, the way phones keep it. Left out, phones split name themselves.
Can be nullprefixstringA title before the name, such as Dr.
Can be nullUp to 200 charactersDefaultnullgivenstringThe first name.
Can be nullUp to 200 charactersDefaultnullmiddlestringAny middle names.
Can be nullUp to 200 charactersDefaultnullfamilystringThe surname.
Can be nullUp to 200 charactersDefaultnullsuffixstringAnything after the name, such as Jr.
Can be nullUp to 200 charactersDefaultnull
nicknamestringA nickname.
Can be nullUp to 200 charactersorganizationstringThe company or organisation.
Can be nullUp to 200 charactersdepartmentstringThe department within the organisation.
Can be nullUp to 200 characterstitlestringThe job title.
Can be nullUp to 200 charactersbirthdaystringYYYY-MM-DD, or --MM-DD when the year is not known.
Can be nullPattern^(?:\d{4}-|--)(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$notesstringFree-form notes. On a saved contact these are the notes the contact page shows.
Can be nullUp to 5000 charactersemailsobject[]Other email addresses, besides email. Given, it replaces the whole list.
Up to 50 itemsvaluestringRequiredThe email address.
Up to 320 charactersFormatemaillabelstringWhat the entry is for: home, work, mobile, main, fax, pager or other.
One of"home""work""mobile""main""fax""pager""other"Default"other"customLabelstringA label of your own, such as Assistant. Address books that support it show it instead of label.
Can be nullUp to 60 charactersDefaultnull
phonesobject[]Phone numbers. Given, it replaces the whole list.
Up to 50 itemsvaluestringRequiredThe number or the link.
1 to 320 characterslabelstringWhat the entry is for: home, work, mobile, main, fax, pager or other.
One of"home""work""mobile""main""fax""pager""other"Default"other"customLabelstringA label of your own, such as Assistant. Address books that support it show it instead of label.
Can be nullUp to 60 charactersDefaultnull
addressesobject[]Postal addresses. Given, it replaces the whole list.
Up to 50 itemslabelstringWhat the entry is for: home, work, mobile, main, fax, pager or other.
One of"home""work""mobile""main""fax""pager""other"Default"other"customLabelstringA label of your own, such as Assistant. Address books that support it show it instead of label.
Can be nullUp to 60 charactersDefaultnullstreetstringThe street and house number, on as many lines as it needs.
Can be nullUp to 200 charactersDefaultnulllocalitystringThe city or town.
Can be nullUp to 200 charactersDefaultnullregionstringThe state, county or province.
Can be nullUp to 200 charactersDefaultnullpostalCodestringThe postal code.
Can be nullUp to 200 charactersDefaultnullcountrystringThe country.
Can be nullUp to 200 charactersDefaultnull
urlsobject[]Websites and profile links. Given, it replaces the whole list.
Up to 50 itemsvaluestringRequiredThe number or the link.
1 to 320 characterslabelstringWhat the entry is for: home, work, mobile, main, fax, pager or other.
One of"home""work""mobile""main""fax""pager""other"Default"other"customLabelstringA label of your own, such as Assistant. Address books that support it show it instead of label.
Can be nullUp to 60 charactersDefaultnull
kindstringindividualfor a person or a company,groupfor a list of other cards, the groups phones keep.One of"individual""group"membersstring[]The ids of the cards in the group. Only a group takes it, and a list you send replaces the whole list.
Up to 2000 items
Also available in
deleteContactCard
Delete a card from the address book and from every phone and computer that syncs it. On a saved contact this deletes the contact too, the way deleteContact does: its notes, photo and audiences go and the address is hidden. A chat always asks first.
Inputs
idstringRequired- 1 to 64 characters
Also available in
listContactImports
The contact imports of this workspace, newest first, as Import on the Contacts page of the app lists them: a .vcf file somebody uploaded, the contacts inside a Google Takeout archive, or the address book pulled from an old mailbox. Each line says how many contacts it found, added, found already here and left out. Imported contacts join no audience. A member sees their own. Uploading a file takes bytes a tool call does not carry, so that is done in the app, over the REST API or with the CLI. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.
Inputs
limitinteger- At least 1At most 100
cursorstring
Also available in
- API
GET /contacts/imports- TypeScript
nextmail.contacts.listImports()nextmail.contacts.listAllImports()nextmail.contacts.iterateImports()- Python
contacts.list_imports()contacts.list_all_imports()contacts.iterate_imports()- Ruby
contacts.list_importscontacts.list_all_importscontacts.iterate_imports- PHP
contacts->listImportscontacts->listAllImportscontacts->iterateImports- Go
Contacts.ListImportsContacts.ListAllImportsContacts.IterateImports- Java
contacts().listImportscontacts().listAllImportscontacts().iterateImports- C#
Contacts.ListImportsAsyncContacts.ListAllImportsAsyncContacts.IterateImportsAsync
getContactImport
One contact import by its id, with its report: the address books the file held and how many cards each gave, how many were left out and why, and the first few that were not brought in.
Inputs
idstringRequired- 1 to 64 characters
Also available in
undoContactImport
Remove every card one contact import added, with the contact it created, as Remove imported contacts does in the app. Contacts that were saved before it stay. It cannot be taken back, though the same file can be imported again. A chat always asks first.
Inputs
idstringRequired- 1 to 64 characters
Also available in
findDuplicateContacts
Cards that look like the same person: they share an email address or a phone number, or have the same full name. Each group lists its cards, the most complete first, which is the one mergeContactCards should keep. Groups found by a shared address come first. It reads the address book and changes nothing.
Inputs
Takes no input.
Also available in
mergeContactCards
Merge cards of one person into a single card. id is the card to keep and cardIds the cards to fold into it. Folds the other cards into this one and deletes them. Fields this card leaves empty are filled from the others, and every email address, phone number, postal address and link is kept. Groups that held the others hold this card instead. A chat always asks first.
Inputs
idstringRequired- 1 to 64 characters
cardIdsstring[]RequiredThe cards to fold into this one. They are deleted once their details are kept.
1 to 10 items
Also available in
listBirthdays
The birthdays of the people in the address book that fall between from and to, one entry for each date, with their age when the card holds the year of birth. Someone born on 29 February has their birthday on 28 February in other years. One line each with the date, the name, the card id and the age they turn. from and to are ISO 8601 with a zone, at most a year apart, and timezone (an IANA zone, UTC unless you say) decides which days the window covers.
Inputs
fromstringRequired- Format
date-time tostringRequired- Format
date-time timezonestring- 1 to 64 characters
Google Workspace
Fastmail