> ## 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. # API v1 vs v2: Differences and Migration > Compare AhaSend API v1 and v2 side by side (auth headers, request fields, responses, features) and follow the step-by-step migration from /v1/email/send to v2. AhaSend offers two API versions for sending emails. This page helps you understand the differences so you can choose the right one when creating credentials. > [!NOTE] > > **API v1 is in maintenance mode.** It will continue to work, but all new features and improvements go to API v2. We recommend API v2 for new integrations. ## Quick Comparison | | API v1 | API v2 | | - | - | - | | **Status** | Maintenance mode | Actively developed | | **Endpoints** | Single (`POST /v1/email/send`) | Full REST API with [multiple resources](#beyond-sending-managing-resources-with-api-v2) | | **Authentication** | `X-Api-Key` header | `Authorization: Bearer` header | | **Send emails** | Up to 100 recipients per request | Up to 100 recipients per request | | **Attachments** | Yes | Yes | | **Custom headers** | Yes | Yes | | **Reply-to** | Yes | Yes | | **Template substitutions** | No | Yes (global and per-recipient) | | **AMP email content** | No | Yes | | **CC/BCC** | No | Yes (via [conversation endpoint](https://ahasend.com/docs/api-reference/messages/create-conversation.md)) | | **Message tags** | No | Yes | | **Scheduled delivery** | No | Yes | | **Message cancellation** | No | Yes | | **Per-message tracking controls** | No | Yes (override account defaults) | | **Retention controls** | No | Yes | | **Sandbox mode** | No | Yes | | **Idempotency** | No | Yes | | **Granular API key scopes** | No | Yes | | **Resource management** | No | Yes (domains, webhooks, routes, etc.) | | **Reporting & analytics** | No | Yes | ## When to Use API v1 API v1 is a single endpoint for sending emails. Choose it if you are maintaining an existing integration that already uses v1. For new integrations, use API v2. ## When to Use API v2 API v2 is the recommended choice for all new integrations. It includes everything v1 can do, plus: * **Template substitutions** with [MiniJinja](https://github.com/mitsuhiko/minijinja) — global and per-recipient * **AMP email content** for interactive emails * **CC/BCC support** via the [conversation message endpoint](https://ahasend.com/docs/api-reference/messages/create-conversation.md) * **Message tags** for categorization * **Scheduled delivery** and **message cancellation** * **Per-message tracking controls** to override account-level open/click tracking settings * **Retention controls** for metadata and content * **Sandbox mode** for testing without delivery * **Idempotency** for safe retries * **Granular API key [scopes](https://ahasend.com/docs/api-reference/scopes.md)** for least-privilege security * **Full resource management** — domains, webhooks, routes, suppressions, and more * **Delivery analytics and reporting** ## Key Differences in Detail ### Authentication > [tab] API v1 > > Uses an `X-Api-Key` header: > > ```bash theme={null} > curl -X POST https://api.ahasend.com/v1/email/send \ > -H "X-Api-Key: YOUR_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ ... }' > ``` > [tab] API v2 > > Uses a Bearer token in the `Authorization` header: > > ```bash theme={null} > curl -X POST https://api.ahasend.com/v2/accounts/{account_id}/messages \ > -H "Authorization: Bearer YOUR_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ ... }' > ``` ### Request Structure > [tab] API v1 > > Email content is nested under a `content` object. Fields use `text_body` and `html_body`: > > ```json theme={null} > { > "from": { "email": "hello@yourdomain.com", "name": "Your Company" }, > "recipients": [ > { "email": "user@example.com", "name": "John Doe" } > ], > "content": { > "subject": "Hello!", > "text_body": "Plain text content", > "html_body": "

HTML content

", > "attachments": [ > { > "data": "base64-encoded-data", > "base64": true, > "file_name": "document.pdf", > "content_type": "application/pdf" > } > ], > "reply_to": { "email": "reply@yourdomain.com" }, > "headers": { "X-Custom-Header": "value" } > } > } > ``` > [tab] API v2 > > All fields are at the top level. Fields use `text_content` and `html_content`. Recipients can have individual substitution data: > > ```json theme={null} > { > "from": { "email": "hello@yourdomain.com", "name": "Your Company" }, > "recipients": [ > { > "email": "user@example.com", > "name": "John Doe", > "substitutions": { "first_name": "John" } > } > ], > "subject": "Hello {{first_name}}!", > "text_content": "Hello {{first_name}}!", > "html_content": "

Hello {{first_name}}!

", > "substitutions": { "first_name": "there" }, > "attachments": [ > { > "data": "base64-encoded-data", > "base64": true, > "file_name": "document.pdf", > "content_type": "application/pdf" > } > ], > "tags": ["welcome"], > "tracking": { "open": true, "click": true }, > "retention": { "metadata": 30, "data": 7 }, > "schedule": { > "first_attempt": "", > "expires": "" > } > } > ``` ### Response Format > [tab] API v1 > > Returns `201 Created` with aggregate counts: > > ```json theme={null} > { > "success_count": 1, > "fail_count": 0, > "failed_recipients": [], > "errors": [] > } > ``` > > Errors return a `status` string: > > ```json theme={null} > { "status": "domain is not yours" } > ``` > [tab] API v2 > > Returns `202 Accepted` with per-recipient status: > > ```json theme={null} > { > "object": "list", > "data": [ > { > "object": "message", > "id": "", > "recipient": { > "email": "user@example.com", > "name": "John Doe" > }, > "status": "queued", > "error": null > } > ] > } > ``` > > Errors return a structured `message`: > > ```json theme={null} > { "message": "Either text_content or html_content is required" } > ``` ### Beyond Sending: Managing Resources with API v2 API v1 only sends emails. API v2 provides a complete management API: > [card] [Messages](https://ahasend.com/docs/api-reference/messages/create-message.md) > > Send, retrieve, list, and cancel messages > [card] [Domains](https://ahasend.com/docs/api-reference/domains/create-domain.md) > > Add, verify, and manage sending domains > [card] [Webhooks](https://ahasend.com/docs/api-reference/webhooks/create-webhook.md) > > Create and manage webhook endpoints for delivery events > [card] [Routes](https://ahasend.com/docs/api-reference/routes/create-route.md) > > Configure inbound email routing rules > [card] [Suppressions](https://ahasend.com/docs/api-reference/suppressions/create-suppression.md) > > Manage bounce and complaint suppression lists > [card] [Reports](https://ahasend.com/docs/api-reference/reports/get-deliverability-report.md) > > Access deliverability, bounce, and delivery time analytics > [card] [SMTP Credentials](https://ahasend.com/docs/api-reference/smtp-credentials/create-smtp-credential.md) > > Create and manage SMTP credentials > [card] [API Keys](https://ahasend.com/docs/api-reference/api-keys/create-api-key.md) > > Create and manage API keys programmatically ## Migrating from v1 to v2 **1. Create an API v2 key** Go to [Credentials](https://dash.ahasend.com/account/-/transactional/credentials) and create a new credential with type "API Key v2". **2. Update authentication** Replace the `X-Api-Key` header with `Authorization: Bearer YOUR_V2_KEY`. **3. Update the endpoint** Change the URL from `/v1/email/send` to `/v2/accounts/{account_id}/messages`. **4. Update the request body** * Move `content.subject` to top-level `subject` * Rename `content.text_body` to `text_content` * Rename `content.html_body` to `html_content` * Move `content.attachments` to top-level `attachments` * Move `content.headers` to top-level `headers` * Move `content.reply_to` to top-level `reply_to` **5. Update response handling** * v1 returns `201` with `success_count`/`fail_count` — v2 returns `202` with a `data` array of per-recipient message objects * v1 error responses use a `status` field — v2 uses a `message` field ## Next Steps > [card] [API v2 Credentials](https://ahasend.com/docs/send-api/credentials.md) > > Create and manage API v2 keys > [card] [Send Emails with v2](https://ahasend.com/docs/send-api/send-email.md) > > Full guide with examples > [card] [API v1 Reference](https://ahasend.com/docs/api-reference/v1.md) > > Legacy API v1 endpoint reference > [card] [API v2 Reference](https://ahasend.com/docs/api-reference.md) > > Complete API v2 documentation For the v2 URL, copy the account UUID from **Account Settings → API Keys** or use `ahasend auth status`. See [account ID and authentication](https://ahasend.com/docs/api-reference/authentication.md). Scheduled first attempts must be in the future and within 7 days; expiry must be in the future and within 8 days. ## Related Guides * [API authentication](https://ahasend.com/docs/api-reference/authentication.md), [Permission scopes](https://ahasend.com/docs/api-reference/scopes.md), [Send-only API keys](https://ahasend.com/docs/send-api/credentials.md). * [REST sending guide](https://ahasend.com/docs/send-api/send-email.md), [SMTP settings](https://ahasend.com/docs/smtp.md), [CLI quickstart](https://ahasend.com/docs/cli/quickstart.md). * [Node.js SDK](https://ahasend.com/docs/guides/nodejs-sdk.md), [Go SDK](https://ahasend.com/docs/guides/go-sdk.md), [Idempotency rules](https://ahasend.com/docs/api-reference/idempotency.md). * [API errors](https://ahasend.com/docs/api-reference/errors.md), [API rate limits](https://ahasend.com/docs/api-reference/rate-limits.md), [Retention rules](https://ahasend.com/docs/retention.md). * [Tracking setup](https://ahasend.com/docs/tracking/open-tracking.md), [Sandbox behavior](https://ahasend.com/docs/send-api/sandbox.md), [Suppression durations](https://ahasend.com/docs/bounces.md#suppression-duration). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.