> ## Documentation Index
> Fetch the complete documentation index at: https://ahasend.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> AhaSend stores all message data in the EU. See /facts.
> The API base URL is https://api.ahasend.com. Send the API key in the Authorization: Bearer header. See /api-reference/authentication.
> Use send.ahasend.com for SMTP in the EU, or send-us.ahasend.com as a US connection point forwarding to the EU. Ports 25, 587 and 2525 use STARTTLS. Port 465 is not supported. See /smtp.
> For send-only integrations, create an API Key v2 under Credentials → Add and scope it to messages:send:{your-domain}. See /send-api/credentials and /api-reference/scopes.

# ahasend contacts: Manage Account Contacts

> Create, read, update, delete, and batch-import AhaSend account contacts with the CLI, including status, unsubscribe choices, and custom attributes.

AhaSend CLI contact commands manage account-global contacts by email address or UUID.

<Note>
  Contacts support is still in development and has not been deployed to the API. These commands exist in the development CLI build `7a47882`, but not in the published v0.2.0 binary. Wait for both API support and a [CLI release](https://github.com/AhaSend/ahasend-cli/releases) containing contacts before using these examples.
</Note>

## Prerequisites

[Authenticate with a full API key](/docs/cli/authentication). Contact tasks need `contacts:read`, `contacts:write`, or `contacts:delete`, according to the action. Attribute keys must already exist in the dashboard. Creating a contact does not subscribe it to a list.

## Create, Read and Update

Choose a fresh test address, then run these commands in order:

```bash theme={null}
ahasend contacts create docs-contact-test@example.com --first-name Pat --last-name Example --status enabled
ahasend contacts list --limit 10
ahasend contacts get docs-contact-test@example.com
ahasend contacts update docs-contact-test@example.com --unsubscribed=true
```

`update` sends only fields you supply. Set an attribute's value to `null` to remove that value; use `--attributes` with a JSON object. Status values are `enabled`, `disabled`, and `blocked`.

## Batch Import

Save this as `contacts.json`. Use fresh test addresses for each run.

```json contacts.json theme={null}
{"data":[{"email":"docs-batch-test@example.com","first_name":"Pat"}]}
```

```bash theme={null}
ahasend contacts batch --file contacts.json --idempotency-key docs-contact-import-UNIQUE_RUN_ID
```

## Delete a Test Contact

The example creates the contact it deletes. Use a fresh address for the fixture.

```bash theme={null}
ahasend contacts create docs-contact-delete-test@example.com --first-name Test
ahasend contacts delete docs-contact-delete-test@example.com --force
```

## Commands and Flags

### `contacts batch`

```text theme={null}
ahasend contacts batch --file <JSON> [flags]
```

| Flag                       | Description and default                          |
| -------------------------- | ------------------------------------------------ |
| `--file string`            | JSON file containing `{"data":[...]}` (required) |
| `--idempotency-key string` | Idempotency key for safe retries                 |

### `contacts create`

```text theme={null}
ahasend contacts create <email> [flags]
```

| Flag                       | Description and default                      |
| -------------------------- | -------------------------------------------- |
| `--attributes string`      | Contact attributes as a JSON object          |
| `--first-name string`      | Contact first name                           |
| `--idempotency-key string` | Idempotency key for safe retries             |
| `--last-name string`       | Contact last name                            |
| `--status string`          | Contact status (enabled, disabled, blocked)  |
| `--status-reason string`   | Reason for the contact status                |
| `--unsubscribed`           | Whether the contact is globally unsubscribed |

### `contacts delete`

```text theme={null}
ahasend contacts delete <id-or-email> [flags]
```

| Flag      | Description and default  |
| --------- | ------------------------ |
| `--force` | Skip confirmation prompt |

### `contacts get`

```text theme={null}
ahasend contacts get <id-or-email> [flags]
```

No command-specific flags. See [global flags](/docs/cli/configuration#global-flags).

### `contacts list`

```text theme={null}
ahasend contacts list [flags]
```

| Flag                  | Description and default                                   |
| --------------------- | --------------------------------------------------------- |
| `--after string`      | Cursor for the next page                                  |
| `--before string`     | Cursor for the previous page                              |
| `--email string`      | Filter by normalized exact email address                  |
| `--from-time string`  | Include contacts created at or after this RFC3339 time    |
| `--limit int32`       | Maximum number of contacts to return (1-100; default 100) |
| `--status string`     | Filter by status (enabled, disabled, blocked)             |
| `--subscribed string` | Filter by subscription state (true, false)                |
| `--to-time string`    | Include contacts created at or before this RFC3339 time   |

### `contacts update`

```text theme={null}
ahasend contacts update <id-or-email> [flags]
```

| Flag                     | Description and default                      |
| ------------------------ | -------------------------------------------- |
| `--attributes string`    | Contact attributes as a JSON object          |
| `--email string`         | New email address                            |
| `--first-name string`    | Contact first name                           |
| `--last-name string`     | Contact last name                            |
| `--status string`        | Contact status (enabled, disabled, blocked)  |
| `--status-reason string` | Reason for the contact status                |
| `--unsubscribed`         | Whether the contact is globally unsubscribed |

## Related Guides

* [Install the CLI](/docs/cli/installation), [CLI authentication](/docs/cli/authentication), [REST sending guide](/docs/send-api/send-email).
* [SMTP settings](/docs/smtp), [Node.js SDK](/docs/guides/nodejs-sdk), [Go SDK](/docs/guides/go-sdk).
* [CLI configuration and output](/docs/cli/configuration), [API authentication](/docs/api-reference/authentication), [Permission scopes](/docs/api-reference/scopes).