> ## 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.
# Create Message
> Creates and sends a message to one or more recipients. This API cannot be used if you want to send a conversational/P2P message and set CC or BCC. Use [Create Conversation Message](https://ahasend.com/docs/api-reference/messages/create-conversation) instead.
**Validation Requirements:**
- Either `text_content` or `html_content` is required
- `from.email` must be from a domain you own with valid DNS records
- `retention.metadata` must be between 1 and 30 days
- `retention.data` must be between 0 and 30 days
- If `reply_to` is provided, do not include `reply-to` in headers
- `message-id` header will be ignored and automatically generated
- Schedule times must be in RFC3339 format
- `schedule.first_attempt` must be in the future and within 7 days of the request
- `schedule.expires` must be in the future and within 8 days of the request
## OpenAPI
````yaml /openapi.yaml POST /v2/accounts/{account_id}/messages
openapi: 3.1.0
info:
title: AhaSend API v2
description: >
The AhaSend API v2 allows you to send transactional emails, manage domains,
webhooks, routes, API keys, and view statistics.
## Authentication
All API requests must be authenticated using a Bearer token in the
Authorization header:
```
Authorization: Bearer aha-sk-64-CHARACTER-RANDOM-STRING
```
## Scopes
API keys have specific scopes that control access to different resources and
actions:
### Message Scopes
- `messages:send:all` - Send messages from any domain in the account
- `messages:send:{domain}` - Send messages from a specific domain
- `messages:cancel:all` - Cancel messages from any domain
- `messages:cancel:{domain}` - Cancel messages from a specific domain
- `messages:read:all` - Read messages from any domain
- `messages:read:{domain}` - Read messages from a specific domain
### Domain Scopes
- `domains:read` - Read all domains
- `domains:write` - Create and update domains
- `domains:delete:all` - Delete any domain
- `domains:delete:{domain}` - Delete a specific domain
### Account Scopes
- `accounts:read` - Read account information
- `accounts:write` - Update account settings
- `accounts:billing` - Access billing information
- `accounts:members:read` - Read account members
- `accounts:members:add` - Add account members
- `accounts:members:update` - Update account members
- `accounts:members:remove` - Remove account members
### Webhook Scopes
- `webhooks:read:all` - Read all webhooks
- `webhooks:read:{domain}` - Read webhooks for a specific domain
- `webhooks:write:all` - Create and update webhooks
- `webhooks:write:{domain}` - Create and update webhooks for a specific
domain
- `webhooks:delete:all` - Delete any webhook
- `webhooks:delete:{domain}` - Delete webhooks for a specific domain
### Route Scopes
- `routes:read:all` - Read all routes
- `routes:read:{domain}` - Read routes for a specific domain
- `routes:write:all` - Create and update routes
- `routes:write:{domain}` - Create and update routes for a specific domain
- `routes:delete:all` - Delete any route
- `routes:delete:{domain}` - Delete routes for a specific domain
### Suppression Scopes
- `suppressions:read` - Read suppressions
- `suppressions:write` - Create suppressions
- `suppressions:delete` - Delete suppressions
- `suppressions:wipe` - Delete all suppressions (dangerous)
### SMTP Credentials Scopes
- `smtp-credentials:read:all` - Read all SMTP credentials
- `smtp-credentials:read:{domain}` - Read SMTP credentials for a specific
domain
- `smtp-credentials:write:all` - Create SMTP credentials
- `smtp-credentials:write:{domain}` - Create SMTP credentials for a specific
domain
- `smtp-credentials:delete:all` - Delete any SMTP credentials
- `smtp-credentials:delete:{domain}` - Delete SMTP credentials for a
specific domain
### Statistics Scopes
- `statistics-transactional:read:all` - Read all transactional statistics
- `statistics-transactional:read:{domain}` - Read transactional statistics
for a specific domain
### API Key Scopes
- `api-keys:read` - Read API keys
- `api-keys:write` - Create and update API keys
- `api-keys:delete` - Delete API keys
## Rate Limiting
- General API endpoints: 100 requests per second, 200 burst
- Statistics endpoints: 1 request per second, 1 burst
## Pagination
List endpoints use cursor-based pagination with the following parameters:
- `limit`: Maximum number of items to return (default: 100, max: 100)
- `cursor`: Pagination cursor for the next page
## Time Formats
All timestamps must be in RFC3339 format, e.g., `2023-12-25T10:30:00Z`
## Idempotency
POST requests support idempotency through the optional `Idempotency-Key`
header. When provided:
- The same request can be safely retried multiple times
- Duplicate requests return the same response with `Idempotent-Replayed:
true`
- In-progress requests return HTTP 409 with `Idempotent-Replayed: false`
- Failed requests return HTTP 412 with `Idempotent-Replayed: false`
- Reusing a key with a different request payload returns HTTP 422
- Idempotency keys expire after 24 hours
version: 2.0.0
contact:
email: support@ahasend.com
license:
name: MIT
identifier: MIT
servers:
- url: https://api.ahasend.com
description: Production server
security:
- BearerAuth: []
tags:
- name: Utility
description: Utility endpoints for health checks and diagnostics
- name: API Keys
description: Manage API keys for authentication and access control
- name: Domains
description: Manage sending domains
- name: Messages
description: Send and manage transactional messages
- name: Accounts
description: Manage account settings and members
- name: Suppressions
description: Manage email suppressions
- name: Routes
description: Manage inbound email routing
- name: Webhooks
description: Manage webhook notifications
- name: SMTP Credentials
description: Manage SMTP authentication credentials
- name: Statistics
description: Access transactional email statistics
- name: Message Events
description: Webhooks for outbound message delivery events
- name: Suppression Events
description: Webhooks for suppression list changes
- name: Domain Events
description: Webhooks for domain configuration issues
- name: Route Events
description: Webhooks for inbound email routing
paths:
/v2/accounts/{account_id}/messages:
post:
tags:
- Messages
summary: Create Message
description: >
Creates and sends a message to one or more recipients. This API cannot
be used if you want to send a conversational/P2P message and set CC or
BCC. Use [Create Conversation
Message](https://ahasend.com/docs/api-reference/messages/create-conversation)
instead.
**Validation Requirements:**
- Either `text_content` or `html_content` is required
- `from.email` must be from a domain you own with valid DNS records
- `retention.metadata` must be between 1 and 30 days
- `retention.data` must be between 0 and 30 days
- If `reply_to` is provided, do not include `reply-to` in headers
- `message-id` header will be ignored and automatically generated
- Schedule times must be in RFC3339 format
- `schedule.first_attempt` must be in the future and within 7 days of
the request
- `schedule.expires` must be in the future and within 8 days of the
request
operationId: createMessage
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMessageRequest'
responses:
'202':
description: Message created successfully
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMessageResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'412':
$ref: '#/components/responses/IdempotencyPreconditionFailed'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- BearerAuth:
- messages:send:all
- messages:send:{domain}
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/common"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
// Create API client with authentication
client := api.NewAPIClient(
api.WithAPIKey("aha-sk-your-64-character-key"),
)
accountID := uuid.New()
// Create context for the API call
ctx := context.Background()
response, httpResp, err := client.MessagesAPI.CreateMessage(
ctx,
accountID,
requests.CreateMessageRequest{
From: common.Address{
Email: "info@example.com",
Name: ahasend.String("Example Corp."),
},
Recipients: []common.Recipient{
{
Email: "john@example.com",
Name: ahasend.String("John Smith"),
},
},
Subject: "Hello",
TextContent: ahasend.String("Hello world!"),
Sandbox: ahasend.Bool(true),
},
)
if err != nil {
log.Fatalf("Error sending message: %v", err)
}
// Check response
if httpResp.StatusCode == 202 {
fmt.Printf("✅ Send successful! Status: %d\n", httpResp.StatusCode)
if response != nil {
fmt.Printf("Message ID: %s\n", *response.Data[0].ID)
}
} else {
fmt.Printf("❌ Unexpected status code: %d\n", httpResp.StatusCode)
}
}
components:
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: >
Optional idempotency key for safe request retries. Must be a unique
string for each logical request.
Requests with the same key will return the same response. Keys expire
after 24 hours.
schema:
type: string
maxLength: 255
example: user-12345-create-domain-20240101
schemas:
CreateMessageRequest:
type: object
required:
- from
- recipients
- subject
properties:
from:
$ref: '#/components/schemas/Address'
recipients:
type: array
items:
$ref: '#/components/schemas/Recipient'
minItems: 1
maxItems: 100
description: >-
This does not set the To header to multiple addresses, it sends a
separate message for each recipient
reply_to:
$ref: '#/components/schemas/Address'
description: >-
If provided, the reply-to header in headers array must not be
provided
subject:
type: string
description: Email subject line
text_content:
type: string
description: Plain text content. Required if html_content is empty
html_content:
type: string
description: HTML content. Required if text_content is empty
amp_content:
type: string
description: AMP HTML content
attachments:
type: array
items:
$ref: '#/components/schemas/Attachment'
description: File attachments
headers:
type: object
additionalProperties:
type: string
description: >-
Custom email headers. reply-to header cannot be provided if reply_to
is provided, message-id will be ignored and automatically generated
substitutions:
type: object
additionalProperties: true
description: Global substitutions, recipient substitutions override global
tags:
type: array
items:
type: string
description: Tags for categorizing messages
sandbox:
type: boolean
description: If true, the message will be sent to the sandbox environment
default: false
sandbox_result:
type: string
enum:
- deliver
- bounce
- defer
- fail
- suppress
description: The result of the sandbox send
tracking:
$ref: '#/components/schemas/Tracking'
description: >-
Tracking settings for the message, overrides default account
settings
retention:
$ref: '#/components/schemas/Retention'
description: >-
Retention settings for the message, overrides default account
settings
schedule:
$ref: '#/components/schemas/MessageSchedule'
description: Schedule for message delivery
example:
from:
email: noreply@example.com
name: Example Corp
recipients:
- email: user@example.com
name: John Doe
subject: Welcome to Example Corp
html_content: Welcome {{first_name}}!
text_content: Welcome {{first_name}}!
substitutions:
first_name: John
CreateMessageResponse:
type: object
required:
- object
- data
properties:
object:
type: string
enum:
- list
description: Object type identifier
data:
type: array
items:
$ref: '#/components/schemas/CreateSingleMessageResponse'
description: List of messages and their statuses
ErrorResponse:
type: object
required:
- message
properties:
message:
type: string
description: Error description
example:
message: Error message
Address:
type: object
required:
- email
properties:
email:
type: string
format: email
description: >-
Valid email address from a domain defined in your account with valid
DNS records
name:
type: string
description: Display name for the sender
example:
email: noreply@example.com
name: Example Corp
Recipient:
type: object
required:
- email
properties:
email:
type: string
format: email
description: Recipient email address
name:
type: string
description: Display name for the recipient
substitutions:
type: object
additionalProperties: true
description: >-
Substitution data for the recipient. Used with jinja2 templating
language for dynamic content
example:
email: user@example.com
name: John Doe
substitutions:
first_name: John
order_id: '12345'
Attachment:
type: object
required:
- data
- content_type
- file_name
properties:
base64:
type: boolean
description: >-
If true, data must be encoded using base64. Otherwise, data will be
interpreted as UTF-8
default: false
data:
type: string
description: >-
Either plaintext or base64 encoded attachment data (depending on
base64 field)
content_type:
type: string
description: The MIME type of the attachment
content_disposition:
type: string
description: The disposition of the attachment
content_id:
type: string
description: The Content-ID of the attachment for inline images
file_name:
type: string
description: The filename of the attachment
example:
base64: true
data: >-
iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==
content_type: image/png
file_name: pixel.png
Tracking:
type: object
nullable: true
properties:
open:
type: boolean
nullable: true
description: Whether to track opens
click:
type: boolean
nullable: true
description: Whether to track clicks
example:
open: true
click: true
Retention:
type: object
nullable: true
properties:
metadata:
type: integer
nullable: true
description: Number of days to retain metadata
minimum: 1
maximum: 30
data:
type: integer
nullable: true
description: Number of days to retain data
minimum: 0
maximum: 30
example:
metadata: 1
data: 0
MessageSchedule:
type: object
properties:
first_attempt:
type: string
format: date-time
description: >-
The time to make the first attempt for delivering the message. Must
be RFC3339 format, in the future, and within 7 days of the request.
expires:
type: string
format: date-time
description: >-
Expire and drop the message if not delivered by this time. Must be
RFC3339 format, in the future, and within 8 days of the request.
CreateSingleMessageResponse:
type: object
required:
- object
- recipient
- status
properties:
object:
type: string
enum:
- message
description: Object type identifier
id:
type: string
nullable: true
description: Message ID (null if the message was not sent)
example:
recipient:
$ref: '#/components/schemas/Recipient'
status:
type: string
enum:
- queued
- scheduled
- error
description: Status of the message
error:
type: string
nullable: true
description: Error message if the message was not sent
schedule:
$ref: '#/components/schemas/MessageSchedule'
description: Provided if the request contained a schedule
headers:
IdempotentReplayed:
description: >
Indicates whether this response is replayed from a previous identical
request.
- `true`: Response was replayed from cache (duplicate request)
- `false`: Response from original processing or error state
schema:
type: string
enum:
- true
- false
responses:
IdempotencyConflict:
description: >-
Request in progress - a request with this idempotency key is already
being processed
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
message: A request with this idempotency key is already in progress
IdempotencyPreconditionFailed:
description: >-
Original request failed - the request with this idempotency key
previously failed and cannot be retried
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
message: >-
The original request with this idempotency key failed and cannot
be retried
IdempotencyPayloadMismatch:
description: Idempotency key was already used with a different request payload
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
message: idempotency key was already used with a different request payload
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: aha-sk-64-CHARACTER-RANDOM-STRING
description: API key for authentication
````