---
title: Filling Contacts from mail
description: Client desk works out who Sam writes to most from sent mail, reads their signatures, and saves them as contacts.
agents: [Client desk]
tools: [start_thread, search.search, search.read, mail.search, mail.read, contacts.add_many]
source: [packages/agents/src/tools/features.ts, packages/agents/src/tools/search.ts]
---

> Roadstar docs for agents. Every page, as markdown: https://docs.roadstar.app/llms.txt

## What Sam said

In Client desk's chat:

> Can you fill Contacts from my email? Just real people I work with, no newsletters.

The chat starts a thread for it:

```json title="start_thread"
{ "title": "Contacts from mail", "task": "Fill Contacts with the people Sam writes to, from Sam's sent mail. Real people only: no newsletters or automated mail." }
```

## 1. Who Sam writes to most

Where search is on, one search over the mail Sam sent gives exact counts by person. `bulk: false` leaves out newsletters and automated mail:

```json title="use_tool"
{ "name": "search.search", "input": { "dir": "sent", "bulk": false, "after": "2026-05-01", "limit": 20 } }
```

Its `counts.people` lists who Sam wrote to, most first: Dana Whitfield, Rosa Ortiz, Marco Ruiz of Ruiz Print Co., and fourteen more.

Without search, `mail.search` with Gmail's own words does the same job, a page at a time:

```json title="use_tool"
{ "name": "mail.search", "input": { "query": "in:sent -category:promotions", "after": "2026-05-01", "limit": 20 } }
```

## 2. Names, roles and phones from their latest messages

For each person, the thread reads their latest message to Sam, where signatures give job titles and phones:

```json title="use_tool"
{ "name": "search.read", "input": { "id": "gmail:7c41e2d0:t:19a2c4e07d5b3f18" } }
```

## 3. Saving them, all at once

Adding contacts needs no yes. Addresses already on a contact are reported, not added twice:

```json title="use_tool"
{
  "name": "contacts.add_many",
  "input": {
    "people": [
      { "name": "Dana Whitfield", "emails": ["dana@juniperdental.test"], "jobTitle": "Practice manager", "company": "Juniper Dental", "labels": ["Client"] },
      { "name": "Rosa Ortiz", "emails": ["rosa@ortizbakery.test"], "jobTitle": "Owner", "phone": "+1 555 0142", "company": "Ortiz Bakery", "labels": ["Client"] },
      { "name": "Marco Ruiz", "emails": ["marco@ruizprint.test"], "jobTitle": "Print manager", "company": "Ruiz Print Co.", "labels": ["Supplier"] }
    ]
  }
}
```

`company` is a name: a company the workspace doesn't have yet is made.

## 4. It answers

> Added 17 people to Contacts from your sent mail since May: 11 clients, 4 suppliers, 2 others. Dana Whitfield was already there.

Every contact it added shows on Home with Undo.

## Related

- [Contacts](/tools/contacts/), [Companies](/tools/companies/), [Search](/tools/search/), [Mail](/tools/mail/)