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

# CLI Email Templates and Variables

> Personalize emails sent with the AhaSend CLI using template files: global and per-recipient substitutions, if/else conditions, loops, and default values.

The AhaSend CLI uses [MiniJinja templating (Jinja2-compatible syntax)](https://github.com/mitsuhiko/minijinja) for creating personalized emails.

Templates are rendered by the AhaSend API using MiniJinja. Subject lines also support substitutions. Use `default` for missing values and test your rendering with sandbox mode; see [API templates](/docs/send-api/send-email#template-variables).

| Flag | File |
| - | - |
| `--html-template` | HTML content |
| `--text-template` | Plain text content |
| `--amp-template` | AMP HTML content |
| `--global-substitutions` | JSON object shared by recipients |
| `--recipients` | CSV or JSON recipient data |

Before running the examples, [log in with a full API key](/docs/cli/authentication), use your verified sender domain, and replace `YOUR_RESOURCE_ID` with a resource UUID from your test account. Create any named template, recipient, attachment, or JSON files first. Shell examples use Bash; examples that read JSON with `jq` need jq installed. Sends use sandbox mode.

## Template Basics

Use double curly braces for variable substitution:

```html theme={null}
<!-- template.html -->
<h1>Hello {{first_name}}!</h1>
<p>Welcome to {{company_name}}.</p>
<p>Your account type is: {{account_type}}</p>
```

## Substitution Types

### Global Substitutions

Applied to all recipients - use for company-wide data:

```json company-data.json theme={null}
{
  "company_name": "ACME Corporation",
  "support_email": "support@acme.com",
  "year": "2024"
}
```

```bash theme={null}
ahasend messages send --sandbox --subject "Docs test" \
  --from sender@example.com \
  --to recipient@example.com \
  --html-template template.html \
  --global-substitutions company-data.json
```

### Recipient Substitutions

Per-recipient data from CSV/JSON files:

<Tabs>
  <Tab title="CSV Format">
    ```csv theme={null}
    email,first_name,account_type,balance
    john@example.com,John,premium,1234.56
    jane@example.com,Jane,basic,567.89
    ```
  </Tab>

  <Tab title="JSON Format">
    ```json theme={null}
    [
      {
        "email": "john@example.com",
        "substitution_data": {
          "first_name": "John",
          "account_type": "premium",
          "balance": 1234.56
        }
      }
    ]
    ```
  </Tab>
</Tabs>

```bash theme={null}
ahasend messages send --sandbox --subject "Docs test" \
  --from sender@example.com \
  --recipients users.csv \
  --html-template template.html \
  --global-substitutions company-data.json
```

## Basic Examples

### Simple Template

```html theme={null}
<!-- welcome.html -->
<!DOCTYPE html>
<html>
<body>
    <h1>Welcome {{first_name}}!</h1>
    <p>Thank you for joining {{company_name}}.</p>
    <p>Your account type: {{account_type}}</p>
    <p>Questions? Contact {{support_email}}</p>
</body>
</html>
```

### Conditional Content

```html theme={null}
<!-- conditional.html -->
<h1>Hello {{first_name}}!</h1>

{% if account_type == "premium" %}
    <p>Thank you for being a Premium member!</p>
{% else %}
    <p>Consider upgrading to Premium!</p>
{% endif %}
```

### Lists and Loops

```html theme={null}
<!-- order-confirmation.html -->
<h1>Order Confirmation</h1>
<p>Thank you, {{customer_name}}!</p>

<table>
    {% for item in items %}
    <tr>
        <td>{{item.name}}</td>
        <td>{{item.quantity}}</td>
        <td>${{item.price}}</td>
    </tr>
    {% endfor %}
</table>
```

## Testing Templates

Test templates using sandbox mode:

```bash theme={null}
ahasend messages send --subject "Docs test" \
  --from test@example.com \
  --to test@example.com \
  --html-template template.html \
  --global-substitutions test-data.json \
  --sandbox
```

Then check the AhaSend dashboard to see the rendered message.

## Best Practices

1. **Use meaningful variable names**: `{{customer_first_name}}` not `{{fn}}`
2. **Provide default values**: `{{name|default("Friend")}}`
3. **Test with real data**: Use sandbox mode before sending
4. **Keep templates simple**: Complex logic belongs in your application
5. **Global vs recipient data**: Company info in global, personal info per recipient

## Next Steps

* [Learn about batch processing](/docs/cli/batch-processing)
* [Explore MiniJinja documentation](https://github.com/mitsuhiko/minijinja)
* [View CLI examples](/docs/cli/examples)

## 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).
* [Domain setup](/docs/domains), [Sandbox behavior](/docs/send-api/sandbox).


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