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

# Send Email from the Command Line with Swaks

> Send and test email over AhaSend SMTP from the terminal with Swaks: STARTTLS and auth flags, HTML, attachments, custom headers, sandbox tests and shell scripts.

Send emails through AhaSend's SMTP servers directly from your terminal using Swaks, a powerful command-line tool designed for testing and debugging SMTP servers. Perfect for scripting, automation, and troubleshooting email delivery issues.

> [!NOTE]
>
> **What is Swaks?** Swaks (Swiss Army Knife for SMTP) is a versatile, scriptable tool for testing SMTP servers and sending emails from the command line. It supports TLS encryption, various authentication methods, and is designed as a diagnostic tool rather than for high-volume sending.

## Prerequisites

Before sending, [verify your domain](https://ahasend.com/docs/domains.md) and [create an SMTP credential](https://ahasend.com/docs/smtp/credentials.md). Use a [sandbox credential](https://ahasend.com/docs/send-api/sandbox.md) for these examples so no email is delivered. Keep the username and password in your server's secret store.

Before you begin, ensure you have:

> [accordion] System Requirements
>
> * **Swaks installed** on your system
> * Command line access (Terminal, Command Prompt, etc.)
> * Basic familiarity with command-line tools

## Installation

Install Swaks using your system's package manager:

```bash Ubuntu/Debian theme={null}
sudo apt-get update
sudo apt-get install swaks
```

```bash CentOS/RHEL/Fedora theme={null}
# CentOS/RHEL
sudo dnf install epel-release
sudo dnf install swaks

# Fedora
sudo dnf install swaks
```

```bash macOS (Homebrew) theme={null}
brew install swaks
```

```bash Windows (Chocolatey) theme={null}
wsl --install
# In the Ubuntu WSL shell, follow the Ubuntu/Debian instructions above.
```

## Connection Settings

| Setting | Value |
| - | - |
| Host | `send.ahasend.com` |
| Ports with STARTTLS | 25, 587 and 2525 |
| Port with implicit TLS | 465 (TLS from the first byte, also called SSL/TLS or SMTPS) |
| Encryption | Required on every port: STARTTLS on 25, 587 and 2525, implicit TLS on 465 |
| Authentication | AUTH PLAIN after STARTTLS on 25, 587 and 2525; AUTH PLAIN or AUTH LOGIN on 465 |
| Username and password | Your SMTP credential, not an API key |

All message data is stored in the EU. See [SMTP limits](https://ahasend.com/docs/smtp.md#what-are-the-smtp-limits).

## Basic Email Examples

```bash Plain Text Email theme={null}
swaks \
  --from hello@yourdomain.com \
  --to user@example.com \
  --server send.ahasend.com \
  --port 587 \
  --auth plain \
  --tls \
  --auth-user 'YOUR_SMTP_USERNAME' \
  --auth-password 'YOUR_SMTP_PASSWORD' \
  --header 'Subject: Welcome to our platform!' \
  --body "Thanks for signing up. We're excited to have you!"
```

```bash HTML Email theme={null}
swaks \
  --from hello@yourdomain.com \
  --to user@example.com \
  --server send.ahasend.com \
  --port 587 \
  --auth plain \
  --tls \
  --auth-user 'YOUR_SMTP_USERNAME' \
  --auth-password 'YOUR_SMTP_PASSWORD' \
  --header 'Subject: Welcome to our platform!' \
  --body "<html><body><h1>Welcome!</h1><p>Thanks for signing up. We're <strong>excited</strong> to have you!</p></body></html>" \
  --add-header "Content-Type: text/html"
```

```bash With Attachment theme={null}
swaks \
  --from hello@yourdomain.com \
  --to user@example.com \
  --server send.ahasend.com \
  --port 587 \
  --auth plain \
  --tls \
  --auth-user 'YOUR_SMTP_USERNAME' \
  --auth-password 'YOUR_SMTP_PASSWORD' \
  --header 'Subject: Your Invoice is Ready' \
  --body "Please find your invoice attached to this email." \
  --attach @/path/to/invoice.pdf
```

```bash Port 465 (Implicit TLS) theme={null}
swaks \
  --from hello@yourdomain.com \
  --to user@example.com \
  --server send.ahasend.com \
  --port 465 \
  --auth login \
  --tls-on-connect \
  --auth-user 'YOUR_SMTP_USERNAME' \
  --auth-password 'YOUR_SMTP_PASSWORD' \
  --header 'Subject: Welcome to our platform!' \
  --body "Thanks for signing up. We're excited to have you!"
```

On port 465, use `--tls-on-connect` instead of `--tls`. Port 465 accepts `--auth login` and `--auth plain`.

## Advanced Examples

```bash Multiple Recipients theme={null}
swaks \
  --from hello@yourdomain.com \
  --to user1@example.com,user2@example.com \
  --server send.ahasend.com \
  --port 587 \
  --auth plain \
  --tls \
  --auth-user 'YOUR_SMTP_USERNAME' \
  --auth-password 'YOUR_SMTP_PASSWORD' \
  --header 'Subject: Newsletter Update' \
  --body "This is our latest newsletter update."
```

```bash With CC and BCC theme={null}
swaks \
  --from hello@yourdomain.com \
  --to user@example.com \
  --cc manager@yourdomain.com \
  --bcc analytics@yourdomain.com \
  --server send.ahasend.com \
  --port 587 \
  --auth plain \
  --tls \
  --auth-user 'YOUR_SMTP_USERNAME' \
  --auth-password 'YOUR_SMTP_PASSWORD' \
  --header 'Subject: Project Update' \
  --body "Here's the latest project update."
```

```bash Multiple Attachments theme={null}
swaks \
  --from hello@yourdomain.com \
  --to user@example.com \
  --server send.ahasend.com \
  --port 587 \
  --auth plain \
  --tls \
  --auth-user 'YOUR_SMTP_USERNAME' \
  --auth-password 'YOUR_SMTP_PASSWORD' \
  --header 'Subject: Documents Package' \
  --body "Please find the requested documents attached." \
  --attach @/path/to/document1.pdf \
  --attach @/path/to/document2.xlsx
```

## Using Special Headers

Add AhaSend's special headers to control tracking, retention, and other features:

```bash With Tracking Headers theme={null}
swaks \
  --from hello@yourdomain.com \
  --to user@example.com \
  --server send.ahasend.com \
  --port 587 \
  --auth plain \
  --tls \
  --auth-user 'YOUR_SMTP_USERNAME' \
  --auth-password 'YOUR_SMTP_PASSWORD' \
  --header 'Subject: Newsletter with Tracking' \
  --add-header "ahasend-track-opens: true" \
  --add-header "ahasend-track-clicks: true" \
  --add-header "ahasend-tags: newsletter,cli,swaks" \
  --body "<html><body><h1>Newsletter</h1><p>Check out our <a href='https://yourdomain.com/features'>latest features</a>!</p></body></html>" \
  --add-header "Content-Type: text/html"
```

```bash With Retention Headers theme={null}
swaks \
  --from hello@yourdomain.com \
  --to user@example.com \
  --server send.ahasend.com \
  --port 587 \
  --auth plain \
  --tls \
  --auth-user 'YOUR_SMTP_USERNAME' \
  --auth-password 'YOUR_SMTP_PASSWORD' \
  --header 'Subject: Temporary Notification' \
  --add-header "AhaSend-Metadata-Retention: 7" \
  --add-header "AhaSend-Data-Retention: 1" \
  --body "This is a temporary notification that will be automatically deleted."
```

```bash Complete Example theme={null}
swaks \
  --from hello@yourdomain.com \
  --to user@example.com \
  --server send.ahasend.com \
  --port 587 \
  --auth plain \
  --tls \
  --auth-user 'YOUR_SMTP_USERNAME' \
  --auth-password 'YOUR_SMTP_PASSWORD' \
  --header 'Subject: Product Update with Tracking' \
  --add-header "ahasend-track-opens: true" \
  --add-header "ahasend-track-clicks: true" \
  --add-header "ahasend-tags: product-update,announcement,cli" \
  --add-header "AhaSend-Metadata-Retention: 30" \
  --add-header "AhaSend-Data-Retention: 7" \
  --body "<html><body><h1>Product Updates</h1><p>We've launched <a href='https://yourdomain.com/new-features'>exciting new features</a>!</p></body></html>" \
  --add-header "Content-Type: text/html"
```

## Testing with Sandbox Mode

Use sandbox mode to safely test your email integration:

```bash Sandbox Test theme={null}
swaks \
  --from hello@yourdomain.com \
  --to test@example.com \
  --server send.ahasend.com \
  --port 587 \
  --auth plain \
  --tls \
  --auth-user 'YOUR_SMTP_USERNAME' \
  --auth-password 'YOUR_SMTP_PASSWORD' \
  --header 'Subject: Sandbox Test Email' \
  --add-header "AhaSend-Sandbox: true" \
  --add-header "AhaSend-Sandbox-Result: deliver" \
  --body "This email is sent in sandbox mode for testing."
```

```bash Sandbox Bounce Test theme={null}
swaks \
  --from hello@yourdomain.com \
  --to test@example.com \
  --server send.ahasend.com \
  --port 587 \
  --auth plain \
  --tls \
  --auth-user 'YOUR_SMTP_USERNAME' \
  --auth-password 'YOUR_SMTP_PASSWORD' \
  --header 'Subject: Sandbox Bounce Test' \
  --add-header "AhaSend-Sandbox: true" \
  --add-header "AhaSend-Sandbox-Result: bounce" \
  --body "This email simulates a bounce for webhook testing."
```

```bash Sandbox with Verbose Output theme={null}
swaks \
  --from hello@yourdomain.com \
  --to test@example.com \
  --server send.ahasend.com \
  --port 587 \
  --auth plain \
  --tls \
  --auth-user 'YOUR_SMTP_USERNAME' \
  --auth-password 'YOUR_SMTP_PASSWORD' \
  --header 'Subject: Verbose Sandbox Test' \
  --add-header "AhaSend-Sandbox: true" \
  --add-header "AhaSend-Sandbox-Result: deliver" \
  --body "Testing with verbose output enabled." \
  --show-data \
  --show-raw-text
```

> [!NOTE]
>
> **Sandbox Benefits:** Emails sent in sandbox mode are free, trigger webhooks normally, and never actually deliver to recipients - perfect for development and testing.

## Scripting and Automation

### Shell Script Example

```bash Email Script Example theme={null}
#!/bin/bash

# Configuration
SMTP_SERVER="send.ahasend.com"
SMTP_PORT="587"
SMTP_USERNAME="YOUR_SMTP_USERNAME"
SMTP_PASSWORD="YOUR_SMTP_PASSWORD"
FROM_EMAIL="hello@yourdomain.com"

# Function to send email
send_email() {
    local to_email="$1"
    local subject="$2"
    local body="$3"

    swaks \
        --from "$FROM_EMAIL" \
        --to "$to_email" \
        --server "$SMTP_SERVER" \
        --port "$SMTP_PORT" \
        --auth plain \
        --tls \
        --auth-user "$SMTP_USERNAME" \
        --auth-password "$SMTP_PASSWORD" \
        --header "Subject: $subject" \
        --body "$body"
}

# Send notification email
send_email "admin@yourdomain.com" "System Alert" "The backup process has completed successfully."

# Send welcome email
send_email "newuser@example.com" "Welcome!" "Thanks for joining our platform."
```

### Environment Variables

For security, use environment variables for credentials:

```bash Environment Setup theme={null}
# Set environment variables
export AHASEND_SMTP_USERNAME="your_smtp_username"
export AHASEND_SMTP_PASSWORD="your_smtp_password"
export AHASEND_FROM_EMAIL="hello@yourdomain.com"

# Use in swaks command
swaks \
  --from "$AHASEND_FROM_EMAIL" \
  --to user@example.com \
  --server send.ahasend.com \
  --port 587 \
  --auth plain \
  --tls \
  --auth-user "$AHASEND_SMTP_USERNAME" \
  --auth-password "$AHASEND_SMTP_PASSWORD" \
  --header 'Subject: Secure Email' \
  --body "This email uses environment variables for credentials."
```

## Send with the AhaSend CLI

The [AhaSend CLI](https://ahasend.com/docs/cli/installation.md) can also send a test email over SMTP, with [`ahasend smtp send`](https://ahasend.com/docs/cli/commands/smtp#send-via-smtp). It connects to `--server`, which defaults to `send.ahasend.com:587`, and starts TLS: at once on port 465, otherwise with STARTTLS when the server offers it. AhaSend's own servers do not offer implicit TLS on port 465, so use port 587, 25 or 2525 with them. It refuses to send the username, the password or the message to a server that offers no STARTTLS, except on `localhost`, `127.0.0.1` or `::1`.

`--password-stdin` reads the password from the first line of stdin, so it stays out of the process list and your shell history:

```bash Sandbox Send with the AhaSend CLI theme={null}
printf '%s\n' "$AHASEND_SMTP_PASSWORD" | ahasend smtp send --sandbox \
  --username "$AHASEND_SMTP_USERNAME" \
  --password-stdin \
  --from "$AHASEND_FROM_EMAIL" \
  --to test@example.com \
  --subject "Sandbox Test Email" \
  --text "This email is sent in sandbox mode for testing."
```

`--test` connects, starts TLS when the server offers it, logs in when you give the username and the password, and quits without sending a message:

```bash Connection Test with the AhaSend CLI theme={null}
printf '%s\n' "$AHASEND_SMTP_PASSWORD" | ahasend smtp send --test \
  --server send.ahasend.com:587 \
  --username "$AHASEND_SMTP_USERNAME" \
  --password-stdin
```

The CLI flags `--sandbox`, `--sandbox-result`, `--tag`, `--track-opens` and `--track-clicks` set the matching AhaSend headers. See [`ahasend smtp`](https://ahasend.com/docs/cli/commands/smtp) for every flag and exit code.

## Resources

> [card] [Swaks Documentation](http://www.jetmore.org/john/code/swaks/)
>
> Official Swaks documentation and manual

> [card] [SMTP Testing Guide](https://ahasend.com/docs/send-api/sandbox.md)
>
> Complete guide to testing email delivery

> [card] [AhaSend SMTP Settings](https://ahasend.com/docs/smtp.md)
>
> SMTP server configuration and credentials

> [card] [AhaSend Support](mailto:support@ahasend.com)
>
> Get help from our engineering team

> [!TIP]
>
> **Pro Tip:** Start with sandbox mode and basic commands before building complex automation. Use environment variables for credentials and always test scripts thoroughly before production use.

## Related Guides

* Before sending: [verify your domain](https://ahasend.com/docs/domains.md) and [create an SMTP credential](https://ahasend.com/docs/smtp/credentials.md).
* Connection and message rules: [SMTP hosts, ports and limits](https://ahasend.com/docs/smtp.md), [special headers](https://ahasend.com/docs/smtp/special-headers.md), [sandbox mode](https://ahasend.com/docs/send-api/sandbox.md), [retention](https://ahasend.com/docs/retention.md) and [plan features](https://ahasend.com/docs/facts.md#plans-and-features).
* Other ways to send: [REST API](https://ahasend.com/docs/send-api/send-email.md), [AhaSend CLI](https://ahasend.com/docs/cli/quickstart.md), [Node.js SDK](https://ahasend.com/docs/guides/nodejs-sdk.md) and [Go SDK](https://ahasend.com/docs/guides/go-sdk.md).
* Delivery events: [webhook setup](https://ahasend.com/docs/integrations/webhooks.md) and [local webhook testing](https://ahasend.com/docs/cli/webhook-testing.md).


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