API v1 vs 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.

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
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)
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 — global and per-recipient
AMP email content for interactive emails
CC/BCC support via the conversation message endpoint
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 for least-privilege security
Full resource management — domains, webhooks, routes, suppressions, and more
Delivery analytics and reporting

Key Differences in Detail

Authentication

API v1
API v2

Uses an X-Api-Key header:

curl -X POST https://api.ahasend.com/v1/email/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Uses a Bearer token in the Authorization header:

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

API v1
API v2

Email content is nested under a content object. Fields use text_body and html_body:

{
  "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": "<p>HTML content</p>",
    "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" }
  }
}

All fields are at the top level. Fields use text_content and html_content. Recipients can have individual substitution data:

{
  "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": "<p>Hello {{first_name}}!</p>",
  "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": "2026-03-11T10:00:00Z",
    "expires": "2026-03-12T10:00:00Z"
  }
}

Response Format

API v1
API v2

Returns 201 Created with aggregate counts:

{
  "success_count": 1,
  "fail_count": 0,
  "failed_recipients": [],
  "errors": []
}

Errors return a status string:

{ "status": "domain is not yours" }

Returns 202 Accepted with per-recipient status:

{
  "object": "list",
  "data": [
    {
      "object": "message",
      "id": "<uuid@example.com>",
      "recipient": {
        "email": "user@example.com",
        "name": "John Doe"
      },
      "status": "queued",
      "error": null
    }
  ]
}

Errors return a structured message:

{ "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:

Messages

Send, retrieve, list, and cancel messages

Domains

Add, verify, and manage sending domains

Webhooks

Create and manage webhook endpoints for delivery events

Routes

Configure inbound email routing rules

Suppressions

Manage bounce and complaint suppression lists

Reports

Access deliverability, bounce, and delivery time analytics

SMTP Credentials

Create and manage SMTP credentials

API Keys

Create and manage API keys programmatically

Migrating from v1 to v2

Create an API v2 key

Go to Credentials and create a new credential with type “API Key v2”.

Update authentication

Replace the X-Api-Key header with Authorization: Bearer YOUR_V2_KEY.

Update the endpoint

Change the URL from /v1/email/send to /v2/accounts/{account_id}/messages.

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

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

API v2 Credentials

Create and manage API v2 keys

Send Emails with v2

Full guide with examples

API v1 Reference

Legacy API v1 endpoint reference

API v2 Reference

Complete API v2 documentation

Overview

API reference

Webhooks

Message Routing

API v1 (legacy)

Quick Comparison

When to Use API v1

When to Use API v2

Key Differences in Detail

Authentication

Request Structure

Response Format

Beyond Sending: Managing Resources with API v2

Messages

Domains

Webhooks

Routes

Suppressions

Reports

SMTP Credentials

API Keys

Migrating from v1 to v2

Next Steps

API v2 Credentials

Send Emails with v2

API v1 Reference

API v2 Reference

Overview

API reference

Webhooks

Message Routing

API v1 (legacy)

​Quick Comparison

​When to Use API v1

​When to Use API v2

​Key Differences in Detail

​Authentication

​Request Structure

​Response Format

​Beyond Sending: Managing Resources with API v2

Messages

Domains

Webhooks

Routes

Suppressions

Reports

SMTP Credentials

API Keys

​Migrating from v1 to v2

​Next Steps

API v2 Credentials

Send Emails with v2

API v1 Reference

API v2 Reference

Quick Comparison

When to Use API v1

When to Use API v2

Key Differences in Detail

Authentication

Request Structure

Response Format

Beyond Sending: Managing Resources with API v2

Migrating from v1 to v2

Next Steps