canonical: https://jentic.com/apis/ahasend.com/ahasend

# AhaSend API v2

Jentic publishes the only available OpenAPI specification for AhaSend API v2, keeping it validated and agent-ready. AhaSend is a transactional email platform; the v2 API exposes 41 endpoints for sending messages, managing sending domains and SMTP credentials, configuring webhooks and routes, handling suppressions, and reading transactional statistics. Authentication uses bearer API keys prefixed with aha-sk- and supports fine-grained scopes per resource (messages, domains, webhooks, suppressions). General endpoints allow 100 requests per second with 200 burst, while statistics endpoints are limited to 1 request per second.

## For AI agents

Send transactional emails, manage sending domains, configure webhooks and routes, and read delivery stats through a scoped bearer-token API.

## Scope

Does not handle SMS, push notifications, or marketing campaign authoring - use for transactional email send, suppression, and webhook configuration only.

## Capabilities

- Send transactional and conversational messages with full RFC822 fields and idempotency keys
- Create, verify, and delete sending domains tied to an account
- Issue and revoke scoped API keys for messages, domains, webhooks, and suppressions
- Configure webhooks to receive delivery, open, click, and bounce events
- Set up and remove inbound routes that forward parsed mail to your webhook
- Manage the suppression list to control bounces, complaints, and manual blocks
- Read transactional statistics scoped per account or per sending domain

## Use cases

### Transactional Email Sending

Backend services send transactional messages - receipts, password resets, notifications - through POST /v2/accounts/{account_id}/messages. Idempotency keys are supported via the Idempotency-Key header so retries do not duplicate sends, and timestamps follow RFC3339. The 100 req/sec general rate limit accommodates high-volume bursts without bespoke retry logic.

Example prompt: POST /v2/accounts/{account_id}/messages with from, to, subject, html_body, and an Idempotency-Key

### Domain and Credential Management

Operations teams script domain onboarding by creating a sending domain, retrieving DNS records to publish, and verifying once DNS is in place. The same flow can issue scoped SMTP credentials and API keys with resource-level scopes (e.g. messages:send:{domain}), keeping each integration's blast radius small. Old credentials are deleted via the matching endpoints when integrations are retired.

Example prompt: POST /v2/accounts/{account_id}/domains with the domain name, then call GET to fetch DNS records for verification

### Webhook and Route Orchestration

AhaSend webhooks deliver delivery, open, click, and bounce events to a customer endpoint, while routes forward inbound mail. Through POST /v2/accounts/{account_id}/webhooks an integration can subscribe a target URL with the event types of interest, and POST /v2/accounts/{account_id}/routes wires up inbound parsing for reply-handling features.

Example prompt: POST /v2/accounts/{account_id}/webhooks with target_url and selected event types

### Suppression and Compliance

Compliance teams keep the suppression list accurate by reading current entries, adding manual suppressions for legal or fraud reasons, and removing suppressions when an address has been re-confirmed. The /suppressions/all delete endpoint is destructive and intended only for full clears. Suppression scopes (suppressions:wipe) gate access to that risky operation.

Example prompt: GET /v2/accounts/{account_id}/suppressions then DELETE the entry for hello@example.com

### AI Agent Email Operations via Jentic

An agent built on Jentic can send transactional mail or manage suppressions in response to natural-language requests. Jentic stores the AhaSend bearer key (with whatever scopes you provision) in its vault and applies it at request time, so the agent never sees the raw aha-sk- value or has to reason about which scope is needed.

Example prompt: Use Jentic to search 'send a transactional email', execute POST /v2/accounts/{account_id}/messages with the message body

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v2/accounts/{account_id}/messages | Send a transactional message |
| GET | /v2/accounts/{account_id}/messages/{message_id} | Get a message by ID |
| DELETE | /v2/accounts/{account_id}/messages/{message_id}/cancel | Cancel a scheduled message |
| POST | /v2/accounts/{account_id}/domains | Create a sending domain |
| POST | /v2/accounts/{account_id}/webhooks | Create a webhook subscription |
| POST | /v2/accounts/{account_id}/routes | Create an inbound route |
| POST | /v2/accounts/{account_id}/suppressions | Create a suppression |
| POST | /v2/accounts/{account_id}/api-keys | Create a scoped API key |

## Key resources

- **Messages** — Send, list, retrieve, and cancel transactional messages
- **Domains** — Create, verify, and delete sending domains
- **API Keys** — Issue and revoke scoped API keys
- **SMTP Credentials** — Manage SMTP credentials per domain
- **Webhooks** — Subscribe to delivery, open, click, and bounce events
- **Routes** — Configure inbound mail forwarding rules
- **Suppressions** — Read, create, and remove suppression list entries
- **Statistics** — Transactional statistics per account or domain
- **Accounts** — Account info, members, and billing reads

## Why Jentic

- **Setup:** Wiring the AhaSend API v2 by hand means managing its aha-sk- bearer keys, threading the account_id through every path, and coding your own logic for transactional email and webhooks. Through Jentic you install once, import the AhaSend API v2 from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** AhaSend puts the account id in the URL path (/v2/accounts/{account_id}/...), so a rule can pin the agent to one account. You choose which operations it may call, such as sending a message, so cancelling messages or creating API keys is not included unless you add it.
- **Credential handling:** Your AhaSend bearer key is stored once, encrypted, by your own Jentic One instance and attached at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a transactional email' or 'create a webhook', and Jentic returns the matching AhaSend operation with its input schema, including the account_id path parameter, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **SendGrid Mail Send** — Twilio's transactional email platform with rich templates, webhooks, and analytics
- **Postmark** — Transactional email service known for fast delivery and clean separation of streams
- **Resend** — Modern transactional email API with simple per-email send and React templates
- **Mailjet** — Transactional and marketing email platform with both REST and SMTP delivery
- **SparkPost** — Transactional email platform with deep deliverability analytics

## FAQ

### Why is there no official OpenAPI spec for AhaSend API v2?

AhaSend publishes a YAML spec for documentation but Jentic generates and maintains the validated, bundled OpenAPI specification used here so that AI agents and developers can call the AhaSend API v2 via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the AhaSend API v2 use?

Bearer authentication using a 64-character API key prefixed with aha-sk- in the Authorization header. Keys carry scopes such as messages:send:{domain}, webhooks:write, and suppressions:wipe. Through Jentic, the key is held in the credential vault and injected at request time.

### What are the rate limits for the AhaSend API v2?

General API endpoints allow 100 requests per second with a burst of 200; statistics endpoints are limited to 1 request per second with a burst of 1. Plan polling and reporting jobs accordingly - pull stats on a schedule rather than per send.

### How do I send a transactional email through the AhaSend API v2?

POST /v2/accounts/{account_id}/messages with the from address, recipients, subject, and either html_body or text_body. Include an Idempotency-Key header to make retries safe. The response includes a message_id you can use with GET /v2/accounts/{account_id}/messages/{message_id} for status.

### How do I send transactional email through Jentic?

Search Jentic for 'send a transactional email'. Load the POST /v2/accounts/{account_id}/messages schema, supply the account ID, sender, recipient, subject, and body, and execute. Jentic injects the bearer key with the right scope and returns the message_id.

### Can I cancel a scheduled message before it sends?

Yes. Call DELETE /v2/accounts/{account_id}/messages/{message_id}/cancel before delivery starts. Once a message has been sent, cancellation no longer applies and the response will indicate the message is in a terminal state.

### Can I limit what my agent is allowed to do with the AhaSend API?

Yes. Because Jentic One is self-hosted, the rules you set on your own instance decide which AhaSend operations and credentials the agent may use. Since AhaSend puts the account ID in the URL path (/v2/accounts/{account_id}/...), you can pin the agent to a single account, and you choose the exact operations it can call, such as sending a message via POST /v2/accounts/{account_id}/messages. Operations like cancelling a message or creating a scoped API key stay off limits unless you explicitly grant them.