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`

- Idempotency keys expire after 24 hours

version: "2.0.0"

contact:

email: [email protected]

license:

name: MIT

identifier: MIT

servers:

- url: https://api.ahasend.com

description: Production server

security:

- BearerAuth: []

components:

securitySchemes:

BearerAuth:

type: http

scheme: bearer

bearerFormat: "aha-sk-64-CHARACTER-RANDOM-STRING"

description: API key for authentication

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"

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"

schemas:

ErrorResponse:

type: object

required:

- message

properties:

message:

type: string

description: Error description

example:

message: "Error message"

SuccessResponse:

type: object

required:

- message

properties:

message:

type: string

description: Success message

example:

message: "Operation completed successfully"

PaginationInfo:

type: object

required:

- has_more

properties:

has_more:

type: boolean

description: Whether there are more items available

next_cursor:

type: string

description: Cursor for the next page of results

previous_cursor:

type: string

description: Cursor for the previous page of results

example:

has_more: true

next_cursor: "eyJpZCI6MTIzNH0="

# API Key Schemas

APIKeyScope:

type: object

properties:

id:

type: string

format: uuid

description: Unique identifier for the scope

created_at:

type: string

format: date-time

description: When the scope was created

updated_at:

type: string

format: date-time

description: When the scope was last updated

api_key_id:

type: string

format: uuid

description: ID of the API key this scope belongs to

scope:

type: string

description: The scope string

domain_id:

type: string

format: uuid

description: Domain ID for domain-specific scopes

required:

- id

- created_at

- updated_at

- api_key_id

- scope

APIKey:

type: object

properties:

object:

type: string

enum: [api_key]

description: Object type identifier

id:

type: string

format: uuid

description: Unique identifier for the API key

created_at:

type: string

format: date-time

description: When the API key was created

updated_at:

type: string

format: date-time

description: When the API key was last updated

last_used_at:

type: string

format: date-time

description: When the API key was last used (updates every 5-10 minutes)

account_id:

type: string

format: uuid

description: Account ID this API key belongs to

label:

type: string

description: Human-readable label for the API key

public_key:

type: string

description: Public portion of the API key

secret_key:

type: string

description: Secret key (only returned on creation)

scopes:

type: array

items:

$ref: '#/components/schemas/APIKeyScope'

description: Scopes granted to this API key

required:

- object

- id

- created_at

- updated_at

- account_id

- label

- public_key

- scopes

CreateAPIKeyRequest:

type: object

required:

- label

- scopes

properties:

label:

type: string

maxLength: 255

description: Human-readable label for the API key

scopes:

type: array

items:

type: string

minItems: 1

description: Array of scope strings to grant to this API key

example:

label: "Production API Key"

scopes: ["messages:send:all", "domains:read"]

UpdateAPIKeyRequest:

type: object

properties:

label:

type: string

maxLength: 255

description: Human-readable label for the API key

scopes:

type: array

items:

type: string

minItems: 1

description: Array of scope strings to grant to this API key

example:

label: "Updated API Key"

scopes: ["messages:send:example.com", "domains:read"]

PaginatedAPIKeysResponse:

type: object

required:

- object

- data

- pagination

properties:

object:

type: string

enum: [list]

description: Object type identifier

data:

type: array

items:

$ref: '#/components/schemas/APIKey'

description: Array of API keys

pagination:

$ref: '#/components/schemas/PaginationInfo'

# Domain Schemas

DNSRecord:

type: object

properties:

type:

type: string

description: DNS record type (e.g., CNAME, TXT, MX)

host:

type: string

description: DNS record host/name

content:

type: string

description: DNS record content/value

required:

type: boolean

description: Whether this DNS record is required for domain verification

propagated:

type: boolean

description: Whether this DNS record has been propagated and verified

required:

- type

- host

- content

- required

- propagated

Domain:

type: object

properties:

object:

type: string

enum: [domain]

description: Object type identifier

id:

type: string

format: uuid

description: Unique identifier for the domain

created_at:

type: string

format: date-time

description: When the domain was created

updated_at:

type: string

format: date-time

description: When the domain was last updated

domain:

type: string

description: The domain name

account_id:

type: string

format: uuid

description: Account ID this domain belongs to

dns_records:

type: array

items:

$ref: '#/components/schemas/DNSRecord'

description: DNS records required for domain verification

last_dns_check_at:

type: string

nullable: true

format: date-time

description: When DNS records were last checked

dns_valid:

type: boolean

description: Whether all required DNS records are properly configured

tracking_subdomain:

type: string

nullable: true

description: Custom tracking subdomain. Null means the account or product default is used.

return_path_subdomain:

type: string

nullable: true

description: Custom return-path subdomain. Null means the account or product default is used.

subscription_subdomain:

type: string

nullable: true

description: Custom subscription management subdomain. Null means the account or product default is used.

media_subdomain:

type: string

nullable: true

description: Custom media subdomain. Null means the account or product default is used.

dkim_rotation_interval_days:

type: integer

nullable: true

description: Custom DKIM rotation interval in days. Null means the account default is used.

rotation_ready:

type: boolean

description: Whether the standby DKIM slot is ready for rotation.

required:

- object

- id

- created_at

- updated_at

- domain

- account_id

- dns_records

- dns_valid

CreateDomainRequest:

type: object

required:

- domain

properties:

domain:

type: string

format: hostname

description: Fully qualified domain name

dkim_private_key:

type: string

description: |

DKIM Private Key for the domain. Only RSA keys with a minimum key size of 2048 bits are supported.

**Note:** This parameter is only supported on [Platform Partner](https://ahasend.com/partners) accounts.

tracking_subdomain:

type: string

description: Optional custom tracking subdomain. Omit to use the default on create.

return_path_subdomain:

type: string

description: Optional custom return-path subdomain. Omit to use the default on create.

subscription_subdomain:

type: string

description: Optional custom subscription management subdomain. Omit to use the default on create.

media_subdomain:

type: string

description: Optional custom media subdomain. Omit to use the default on create.

dkim_rotation_interval_days:

type: integer

description: Optional custom DKIM rotation interval in days. Only supported for managed DNS domains on eligible plans.

example:

domain: "example.com"

tracking_subdomain: "click"

return_path_subdomain: "mail"

subscription_subdomain: "preferences"

media_subdomain: "media"

dkim_rotation_interval_days: 45

UpdateDomainRequest:

type: object

properties:

tracking_subdomain:

type: string

description: Optional custom tracking subdomain. Omit to leave the current value unchanged.

return_path_subdomain:

type: string

description: Optional custom return-path subdomain. Omit to leave the current value unchanged.

subscription_subdomain:

type: string

description: Optional custom subscription management subdomain. Omit to leave the current value unchanged.

media_subdomain:

type: string

description: Optional custom media subdomain. Omit to leave the current value unchanged.

dkim_rotation_interval_days:

type: integer

description: Optional custom DKIM rotation interval in days. Omit to leave the current value unchanged. Only supported for managed DNS domains on eligible plans.

example:

tracking_subdomain: "click"

return_path_subdomain: "mail"

subscription_subdomain: "preferences"

media_subdomain: "media"

dkim_rotation_interval_days: 45

PaginatedDomainsResponse:

type: object

required:

- object

- data

- pagination

properties:

object:

type: string

enum: [list]

description: Object type identifier

data:

type: array

items:

$ref: '#/components/schemas/Domain'

description: Array of domains

pagination:

$ref: '#/components/schemas/PaginationInfo'

# Message Schemas

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: "[email protected]"

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: "[email protected]"

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 (RFC3339 format)

expires:

type: string

format: date-time

description: Expire and drop the message if not delivered by this time (RFC3339 format)

example:

first_attempt: "2023-12-25T10:30:00Z"

expires: "2023-12-26T10:30:00Z"

CreateMessageRequest:

type: object

required:

- from

- recipients

- subject

properties:

from:

$ref: '#/components/schemas/Address'

recipients:

type: array

items:

$ref: '#/components/schemas/Recipient'

minItems: 1

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: "[email protected]"

name: "Example Corp"

recipients:

- email: "[email protected]"

name: "John Doe"

subject: "Welcome to Example Corp"

html_content: "<h1>Welcome {{first_name}}!</h1>"

text_content: "Welcome {{first_name}}!"

substitutions:

first_name: "John"

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.

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.

bcc:

type: array

items:

$ref: '#/components/schemas/Address'

minItems: 1

description: This parameter can set the `To` header to multiple addresses.

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. `cc` and `reply-to` headers cannot be provided if `reply_to` or `cc` parameters are provided, message-id will be ignored and automatically generated

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: "[email protected]"

name: "Example Corp"

to:

- email: "[email protected]"

name: "John Doe"

- email: "[email protected]"

name: "Jane Doe"

cc:

- email: "[email protected]"

name: "Example Corp HR"

bcc:

- email: "[email protected]"

name: "BCC Recipient"

subject: "Welcome to Example Corp"

html_content: "<h1>Dear John and Jane, welcome to Example Corp!</h1>"

text_content: "Dear John and Jane, welcome to Example Corp!"

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: <[email protected]>

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

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

DeliveryEvent:

type: object

properties:

time:

type: string

format: date-time

description: Timestamp of the delivery event

log:

type: string

description: Log message for the delivery event

status:

type: string

description: Status of the delivery event

required:

- time

- log

- status

MessageContentPart:

type: object

properties:

content_type:

type: string

description: MIME content type (e.g., "text/plain", "text/html")

example: "text/html"

content:

type: string

description: The actual content for this part

required:

- content_type

- content

MessageAttachment:

type: object

properties:

filename:

type: string

description: Original filename of the attachment

example: "document.pdf"

content:

type: string

description: Base64 encoded attachment content

content_type:

type: string

description: MIME content type of the attachment

example: "application/pdf"

content_id:

type: string

description: Content-ID for inline attachments

nullable: true

example: "[email protected]"

required:

- filename

- content

- content_type

MessageContentParsed:

type: object

properties:

parts:

type: array

items:

$ref: '#/components/schemas/MessageContentPart'

description: Array of message content parts (text, HTML, etc.)

attachments:

type: array

items:

$ref: '#/components/schemas/MessageAttachment'

description: Array of message attachments

headers:

type: object

additionalProperties:

type: array

items:

type: string

description: Email headers as key-value pairs (values are arrays to handle multiple headers with same name)

example:

"Content-Type": ["text/html; charset=utf-8"]

"X-Custom-Header": ["value1", "value2"]

required:

- parts

- attachments

- headers

# Base message schema without heavy content fields

MessageSummary:

type: object

properties:

object:

type: string

enum: [message]

description: Object type identifier

created_at:

type: string

format: date-time

description: When the message was created

updated_at:

type: string

format: date-time

description: When the message was last updated

sent_at:

type: string

format: date-time

nullable: true

description: When the message was sent

delivered_at:

type: string

format: date-time

nullable: true

description: When the message was delivered

retain_until:

type: string

format: date-time

description: When the message data will be purged

direction:

type: string

enum: [incoming, outgoing]

description: Message direction

is_bounce_notification:

type: boolean

description: Whether this is a bounce notification

bounce_classification:

type: string

description: Classification of bounce if applicable

delivery_attempts:

type: array

items:

$ref: '#/components/schemas/DeliveryEvent'

description: List of delivery attempts for this message

message_id:

type: string

description: Message-ID header value