openapi: 3.1.0
info:
title: AhaSend API v2 Accounts Messages API
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`
- 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: Messages
description: Send and manage transactional messages
paths:
/v2/accounts/{account_id}/messages:
get:
summary: AhaSend Get Messages
description: 'Returns a list of message summaries for the account. Can be filtered by various parameters.
'
operationId: getMessages
tags:
- Messages
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
example: '500123'
- name: status
in: query
description: Filter by comma-separated list of message statuses
schema:
type: string
example: Bounced,Failed
- name: sender
in: query
description: Sender email address (must be from domain in API key scopes)
schema:
type: string
format: email
example: example_value
- name: recipient
in: query
description: Recipient email address
schema:
type: string
format: email
example: example_value
- name: subject
in: query
description: Filter by subject text
schema:
type: string
example: example_value
- name: message_id_header
in: query
description: Filter by message ID header (same ID returned by CreateMessage API)
schema:
type: string
example: '500123'
- name: tags
in: query
description: Filter by comma-separated list of tags (max 20)
schema:
type: string
example: billing,urgent
- name: from_time
in: query
description: Filter messages created after this time (RFC3339 format)
schema:
type: string
format: date-time
example: '2023-12-25T10:30:00Z'
- name: to_time
in: query
description: Filter messages created before this time (RFC3339 format)
schema:
type: string
format: date-time
example: '2023-12-26T10:30:00Z'
- name: limit
in: query
description: Maximum number of items to return (1-100)
schema:
type: integer
minimum: 1
maximum: 100
default: 100
example: 1
- name: after
in: query
description: Pagination cursor for the next page. Provide the value provided in `next_cursor` from the response.
schema:
type: string
example: example_value
- name: before
in: query
description: Pagination cursor for the previous page.
schema:
type: string
example: example_value
security:
- BearerAuth:
- messages:read:all
- messages:read:{domain}
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n\n \"github.com/AhaSend/ahasend-go\"\n \"github.com/AhaSend/ahasend-go/api\"\n \"github.com/AhaSend/ahasend-go/models/requests\"\n \"github.com/google/uuid\"\n)\n\nfunc main() {\n // Create API client with authentication\n client := api.NewAPIClient(\n api.WithAPIKey(\"aha-sk-your-64-character-key\"),\n )\n\n accountID := uuid.New()\n\n // Create context for the API call\n ctx := context.Background()\n\n // Call the ping endpoint\n response, httpResp, err := client.MessagesAPI.GetMessages(\n ctx,\n accountID,\n requests.GetMessagesParams{\n Status: ahasend.String(\"bounced,failed\"),\n Sender: ahasend.String(\"info@example.com\"),\n Tags: []string{\"billing\", \"urgent\"},\n },\n )\n if err != nil {\n log.Fatalf(\"Error getting messages: %v\", err)\n }\n\n // Check response\n if httpResp.StatusCode == 200 {\n fmt.Printf(\"✅ Status: %d\\n\", httpResp.StatusCode)\n if response != nil {\n fmt.Printf(\"Found %d messages\\n\", len(response.Data))\n }\n } else {\n fmt.Printf(\"❌ Unexpected status code: %d\\n\", httpResp.StatusCode)\n }\n}\n"
responses:
'200':
description: List of messages
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedMessagesResponse'
examples:
getMessages200Example:
summary: Default getMessages 200 response
x-microcks-default: true
value:
object: list
data:
- {}
pagination:
has_more: {}
next_cursor: {}
previous_cursor: {}
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getMessages400Example:
summary: Default getMessages 400 response
x-microcks-default: true
value:
message: example_value
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getMessages401Example:
summary: Default getMessages 401 response
x-microcks-default: true
value:
message: example_value
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getMessages403Example:
summary: Default getMessages 403 response
x-microcks-default: true
value:
message: example_value
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getMessages500Example:
summary: Default getMessages 500 response
x-microcks-default: true
value:
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: AhaSend 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
'
operationId: createMessage
tags:
- Messages
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
example: '500123'
- $ref: '#/components/parameters/IdempotencyKey'
example: example
security:
- BearerAuth:
- messages:send:all
- messages:send:{domain}
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n\n \"github.com/AhaSend/ahasend-go\"\n \"github.com/AhaSend/ahasend-go/api\"\n \"github.com/AhaSend/ahasend-go/models/common\"\n \"github.com/AhaSend/ahasend-go/models/requests\"\n \"github.com/google/uuid\"\n)\n\nfunc main() {\n // Create API client with authentication\n client := api.NewAPIClient(\n api.WithAPIKey(\"aha-sk-your-64-character-key\"),\n )\n\n accountID := uuid.New()\n\n // Create context for the API call\n ctx := context.Background()\n\n response, httpResp, err := client.MessagesAPI.CreateMessage(\n ctx,\n accountID,\n requests.CreateMessageRequest{\n From: common.Address{\n Email: \"info@example.com\",\n Name: ahasend.String(\"Example Corp.\"),\n },\n Recipients: []common.Recipient{\n {\n Email: \"john@example.com\",\n Name: ahasend.String(\"John Smith\"),\n },\n },\n Subject: \"Hello\",\n TextContent: ahasend.String(\"Hello world!\"),\n Sandbox: ahasend.Bool(true),\n },\n )\n if err != nil {\n log.Fatalf(\"Error sending message: %v\", err)\n }\n\n // Check response\n if httpResp.StatusCode == 200 {\n fmt.Printf(\"✅ Send successful! Status: %d\\n\", httpResp.StatusCode)\n if response != nil {\n fmt.Printf(\"Message ID: %s\\n\", *response.Data[0].ID)\n }\n } else {\n fmt.Printf(\"❌ Unexpected status code: %d\\n\", httpResp.StatusCode)\n }\n}\n"
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'
examples:
createMessage202Example:
summary: Default createMessage 202 response
x-microcks-default: true
value:
object: list
data:
- {}
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
createMessage400Example:
summary: Default createMessage 400 response
x-microcks-default: true
value:
message: example_value
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
createMessage401Example:
summary: Default createMessage 401 response
x-microcks-default: true
value:
message: example_value
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
createMessage403Example:
summary: Default createMessage 403 response
x-microcks-default: true
value:
message: example_value
'409':
$ref: '#/components/responses/IdempotencyConflict'
'412':
$ref: '#/components/responses/IdempotencyPreconditionFailed'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
createMessage500Example:
summary: Default createMessage 500 response
x-microcks-default: true
value:
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v2/accounts/{account_id}/messages/conversation:
post:
summary: AhaSend Create Conversational Message
description: 'Creates and sends a conversational message (with support for CC and BCC) to one or more recipients. This API does not support template substitutions, use [Create Message](https://ahasend.com/docs/api-reference/messages/create-message) instead if you need substitutions.
**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 the `reply_to` parameter is provided, do not include `reply-to` in headers
- If the `cc` parameter is provided, do not include `cc` in headers
- `message-id` header will be ignored and automatically generated
- Schedule times must be in RFC3339 format
'
operationId: createConversationMessage
tags:
- Messages
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
example: '500123'
- $ref: '#/components/parameters/IdempotencyKey'
example: example
security:
- BearerAuth:
- messages:send:all
- messages:send:{domain}
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateConversationMessageRequest'
responses:
'202':
description: Message created successfully
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMessageResponse'
examples:
createConversationMessage202Example:
summary: Default createConversationMessage 202 response
x-microcks-default: true
value:
object: list
data:
- {}
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
createConversationMessage400Example:
summary: Default createConversationMessage 400 response
x-microcks-default: true
value:
message: example_value
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
createConversationMessage401Example:
summary: Default createConversationMessage 401 response
x-microcks-default: true
value:
message: example_value
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
createConversationMessage403Example:
summary: Default createConversationMessage 403 response
x-microcks-default: true
value:
message: example_value
'409':
$ref: '#/components/responses/IdempotencyConflict'
'412':
$ref: '#/components/responses/IdempotencyPreconditionFailed'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
createConversationMessage500Example:
summary: Default createConversationMessage 500 response
x-microcks-default: true
value:
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v2/accounts/{account_id}/messages/{message_id}:
get:
summary: AhaSend Get Message
description: 'Returns the complete message by its ID, including raw content and parsed content structure.
'
operationId: getMessage
tags:
- Messages
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
example: '500123'
- name: message_id
in: path
required: true
description: Message API ID (the same ID returned by [Create Message API](https://ahasend.com/docs/api-reference/messages/create-message))
schema:
type: string
format: uuid
example: '500123'
security:
- BearerAuth:
- messages:read:all
- messages:read:{domain}
responses:
'200':
description: Message details
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
examples:
getMessage200Example:
summary: Default getMessage 200 response
x-microcks-default: true
value: example_value
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getMessage400Example:
summary: Default getMessage 400 response
x-microcks-default: true
value:
message: example_value
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getMessage401Example:
summary: Default getMessage 401 response
x-microcks-default: true
value:
message: example_value
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getMessage403Example:
summary: Default getMessage 403 response
x-microcks-default: true
value:
message: example_value
'404':
description: Message not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getMessage404Example:
summary: Default getMessage 404 response
x-microcks-default: true
value:
message: example_value
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getMessage500Example:
summary: Default getMessage 500 response
x-microcks-default: true
value:
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v2/accounts/{account_id}/messages/{message_id}/cancel:
delete:
summary: AhaSend Cancel Message
description: Cancels a scheduled message
operationId: cancelMessage
tags:
- Messages
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
example: '500123'
- name: message_id
in: path
required: true
description: Message API ID (the same ID returned by [Create Message API](https://ahasend.com/docs/api-reference/messages/create-message))
schema:
type: string
example: '500123'
security:
- BearerAuth:
- messages:cancel:all
- messages:cancel:{domain}
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n\n \"github.com/AhaSend/ahasend-go/api\"\n \"github.com/google/uuid\"\n)\n\nfunc main() {\n // Create API client with authentication\n client := api.NewAPIClient(\n api.WithAPIKey(\"aha-sk-your-64-character-key\"),\n )\n\n accountID := uuid.New()\n\n // Create context for the API call\n ctx := context.Background()\n\n response, httpResp, err := client.MessagesAPI.CancelMessage(\n ctx,\n accountID,\n \"<uuid@example.com>\",\n )\n if err != nil {\n log.Fatalf(\"Error canceling message: %v\", err)\n }\n\n // Check response\n if httpResp.StatusCode == 200 {\n fmt.Printf(\"✅ Successfully canceled! Status: %d\\n\", httpResp.StatusCode)\n if response != nil {\n fmt.Printf(\"Message canceled: %s\\n\", response.Message)\n }\n } else {\n fmt.Printf(\"❌ Unexpected status code: %d\\n\", httpResp.StatusCode)\n }\n}\n"
responses:
'200':
description: Scheduled message is cancelled
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
examples:
cancelMessage200Example:
summary: Default cancelMessage 200 response
x-microcks-default: true
value:
message: example_value
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
cancelMessage400Example:
summary: Default cancelMessage 400 response
x-microcks-default: true
value:
message: example_value
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
cancelMessage401Example:
summary: Default cancelMessage 401 response
x-microcks-default: true
value:
message: example_value
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
cancelMessage403Example:
summary: Default cancelMessage 403 response
x-microcks-default: true
value:
message: example_value
'404':
description: Message not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
cancelMessage404Example:
summary: Default cancelMessage 404 response
x-microcks-default: true
value:
message: example_value
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
cancelMessage500Example:
summary: Default cancelMessage 500 response
x-microcks-default: true
value:
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
CreateMessageResponse:
type: object
required:
- object
- data
properties:
object:
type: string
enum:
- list
description: Object type identifier
example: list
data:
type: array
items:
$ref: '#/components/schemas/CreateSingleMessageResponse'
description: List of messages and their statuses
example:
- object: message
id: '500123'
recipient: {}
status: queued
error: example_value
MessageSchedule:
type: object
properties:
first_attempt:
type: string
format: date-time
description: The time to make the first attempt for delivering the message (RFC3339 format)
example: '2025-03-15T14:30:00Z'
expires:
type: string
format: date-time
description: Expire and drop the message if not delivered by this time (RFC3339 format)
example: '2025-03-15T14:30:00Z'
example:
first_attempt: '2023-12-25T10:30:00Z'
expires: '2023-12-26T10:30:00Z'
CreateConversationMessageRequest:
type: object
required:
- from
- recipients
- subject
properties:
from:
$ref: '#/components/schemas/Address'
to:
type: array
items:
$ref: '#/components/schemas/Address'
minItems: 1
description: This parameter can set the `To` header to multiple addresses.
example:
- email: user@example.com
name: Example Name
cc:
type: array
items:
$ref: '#/components/schemas/Address'
minItems: 1
description: This parameter can set the `CC` header to multiple addresses. Do not include `cc` in the headers array.
example:
- email: user@example.com
name: Example Name
bcc:
type: array
items:
$ref: '#/components/schemas/Address'
minItems: 1
description: This parameter can set the `To` header to multiple addresses.
example:
- email: user@example.com
name: Example Name
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
example: example_value
text_content:
type: string
description: Plain text content. Required if html_content is empty
example: example_value
html_content:
type: string
description: HTML content. Required if text_content is empty
example: example_value
amp_content:
type: string
description: AMP HTML content
example: example_value
attachments:
type: array
items:
$ref: '#/components/schemas/Attachment'
description: File attachments
example:
- base64: true
data: example_value
content_type: example_value
content_disposition: example_value
content_id: '500123'
headers:
type: object
additionalProperties:
type: string
description: Custom email headers. `cc` and `reply-to` headers cannot be provided if `reply_to` or `cc` parameters are provided, message-id will be ignored and automatically generated
example: {}
tags:
type: array
items:
type: string
description: Tags for categorizing messages
example:
- example_value
sandbox:
type: boolean
description: If true, th
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ahasend/refs/heads/main/openapi/ahasend-messages-api-openapi.yml