Send emails programmatically using AhaSend’s powerful API v2 create-message endpoint. This guide covers everything from basic email sending to advanced features like template variables, bulk operations, and scheduled delivery.
API v2 Features: This guide covers the advanced API v2 create-message endpoint, which provides enhanced features like template substitutions, bulk sending, scheduled delivery, and comprehensive webhook support.

​
Quick Start

Here’s a simple example to send your first email using the API: 
curl --request POST \
  --url https://api.ahasend.com/v2/accounts/{account_id}/messages \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "from": {
      "email": "[email protected]",
      "name": "Your Company"
    },
    "recipients": [
      {
        "email": "[email protected]",
        "name": "John Doe"
      }
    ],
    "subject": "Welcome to our platform!",
    "text_content": "Thanks for signing up. We're excited to have you!"
  }'

​
Authentication

All API requests require authentication using your API v2 key:
Need API Keys? If you haven’t created API v2 credentials yet, check out our API Credentials guide for step-by-step instructions.

​
Basic Examples

{
  "from": {
    "email": "[email protected]",
    "name": "Your Company"
  },
  "recipients": [
    {
      "email": "[email protected]",
      "name": "John Doe"
    }
  ],
  "subject": "Welcome to our platform!",
  "text_content": "Thanks for signing up. We're excited to have you!"
}

​
Advanced Examples

Multiple Recipients: When you specify multiple recipients in the recipients array, AhaSend sends separate individual emails to each recipient. This is not one email with multiple addresses in the To/CC headers, but rather individual personalized emails where each recipient only sees their own email address and can receive personalized template substitutions.
{
  "from": {
    "email": "[email protected]",
    "name": "Your Newsletter"
  },
  "recipients": [
    {
      "email": "[email protected]",
      "name": "Alice Smith"
    },
    {
      "email": "[email protected]",
      "name": "Bob Johnson"
    },
    {
      "email": "[email protected]",
      "name": "Carol Wilson"
    }
  ],
  "subject": "Monthly Newsletter - {{month}}",
  "html_content": "<h1>{{month}} Newsletter</h1><p>Dear {{name}}, here's what's new this month...</p>",
  "text_content": "{{month}} Newsletter - Dear {{name}}, here's what's new this month...",
  "substitutions": {
    "month": "December",
    "name": "Valued Customer"
  }
}

​
Response Handling

The API returns a response with information about each message created:

​
Successful Response (200)

{
  "object": "list",
  "data": [
    {
      "object": "message",
      "id": "3f8e2b1a-7c4d-4e2a-9b1e-2f3a4b5c6d7e",
      "recipient": {
        "email": "[email protected]",
        "name": "John Doe",
        "substitution_data": {
          "first_name": "John",
          "company": "Your Company"
        }
      },
      "status": "queued",
      "error": null,
      "schedule": {
        "first_attempt": "2024-01-15T10:30:00Z",
        "expires": "2024-01-16T10:30:00Z"
      }
    }
  ]
}

​
Response Fields

​
Error Handling

Handle different HTTP status codes appropriately:

​
Validation Requirements

Based on the API documentation, ensure your requests meet these requirements:

​
Best Practices