OpenAPI Specification
openapi: 3.1.0
info:
title: AhaSend API v2 Accounts 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: Accounts
description: Manage account settings and members
paths:
/v2/accounts/{account_id}:
get:
summary: AhaSend Get Account
description: Returns account information
operationId: getAccount
tags:
- Accounts
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
example: '500123'
security:
- BearerAuth:
- accounts:read
responses:
'200':
description: Account details
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
examples:
getAccount200Example:
summary: Default getAccount 200 response
x-microcks-default: true
value:
object: account
id: '500123'
created_at: '2025-03-15T14:30:00Z'
updated_at: '2025-03-15T14:30:00Z'
name: Example Name
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getAccount400Example:
summary: Default getAccount 400 response
x-microcks-default: true
value:
message: example_value
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getAccount401Example:
summary: Default getAccount 401 response
x-microcks-default: true
value:
message: example_value
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getAccount403Example:
summary: Default getAccount 403 response
x-microcks-default: true
value:
message: example_value
'404':
description: Account not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getAccount404Example:
summary: Default getAccount 404 response
x-microcks-default: true
value:
message: example_value
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getAccount500Example:
summary: Default getAccount 500 response
x-microcks-default: true
value:
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: AhaSend Update Account
description: 'Updates account settings
**Validation Requirements:**
- `name` must be maximum 255 characters
- `website` must be a valid URL
- `message_metadata_retention` must be between 1 and 30 days
- `message_data_retention` must be between 0 and 30 days
'
operationId: updateAccount
tags:
- Accounts
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
example: '500123'
security:
- BearerAuth:
- accounts:write
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAccountRequest'
responses:
'200':
description: Account updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
examples:
updateAccount200Example:
summary: Default updateAccount 200 response
x-microcks-default: true
value:
object: account
id: '500123'
created_at: '2025-03-15T14:30:00Z'
updated_at: '2025-03-15T14:30:00Z'
name: Example Name
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
updateAccount400Example:
summary: Default updateAccount 400 response
x-microcks-default: true
value:
message: example_value
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
updateAccount401Example:
summary: Default updateAccount 401 response
x-microcks-default: true
value:
message: example_value
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
updateAccount403Example:
summary: Default updateAccount 403 response
x-microcks-default: true
value:
message: example_value
'404':
description: Account not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
updateAccount404Example:
summary: Default updateAccount 404 response
x-microcks-default: true
value:
message: example_value
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
updateAccount500Example:
summary: Default updateAccount 500 response
x-microcks-default: true
value:
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v2/accounts/{account_id}/members:
get:
summary: AhaSend Get Account Members
description: Returns a list of account members
operationId: getAccountMembers
tags:
- Accounts
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
example: '500123'
security:
- BearerAuth:
- accounts:members:read
responses:
'200':
description: List of account members
content:
application/json:
schema:
$ref: '#/components/schemas/AccountMembersResponse'
examples:
getAccountMembers200Example:
summary: Default getAccountMembers 200 response
x-microcks-default: true
value:
object: list
data:
- {}
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getAccountMembers400Example:
summary: Default getAccountMembers 400 response
x-microcks-default: true
value:
message: example_value
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getAccountMembers401Example:
summary: Default getAccountMembers 401 response
x-microcks-default: true
value:
message: example_value
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getAccountMembers403Example:
summary: Default getAccountMembers 403 response
x-microcks-default: true
value:
message: example_value
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getAccountMembers500Example:
summary: Default getAccountMembers 500 response
x-microcks-default: true
value:
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: AhaSend Add Account Member
description: 'Adds a new member to the account
**Validation Requirements:**
- `email` must be a valid email address
- `role` must be one of: Administrator, Developer, Analyst, Billing Manager
'
operationId: addAccountMember
tags:
- Accounts
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:
- accounts:members:add
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddMemberRequest'
responses:
'200':
description: Member added successfully
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/UserAccount'
examples:
addAccountMember200Example:
summary: Default addAccountMember 200 response
x-microcks-default: true
value:
id: '500123'
created_at: '2025-03-15T14:30:00Z'
updated_at: '2025-03-15T14:30:00Z'
user_id: '500123'
account_id: '500123'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
addAccountMember400Example:
summary: Default addAccountMember 400 response
x-microcks-default: true
value:
message: example_value
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
addAccountMember401Example:
summary: Default addAccountMember 401 response
x-microcks-default: true
value:
message: example_value
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
addAccountMember403Example:
summary: Default addAccountMember 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:
addAccountMember500Example:
summary: Default addAccountMember 500 response
x-microcks-default: true
value:
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v2/accounts/{account_id}/members/{user_id}:
delete:
summary: AhaSend Remove Account Member
description: 'Removes a member from the account
**Restrictions:**
- You cannot delete yourself
- You cannot delete the account owner
'
operationId: removeAccountMember
tags:
- Accounts
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
example: '500123'
- name: user_id
in: path
required: true
description: User ID
schema:
type: string
format: uuid
example: '500123'
security:
- BearerAuth:
- accounts:members:remove
responses:
'200':
description: Member removed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
examples:
removeAccountMember200Example:
summary: Default removeAccountMember 200 response
x-microcks-default: true
value:
message: example_value
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
removeAccountMember400Example:
summary: Default removeAccountMember 400 response
x-microcks-default: true
value:
message: example_value
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
removeAccountMember401Example:
summary: Default removeAccountMember 401 response
x-microcks-default: true
value:
message: example_value
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
removeAccountMember403Example:
summary: Default removeAccountMember 403 response
x-microcks-default: true
value:
message: example_value
'404':
description: Member not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
removeAccountMember404Example:
summary: Default removeAccountMember 404 response
x-microcks-default: true
value:
message: example_value
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
removeAccountMember500Example:
summary: Default removeAccountMember 500 response
x-microcks-default: true
value:
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
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: example_value
example:
message: Error message
AccountMembersResponse:
type: object
required:
- object
- data
properties:
object:
type: string
enum:
- list
description: Object type identifier
example: list
data:
type: array
items:
$ref: '#/components/schemas/UserAccount'
description: Array of account members
example:
- id: '500123'
created_at: '2025-03-15T14:30:00Z'
updated_at: '2025-03-15T14:30:00Z'
user_id: '500123'
account_id: '500123'
AddMemberRequest:
type: object
required:
- email
- role
properties:
email:
type: string
format: email
description: Email address of the user to add
example: user@example.com
name:
type: string
description: Display name for the user
example: Example Name
role:
type: string
enum:
- Administrator
- Developer
- Analyst
- Billing Manager
description: Role to assign to the user
example: Administrator
example:
email: user@example.com
name: John Doe
role: Developer
SuccessResponse:
type: object
required:
- message
properties:
message:
type: string
description: Success message
example: example_value
example:
message: Operation completed successfully
UserAccount:
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier for the user account relationship
example: '500123'
created_at:
type: string
format: date-time
description: When the relationship was created
example: '2025-03-15T14:30:00Z'
updated_at:
type: string
format: date-time
description: When the relationship was last updated
example: '2025-03-15T14:30:00Z'
user_id:
type: string
format: uuid
description: User ID
example: '500123'
account_id:
type: string
format: uuid
description: Account ID
example: '500123'
role:
type: string
enum:
- Administrator
- Developer
- Analyst
- Billing Manager
description: User role in the account
example: Administrator
required:
- id
- created_at
- updated_at
- user_id
- account_id
- role
Account:
type: object
properties:
object:
type: string
enum:
- account
description: Object type identifier
example: account
id:
type: string
format: uuid
description: Unique identifier for the account
example: '500123'
created_at:
type: string
format: date-time
description: When the account was created
example: '2025-03-15T14:30:00Z'
updated_at:
type: string
format: date-time
description: When the account was last updated
example: '2025-03-15T14:30:00Z'
name:
type: string
description: Account name
example: Example Name
website:
type: string
format: uri
nullable: true
description: Account website URL
example: https://example.com
about:
type: string
nullable: true
description: Account description
example: example_value
track_opens:
type: boolean
description: Default open tracking setting
example: true
track_clicks:
type: boolean
description: Default click tracking setting
example: true
reject_bad_recipients:
type: boolean
description: Whether to reject bad recipients
example: true
reject_mistyped_recipients:
type: boolean
description: Whether to reject mistyped recipients
example: true
message_metadata_retention:
type: integer
description: Default message metadata retention in days
example: 1
message_data_retention:
type: integer
description: Default message data retention in days
example: 1
required:
- object
- id
- created_at
- updated_at
- name
UpdateAccountRequest:
type: object
properties:
name:
type: string
maxLength: 255
description: Account name
example: Example Name
website:
type: string
format: uri
description: Account website URL
example: https://example.com
about:
type: string
description: Account description (used for account verification)
example: example_value
track_opens:
type: boolean
description: Default open tracking setting
example: true
track_clicks:
type: boolean
description: Default click tracking setting
example: true
reject_bad_recipients:
type: boolean
description: Whether to reject bad recipients
example: true
reject_mistyped_recipients:
type: boolean
description: Whether to reject mistyped recipients
example: true
message_metadata_retention:
type: integer
minimum: 1
maximum: 30
description: Default message metadata retention in days
example: 1
message_data_retention:
type: integer
minimum: 0
maximum: 30
description: Default message data retention in days
example: 1
example:
name: Updated Company Name
website: https://example.com
track_opens: true
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
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: aha-sk-64-CHARACTER-RANDOM-STRING
description: API key for authentication