skills/resend-cli/references/contacts.md

# contacts

Detailed flag specifications for `resend contacts` commands.

---

## contacts list

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--limit <n>` | number | 10 | Max results (1-100) |
| `--after <cursor>` | string | — | Forward pagination |
| `--before <cursor>` | string | — | Backward pagination |

---

## contacts create

| Flag | Type | Required | Description |
|------|------|----------|-------------|
| `--email <email>` | string | Yes | Contact email |
| `--first-name <name>` | string | No | First name |
| `--last-name <name>` | string | No | Last name |
| `--unsubscribed` | boolean | No | Globally unsubscribe |
| `--properties <json>` | string | No | Custom properties JSON |
| `--segment-id <id...>` | string[] | No | Add to segment(s) |

---

## contacts get

**Argument:** `<id|email>` — Contact UUID or email address (both accepted)

---

## contacts update

**Argument:** `<id|email>` — Contact UUID or email address

| Flag | Type | Description |
|------|------|-------------|
| `--unsubscribed` | boolean | Set unsubscribed |
| `--no-unsubscribed` | boolean | Re-subscribe |
| `--properties <json>` | string | Merge properties (set key to `null` to clear) |

---

## contacts delete

**Argument:** `<id|email>` — Contact UUID or email address

| Flag | Type | Required | Description |
|------|------|----------|-------------|
| `--yes` | boolean | Yes (non-interactive) | Skip confirmation |

**Alias:** `rm`

---

## contacts segments

List segments a contact belongs to.

**Argument:** `<id|email>` — Contact UUID or email

---

## contacts add-segment

**Argument:** `<contactId>` — Contact UUID or email

| Flag | Type | Required | Description |
|------|------|----------|-------------|
| `--segment-id <id>` | string | Yes (non-interactive) | Segment ID to add to |

---

## contacts remove-segment

**Arguments:** `<id|email>` `<segmentId>`

---

## contacts topics

List contact's topic subscriptions.

**Argument:** `<id|email>` — Contact UUID or email

---

## contacts update-topics

**Argument:** `<id|email>` — Contact UUID or email

| Flag | Type | Required | Description |
|------|------|----------|-------------|
| `--topics <json>` | string | Yes (non-interactive) | JSON array: `[{"id":"topic-uuid","subscription":"opt_in"}]` |

Subscription values: `opt_in` | `opt_out`

---

## contacts imports create

Bulk-import contacts from a local CSV file. The file is uploaded as multipart form data (max 100MB). Imports run **asynchronously** — the command returns an import id immediately while the file is processed in the background (poll with `contacts imports get`).

| Flag | Type | Required | Description |
|------|------|----------|-------------|
| `--file <path>` | string | Yes (non-interactive) | Path to the CSV file to import |
| `--column-map <json>` | string | No | JSON object mapping contact fields to CSV column headers: `{"email":"Email","firstName":"First Name","properties":{"plan":{"column":"Plan","type":"string"}}}` |
| `--on-conflict <strategy>` | string | No | How to handle existing contacts: `upsert` (default, updates) or `skip` |
| `--segment-id <id...>` | string[] | No | Add imported contacts to segment(s) — repeatable |
| `--topics <json>` | string | No | JSON array: `[{"id":"topic-uuid","subscription":"opt_in"}]` |

Mappable contact fields: `email`, `firstName`, `lastName`, `unsubscribed`, `properties`.

Without `--column-map`, columns are matched by the lowercase names `email` (required), `first_name`, `last_name` — matching is **case-sensitive**, so a CSV with `Email`/`First Name` headers fails with `create_error` (422 "missing required email column"). Use `--column-map` to import such a file.

---

## contacts imports get

Retrieve a contact import's status and counts.

**Argument:** `[id]` — Contact import ID (interactive picker when omitted)

Status values: `queued` | `in_progress` | `completed` | `failed`

---

## contacts imports list

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--limit <n>` | number | 10 | Max results (1-100) |
| `--after <cursor>` | string | — | Forward pagination |
| `--before <cursor>` | string | — | Backward pagination |
| `--status <status>` | string | — | Filter by status: `queued` \| `in_progress` \| `completed` \| `failed` |

**Alias:** `ls`