> ## 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. 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.

# CLI Quickstart: Send Email from the Terminal

> Send your first email from the command line with the AhaSend CLI: log in with your API key, add and verify a domain, then send test emails in sandbox mode.

This guide helps you send your first email with the AhaSend CLI in a few minutes.

## Prerequisites

Before you begin, make sure you have:

1. [Installed the AhaSend CLI](https://ahasend.com/docs/cli/installation.md)
2. An AhaSend account ([sign up here](https://dash.ahasend.com/user/register))
3. Your API key and Account ID from the [dashboard](https://dash.ahasend.com)
4. A domain whose DNS records you can change. The examples use `example.com`; replace it with your domain.

The examples send with `--sandbox`, so no email is delivered. [Step 4](#step-4-test-with-sandbox-mode) explains sandbox mode.

## Step 1: Authentication

First, authenticate with your AhaSend API credentials:

```bash theme={null}
# Interactive login (recommended)
ahasend auth login
```

On a terminal, the command asks for:

* Your API key, hidden as you type it
* Your Account ID

The CLI checks that the key belongs to the account before it saves them. [Profiles](https://ahasend.com/docs/cli/configuration.md#profiles) says which name the profile gets.

> [!TIP]
>
> Your credentials are stored in `~/.ahasend/config.yaml` for future use.

Alternatively, provide credentials directly:

```bash theme={null}
ahasend auth login --api-key YOUR_API_KEY --account-id YOUR_ACCOUNT_ID
```

Verify your authentication:

```bash theme={null}
ahasend auth status
```

## Step 2: Add a Sending Domain

Before sending emails, you need to add and verify a domain:

```bash theme={null}
# Add your domain
ahasend domains create example.com
```

The command prints the DNS records the domain needs, on stderr, and marks each one as required or optional. Add them to your domain's DNS settings.

After configuring your DNS records, check them:

```bash theme={null}
# Check the DNS records again
ahasend domains check-dns example.com

# Show the domain and its status
ahasend domains get example.com
```

> [!NOTE]
>
> Most records verify within minutes. DNS changes can take up to 48 hours to propagate. Run `ahasend domains check-dns` again until the DNS is valid.

## Step 3: Send Your First Email

### Simple Text Email

```bash theme={null}
ahasend messages send --sandbox \
  --from noreply@example.com \
  --to recipient@example.com \
  --subject "Hello from AhaSend CLI" \
  --text "This is my first email sent using the AhaSend CLI!"
```

### HTML Email

```bash theme={null}
ahasend messages send --sandbox \
  --from noreply@example.com \
  --to recipient@example.com \
  --subject "Welcome to AhaSend" \
  --html "<h1>Welcome!</h1><p>Thank you for using AhaSend.</p>"
```

### Email with Both HTML and Text

```bash theme={null}
ahasend messages send --sandbox \
  --from noreply@example.com \
  --to recipient@example.com \
  --subject "Welcome" \
  --html "<h1>Welcome to AhaSend!</h1><p>We're glad you're here.</p>" \
  --text "Welcome to AhaSend! We're glad you're here."
```

## Step 4: Test with Sandbox Mode

Before sending real emails, test your integration using sandbox mode:

```bash theme={null}
ahasend messages send \
  --from noreply@example.com \
  --to test@example.com \
  --subject "Test Email" \
  --text "This is a test email in sandbox mode" \
  --sandbox
```

> [!NOTE]
>
> Sandbox mode goes through the sending process but delivers nothing. See [sandbox behavior](https://ahasend.com/docs/send-api/sandbox.md).

You can also simulate different outcomes with `--sandbox-result`: `deliver` (the default), `bounce`, `defer`, `fail`, or `suppress`. It needs `--sandbox`.

```bash theme={null}
# Simulate a bounce
ahasend messages send \
  --from noreply@example.com \
  --to test@example.com \
  --subject "Test Bounce" \
  --text "Testing bounce scenario" \
  --sandbox \
  --sandbox-result bounce

# Simulate successful delivery
ahasend messages send \
  --from noreply@example.com \
  --to test@example.com \
  --subject "Test Success" \
  --text "Testing successful delivery" \
  --sandbox \
  --sandbox-result deliver
```

## Step 5: Send Batch Emails

### Prepare Recipients File

Create a CSV file with recipient data (`recipients.csv`). The `email` and `name` columns set the recipient; each other column is a substitution:

```csv theme={null}
email,name,first_name,company
john@example.com,John Doe,John,ACME Corp
jane@example.com,Jane Smith,Jane,Tech Inc
alice@example.com,Alice Johnson,Alice,StartUp Ltd
```

### Create an HTML File

Create the HTML content (`welcome.html`):

```html theme={null}
<!DOCTYPE html>
<html>
<head>
    <title>Welcome {{first_name}}!</title>
</head>
<body>
    <h1>Welcome to {{company}}, {{first_name}}!</h1>
    <p>We're excited to have you on board.</p>
    <p>Best regards,<br>The AhaSend Team</p>
</body>
</html>
```

### Send Batch Emails

```bash theme={null}
ahasend messages send --sandbox \
  --from welcome@example.com \
  --recipients recipients.csv \
  --subject "Welcome to {{company}}" \
  --html-file welcome.html \
  --progress \
  --show-metrics
```

The CLI:

* Sends a personalized email to each recipient
* Shows a progress bar on stderr, on a terminal only
* Prints performance metrics on stderr after the send
* Saves any failed recipients to a file in `~/.ahasend/` and prints its path, so you can pass it back to `--recipients`
* Exits with code 0 only when every recipient was sent; [exit codes](https://ahasend.com/docs/cli/configuration.md#exit-codes) lists the other codes

## Step 6: Monitor Your Emails

### Check Delivery Statistics

```bash theme={null}
# View statistics for the last 7 days
ahasend stats deliverability

# View statistics for a date range
ahasend stats deliverability \
  --from-time 30d \
  --to-time 7d
```

### List Recent Messages

```bash theme={null}
# List recent sent messages
ahasend messages list

# Filter by status: sandbox sends have sandbox statuses
ahasend messages list --status "sandbox delivered"
```

## Common Patterns

### Using Different Output Formats

```bash theme={null}
# Default plain output
ahasend domains list

# JSON format for automation: the API response, unchanged
ahasend domains list --output json

# CSV format for analysis
ahasend stats deliverability --output csv > stats.csv
```

Every failure exits with a nonzero code. [JSON output](https://ahasend.com/docs/cli/configuration.md#json-output) describes what `--output json` prints, errors included, and [stdout and stderr](https://ahasend.com/docs/cli/configuration.md#stdout-and-stderr) says where each part of the output goes.

### Working with Multiple Environments

```bash theme={null}
# Set up different profiles
ahasend auth login --profile production
ahasend auth login --profile staging

# Use specific profile for commands
ahasend messages send --sandbox --profile staging \
  --from test@staging.example.com \
  --to dev@example.com \
  --subject "Staging Test" \
  --text "Testing staging environment"

# Switch default profile
ahasend auth switch production
```

[Profiles](https://ahasend.com/docs/cli/configuration.md#profiles) says which profile is the default; `ahasend auth switch` changes it.

### Adding Attachments

```bash theme={null}
ahasend messages send --sandbox \
  --from noreply@example.com \
  --to customer@example.com \
  --subject "Your Invoice" \
  --text "Please find your invoice attached." \
  --attach invoice.pdf \
  --attach receipt.pdf
```

### Scheduling Emails

`--schedule` takes a relative time, such as `2h` from now, or an RFC 3339 time. It must be in the future and at most 7 days ahead.

```bash theme={null}
# Schedule for 24 hours from now
ahasend messages send --sandbox \
  --from reminder@example.com \
  --to user@example.com \
  --subject "Reminder: Meeting Tomorrow" \
  --text "Don't forget about our meeting at 2 PM." \
  --schedule 24h
```

## What's Next?

Now that you've sent your first emails, explore more features:

> [card] [Authentication](https://ahasend.com/docs/cli/authentication.md)
>
> Learn about profiles and credential management

> [card] [Message Commands](https://ahasend.com/docs/cli/commands/messages.md)
>
> Explore all email sending options

> [card] [Batch Processing](https://ahasend.com/docs/cli/batch-processing.md)
>
> Send high-volume emails efficiently

> [card] [Message Content](https://ahasend.com/docs/cli/templates.md)
>
> Personalize emails with substitutions

## Getting Help

If you need help at any point:

```bash theme={null}
# General help
ahasend --help

# Command-specific help
ahasend messages send --help

# Check current status
ahasend auth status
ahasend ping
```

For additional support:

* [GitHub Issues](https://github.com/AhaSend/ahasend-cli/issues)
* [API Documentation](https://ahasend.com/docs/api-reference.md)
* Email: [support@ahasend.com](mailto:support@ahasend.com)

## Related Guides

* [Install the CLI](https://ahasend.com/docs/cli/installation.md), [CLI authentication](https://ahasend.com/docs/cli/authentication.md), [REST sending guide](https://ahasend.com/docs/send-api/send-email.md).
* [SMTP settings](https://ahasend.com/docs/smtp.md), [Node.js SDK](https://ahasend.com/docs/guides/nodejs-sdk.md), [Go SDK](https://ahasend.com/docs/guides/go-sdk.md).
* [CLI configuration and output](https://ahasend.com/docs/cli/configuration.md), [API authentication](https://ahasend.com/docs/api-reference/authentication.md), [Permission scopes](https://ahasend.com/docs/api-reference/scopes.md).
* [Domain setup](https://ahasend.com/docs/domains.md), [Sandbox behavior](https://ahasend.com/docs/send-api/sandbox.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.