CLI Quickstart: Send Email from the Terminal

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

Prerequisites

Before you begin, make sure you have:

Installed the AhaSend CLI
An AhaSend account (sign up here)
Your API key and Account ID from the dashboard
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 explains sandbox mode.

Step 1: Authentication

First, authenticate with your AhaSend API credentials:

# 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 says which name the profile gets.

Your credentials are stored in ~/.ahasend/config.yaml for future use.

Alternatively, provide credentials directly:

ahasend auth login --api-key YOUR_API_KEY --account-id YOUR_ACCOUNT_ID

Verify your authentication:

ahasend auth status

Step 2: Add a Sending Domain

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

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

# Check the DNS records again
ahasend domains check-dns example.com

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

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

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

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

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:

ahasend messages send \
  --from noreply@example.com \
  --to test@example.com \
  --subject "Test Email" \
  --text "This is a test email in sandbox mode" \
  --sandbox

Sandbox mode goes through the sending process but delivers nothing. See sandbox behavior.

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

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

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):

<!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

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 lists the other codes

Step 6: Monitor Your Emails

Check Delivery Statistics

# 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

# 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

# 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 describes what --output json prints, errors included, and stdout and stderr says where each part of the output goes.

Working with Multiple Environments

# 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 says which profile is the default; ahasend auth switch changes it.

Adding Attachments

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.

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

Authentication

Learn about profiles and credential management

Message Commands

Explore all email sending options

Batch Processing

Send high-volume emails efficiently

Message Content

Personalize emails with substitutions

Getting Help

If you need help at any point:

# General help
ahasend --help

# Command-specific help
ahasend messages send --help

# Check current status
ahasend auth status
ahasend ping

For additional support:

Getting Started

Commands

Features

CLI Quickstart: Send Email from the Terminal

Prerequisites

Step 1: Authentication

Step 2: Add a Sending Domain

Step 3: Send Your First Email

Simple Text Email

HTML Email

Email with Both HTML and Text

Step 4: Test with Sandbox Mode

Step 5: Send Batch Emails

Prepare Recipients File

Create an HTML File

Send Batch Emails

Step 6: Monitor Your Emails

Check Delivery Statistics

List Recent Messages

Common Patterns

Using Different Output Formats

Working with Multiple Environments

Adding Attachments

Scheduling Emails

What’s Next?

Authentication

Message Commands

Batch Processing

Message Content

Getting Help

​Prerequisites

​Step 1: Authentication

​Step 2: Add a Sending Domain

​Step 3: Send Your First Email

​Simple Text Email

​HTML Email

​Email with Both HTML and Text

​Step 4: Test with Sandbox Mode

​Step 5: Send Batch Emails

​Prepare Recipients File

​Create an HTML File

​Send Batch Emails

​Step 6: Monitor Your Emails

​Check Delivery Statistics

​List Recent Messages

​Common Patterns

​Using Different Output Formats

​Working with Multiple Environments

​Adding Attachments

​Scheduling Emails

​What’s Next?

Authentication

Message Commands

Batch Processing

Message Content

​Getting Help

​Related Guides

Prerequisites

Step 1: Authentication

Step 2: Add a Sending Domain

Step 3: Send Your First Email

Simple Text Email

HTML Email

Email with Both HTML and Text

Step 4: Test with Sandbox Mode

Step 5: Send Batch Emails

Prepare Recipients File

Create an HTML File

Send Batch Emails

Step 6: Monitor Your Emails

Check Delivery Statistics

List Recent Messages

Common Patterns

Using Different Output Formats

Working with Multiple Environments

Adding Attachments

Scheduling Emails

What’s Next?

Getting Help

Related Guides