openapi: 3.1.0
info:
title: AhaSend API v2 Accounts Statistics 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: Statistics
description: Access transactional email statistics
paths:
/v2/accounts/{account_id}/statistics/transactional/deliverability:
get:
summary: AhaSend Get Deliverability Statistics
description: 'Returns transactional deliverability statistics grouped by status
**Query Parameters:**
- `from_time`: Filter statistics after this date (RFC3339 format)
- `to_time`: Filter statistics before this date (RFC3339 format)
- `sender_domain`: Filter by sender domain
- `recipient_domains`: Filter by recipient domain
- `tags`: Filter by tags (comma-separated)
- `group_by`: Group by time period (hour, day, week, month)
'
operationId: getDeliverabilityStatistics
tags:
- Statistics
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
example: '500123'
- name: from_time
in: query
description: Filter statistics after this datetime (RFC3339 format)
schema:
type: string
format: date-time
example: '2025-03-15T14:30:00Z'
- name: to_time
in: query
description: Filter statistics before this datetime (RFC3339 format)
schema:
type: string
format: date-time
example: '2025-03-15T14:30:00Z'
- name: sender_domain
in: query
description: Filter by sender domain
schema:
type: string
example: mail.example.com
- name: recipient_domains
in: query
description: Filter by a comma separated list of recipient domains
schema:
type: string
example: gmail.com,googlemail.com
- name: tags
in: query
description: Filter by tags (comma-separated)
schema:
type: string
example: example_value
- name: group_by
in: query
description: Group by time period
schema:
type: string
enum:
- hour
- day
- week
- month
default: day
example: hour
security:
- BearerAuth:
- statistics-transactional:read:all
- statistics-transactional:read:{domain}
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"time\"\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 fromTime := time.Now().Add(-time.Hour * 24 * 30)\n // Call the ping endpoint\n response, httpResp, err := client.StatisticsAPI.GetDeliverabilityStatistics(\n ctx,\n accountID,\n requests.GetDeliverabilityStatisticsParams{\n FromTime: &fromTime,\n SenderDomain: ahasend.String(\"example.com\"),\n RecipientDomains: ahasend.String(\"gmail.com\"),\n GroupBy: ahasend.String(\"week\"),\n },\n )\n if err != nil {\n log.Fatalf(\"Error getting deliverability statistics: %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(\"Deliverability statistics: %#v\\n\", response)\n }\n } else {\n fmt.Printf(\"❌ Unexpected status code: %d\\n\", httpResp.StatusCode)\n }\n}\n"
responses:
'200':
description: Deliverability statistics
content:
application/json:
schema:
$ref: '#/components/schemas/DeliverabilityStatisticsResponse'
examples:
getDeliverabilityStatistics200Example:
summary: Default getDeliverabilityStatistics 200 response
x-microcks-default: true
value:
object: list
data:
- {}
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getDeliverabilityStatistics400Example:
summary: Default getDeliverabilityStatistics 400 response
x-microcks-default: true
value:
message: example_value
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getDeliverabilityStatistics401Example:
summary: Default getDeliverabilityStatistics 401 response
x-microcks-default: true
value:
message: example_value
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getDeliverabilityStatistics403Example:
summary: Default getDeliverabilityStatistics 403 response
x-microcks-default: true
value:
message: example_value
'429':
description: Too many requests (rate limited to 1 request per second)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getDeliverabilityStatistics429Example:
summary: Default getDeliverabilityStatistics 429 response
x-microcks-default: true
value:
message: example_value
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getDeliverabilityStatistics500Example:
summary: Default getDeliverabilityStatistics 500 response
x-microcks-default: true
value:
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v2/accounts/{account_id}/statistics/transactional/bounce:
get:
summary: AhaSend Get Bounce Statistics
description: 'Returns transactional bounce statistics grouped by classification
**Query Parameters:**
- `from_time`: Filter statistics after this date (RFC3339 format)
- `to_time`: Filter statistics before this date (RFC3339 format)
- `sender_domain`: Filter by sender domain
- `recipient_domains`: Filter by recipient domain
- `tags`: Filter by tags (comma-separated)
- `group_by`: Group by time period (hour, day, week, month)
'
operationId: getBounceStatistics
tags:
- Statistics
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
example: '500123'
- name: from_time
in: query
description: Filter statistics after this datetime (RFC3339 format)
schema:
type: string
format: date-time
example: '2025-03-15T14:30:00Z'
- name: to_time
in: query
description: Filter statistics before this datetime (RFC3339 format)
schema:
type: string
format: date-time
example: '2025-03-15T14:30:00Z'
- name: sender_domain
in: query
description: Filter by sender domain
schema:
type: string
example: mail.example.com
- name: recipient_domains
in: query
description: Filter by a comma separated list of recipient domains
schema:
type: string
example: gmail.com,googlemail.com
- name: tags
in: query
description: Filter by tags (comma-separated)
schema:
type: string
example: example_value
- name: group_by
in: query
description: Group by time period
schema:
type: string
enum:
- hour
- day
- week
- month
default: day
example: hour
security:
- BearerAuth:
- statistics-transactional:read:all
- statistics-transactional:read:{domain}
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"time\"\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 fromTime := time.Now().Add(-time.Hour * 24 * 30)\n // Call the ping endpoint\n response, httpResp, err := client.StatisticsAPI.GetBounceStatistics(\n ctx,\n accountID,\n requests.GetBounceStatisticsParams{\n FromTime: &fromTime,\n SenderDomain: ahasend.String(\"example.com\"),\n RecipientDomains: ahasend.String(\"gmail.com\"),\n GroupBy: ahasend.String(\"week\"),\n },\n )\n if err != nil {\n log.Fatalf(\"Error getting bounce statistics: %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(\"Bounce statistics: %#v\\n\", response)\n }\n } else {\n fmt.Printf(\"❌ Unexpected status code: %d\\n\", httpResp.StatusCode)\n }\n}\n"
responses:
'200':
description: Bounce statistics
content:
application/json:
schema:
$ref: '#/components/schemas/BounceStatisticsResponse'
examples:
getBounceStatistics200Example:
summary: Default getBounceStatistics 200 response
x-microcks-default: true
value:
object: list
data:
- {}
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getBounceStatistics400Example:
summary: Default getBounceStatistics 400 response
x-microcks-default: true
value:
message: example_value
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getBounceStatistics401Example:
summary: Default getBounceStatistics 401 response
x-microcks-default: true
value:
message: example_value
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getBounceStatistics403Example:
summary: Default getBounceStatistics 403 response
x-microcks-default: true
value:
message: example_value
'429':
description: Too many requests (rate limited to 1 request per second)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getBounceStatistics429Example:
summary: Default getBounceStatistics 429 response
x-microcks-default: true
value:
message: example_value
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getBounceStatistics500Example:
summary: Default getBounceStatistics 500 response
x-microcks-default: true
value:
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v2/accounts/{account_id}/statistics/transactional/delivery-time:
get:
summary: AhaSend Get Delivery Time Statistics
description: 'Returns transactional delivery time statistics grouped by recipient domain
**Query Parameters:**
- `from_time`: Filter statistics after this date (RFC3339 format)
- `to_time`: Filter statistics before this date (RFC3339 format)
- `sender_domain`: Filter by sender domain
- `recipient_domains`: Filter by recipient domains
- `tags`: Filter by tags (comma-separated)
- `group_by`: Group by time period (hour, day, week, month)
'
operationId: getDeliveryTimeStatistics
tags:
- Statistics
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
example: '500123'
- name: from_time
in: query
description: Filter statistics after this datetime (RFC3339 format)
schema:
type: string
format: date-time
example: '2025-03-15T14:30:00Z'
- name: to_time
in: query
description: Filter statistics before this datetime (RFC3339 format)
schema:
type: string
format: date-time
example: '2025-03-15T14:30:00Z'
- name: sender_domain
in: query
description: Filter by sender domain
schema:
type: string
example: mail.example.com
- name: recipient_domains
in: query
description: Filter by a comma separated list of recipient domains
schema:
type: string
example: gmail.com,googlemail.com
- name: tags
in: query
description: Filter by tags (comma-separated)
schema:
type: string
example: example_value
- name: group_by
in: query
description: Group by time period
schema:
type: string
enum:
- hour
- day
- week
- month
default: day
example: hour
security:
- BearerAuth:
- statistics-transactional:read:all
- statistics-transactional:read:{domain}
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: "package main\n\nimport (\n \"context\"\n \"fmt\"\n \"log\"\n \"time\"\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 fromTime := time.Now().Add(-time.Hour * 24 * 30)\n // Call the ping endpoint\n response, httpResp, err := client.StatisticsAPI.GetDeliveryTimeStatistics(\n ctx,\n accountID,\n requests.GetDeliveryTimeStatisticsParams{\n FromTime: &fromTime,\n SenderDomain: ahasend.String(\"example.com\"),\n RecipientDomains: ahasend.String(\"gmail.com\"),\n GroupBy: ahasend.String(\"week\"),\n },\n )\n if err != nil {\n log.Fatalf(\"Error getting delivery time statistics: %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(\"Delivery time statistics: %#v\\n\", response)\n }\n } else {\n fmt.Printf(\"❌ Unexpected status code: %d\\n\", httpResp.StatusCode)\n }\n}\n"
responses:
'200':
description: Delivery time statistics
content:
application/json:
schema:
$ref: '#/components/schemas/DeliveryTimeStatisticsResponse'
examples:
getDeliveryTimeStatistics200Example:
summary: Default getDeliveryTimeStatistics 200 response
x-microcks-default: true
value:
object: list
data:
- {}
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getDeliveryTimeStatistics400Example:
summary: Default getDeliveryTimeStatistics 400 response
x-microcks-default: true
value:
message: example_value
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getDeliveryTimeStatistics401Example:
summary: Default getDeliveryTimeStatistics 401 response
x-microcks-default: true
value:
message: example_value
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getDeliveryTimeStatistics403Example:
summary: Default getDeliveryTimeStatistics 403 response
x-microcks-default: true
value:
message: example_value
'429':
description: Too many requests (rate limited to 1 request per second)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getDeliveryTimeStatistics429Example:
summary: Default getDeliveryTimeStatistics 429 response
x-microcks-default: true
value:
message: example_value
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
getDeliveryTimeStatistics500Example:
summary: Default getDeliveryTimeStatistics 500 response
x-microcks-default: true
value:
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
DeliveryTime:
type: object
properties:
recipient_domain:
type: string
format: fqdn
description: The recipient domain
example: mail.example.com
delivery_time:
type: number
format: double
description: The average time from reception to delivery in seconds
example: 1.0
ErrorResponse:
type: object
required:
- message
properties:
message:
type: string
description: Error description
example: example_value
example:
message: Error message
DeliveryTimeStatisticsResponse:
type: object
required:
- object
- data
properties:
object:
type: string
enum:
- list
description: Object type identifier
example: list
data:
type: array
items:
$ref: '#/components/schemas/DeliveryTimeStatistics'
description: Array of delivery time statistics
example:
- from_timestamp: '2025-03-15T14:30:00Z'
to_timestamp: '2025-03-15T14:30:00Z'
avg_delivery_time: 1.0
delivered_count: 1
delivery_times:
- {}
BounceStatistics:
type: object
properties:
from_timestamp:
type: string
format: date-time
description: Start time of the statistics bucket
example: '2025-03-15T14:30:00Z'
to_timestamp:
type: string
format: date-time
description: End time of the statistics bucket
example: '2025-03-15T14:30:00Z'
bounces:
type: array
items:
$ref: '#/components/schemas/Bounce'
description: Bounce count per bounce classification
example:
- classification: example_value
count: 1
required:
- from_timestamp
- to_timestamp
- bounces
DeliverabilityStatistics:
type: object
properties:
from_timestamp:
type: string
format: date-time
description: Start time of the statistics bucket
example: '2025-03-15T14:30:00Z'
to_timestamp:
type: string
format: date-time
description: End time of the statistics bucket
example: '2025-03-15T14:30:00Z'
reception_count:
type: integer
description: Number of messages accepted for delivery
example: 1
delivered_count:
type: integer
description: Number of messages delivered
example: 1
deferred_count:
type: integer
description: Number of messages deferred
example: 1
bounced_count:
type: integer
description: Number of messages bounced
example: 1
failed_count:
type: integer
description: Number of messages failed
example: 1
suppressed_count:
type: integer
description: Number of messages suppressed
example: 1
opened_count:
type: integer
description: Number of messages opened at least once
example: 1
clicked_count:
type: integer
description: Number of messages that have at least one link in them clicked.
example: 1
required:
- from_timestamp
- to_timestamp
DeliverabilityStatisticsResponse:
type: object
required:
- object
- data
properties:
object:
type: string
enum:
- list
description: Object type identifier
example: list
data:
type: array
items:
$ref: '#/components/schemas/DeliverabilityStatistics'
description: Array of deliverability statistics
example:
- from_timestamp: '2025-03-15T14:30:00Z'
to_timestamp: '2025-03-15T14:30:00Z'
reception_count: 1
delivered_count: 1
deferred_count: 1
DeliveryTimeStatistics:
type: object
properties:
from_timestamp:
type: string
format: date-time
description: Start time of the statistics bucket
example: '2025-03-15T14:30:00Z'
to_timestamp:
type: string
format: date-time
description: End time of the statistics bucket
example: '2025-03-15T14:30:00Z'
avg_delivery_time:
type: number
format: double
description: Average delivery time in seconds
example: 1.0
delivered_count:
type: integer
description: Number of messages
example: 1
delivery_times:
type: array
items:
$ref: '#/components/schemas/DeliveryTime'
description: Delivery times per recipient domain
example:
- recipient_domain: mail.example.com
delivery_time: 1.0
required:
- from_timestamp
- to_timestamp
- avg_delivery_time
- delivered_count
BounceStatisticsResponse:
type: object
required:
- object
- data
properties:
object:
type: string
enum:
- list
description: Object type identifier
example: list
data:
type: array
items:
$ref: '#/components/schemas/BounceStatistics'
description: Array of bounce statistics
example:
- from_timestamp: '2025-03-15T14:30:00Z'
to_timestamp: '2025-03-15T14:30:00Z'
bounces:
- {}
Bounce:
type: object
properties:
classification:
type: string
description: Bounce classification
example: example_value
count:
type: integer
description: Number of bounces
example: 1
required:
- classification
- count
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: aha-sk-64-CHARACTER-RANDOM-STRING
description: API key for authentication