`, or the bare UUID portion.
schema:
type: string
security:
- BearerAuth: ["messages:cancel:all"]
- BearerAuth: ["messages:cancel:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// The Message-ID returned by Create Message, or its bare UUID.
response, _, err := client.MessagesAPI.CancelMessage(ctx, accountID, "<8b1f2e8c-5d6a-4c3b-9e7f-1a2b3c4d5e6f@example.com>")
if err != nil {
log.Fatalf("Error canceling message: %v", err)
}
fmt.Println(response.Message)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const messageId = "00000000-0000-4000-8000-000000000002";
const result = await client.messages.cancel(messageId);
console.log("Message cancellation requested.", { message: result.message });
responses:
'200':
description: Scheduled message is cancelled
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Message not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
# Template endpoints
/v2/accounts/{account_id}/templates:
get:
summary: List Templates
description: |
Returns a cursor-paginated list of the account's transactional
templates, newest first. Campaign designs are a different resource and
never appear here. Each template is listed without its `content`; Get
Template returns it.
A template with no design yet is listed like any other; whether it can
be sent is the send's answer, not this one.
operationId: listTemplates
tags:
- Templates
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: limit
in: query
description: Maximum number of items to return (1-100)
schema:
type: integer
minimum: 1
maximum: 100
default: 100
- name: after
in: query
description: Pagination cursor for the next page. Provide the value from `next_cursor` in the response.
schema:
type: string
- name: before
in: query
description: Pagination cursor for the previous page. Provide the value from `previous_cursor` in the response.
schema:
type: string
security:
- BearerAuth: ["templates:read"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
response, _, err := client.TemplatesAPI.GetTemplates(ctx, accountID, requests.GetTemplatesParams{
Limit: ahasend.Int32(100),
})
if err != nil {
log.Fatalf("Error listing templates: %v", err)
}
for _, template := range response.Data {
fmt.Printf("%s %s\n", template.ID, template.Name)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const page = await client.templates.list({ limit: 20 });
console.log("Templates listed.", { count: page.data.length });
responses:
'200':
description: Paginated templates
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedTemplatesResponse'
'400':
description: Invalid limit or cursor
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `templates:read` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
summary: Create Template
description: |
Creates a transactional template. Its fields go to its draft, as a
dashboard save does, so sends keep failing until it is published: pass
`publish: true` to publish it in the same request, or call Publish
Template.
`content.mjml` makes an `advanced` template and `content.html` an `html`
template. A template with neither must name its `editor`. The editor never
changes after create.
MJML is compiled in strict mode, and HTML must use full `https://` URLs
for its images and stylesheets: the API cannot upload files.
A create with `publish: true` and nothing to publish is refused and
creates nothing.
operationId: createTemplate
tags:
- Templates
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["templates:write"]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTemplateRequest'
responses:
'201':
description: Template created. The Template object is the published copy; `has_draft` says whether the request left a draft.
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
'400':
description: 'Invalid request: the body, a field, or a publish with nothing to publish. The message names the field and the problem.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `templates:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/common"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// HTML content makes an html template; MJML would make an advanced one.
// The text is made from the HTML when it is left out. Publish makes the
// template ready to send at once; without it, the fields stay in a draft.
response, _, err := client.TemplatesAPI.CreateTemplate(ctx, accountID, requests.CreateTemplateRequest{
Name: "Password reset",
Subject: ahasend.String("Reset your password, {{ first_name }}"),
From: &common.SenderAddress{
Email: "hello@yourdomain.com",
Name: ahasend.String("Example"),
},
Content: &requests.TemplateContentInput{
HTML: ahasend.String(`Hi {{ first_name }},
Reset your password
`),
},
Publish: true,
})
if err != nil {
log.Fatalf("Error creating template: %v", err)
}
fmt.Printf("Created %s template %s\n", response.Editor, response.ID)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const template = await client.templates.create({
name: "Welcome email",
subject: "Welcome, {{ first_name }}",
content: { html: "Hello {{ first_name }}, welcome aboard.
" },
publish: true,
});
console.log("Template created.", { id: template.id, editor: template.editor });
/v2/accounts/{account_id}/templates/{template_id}:
get:
summary: Get Template
description: |
Returns one of the account's transactional templates: its published
copy, which is what a send uses, with its content and the variable list
a send has to satisfy. `has_draft` says whether changes are waiting to
be published; Get Template Draft returns them. A campaign design's ID
is not addressable here and answers 404.
operationId: getTemplate
tags:
- Templates
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: template_id
in: path
required: true
description: Template ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["templates:read"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
templateID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
response, _, err := client.TemplatesAPI.GetTemplate(ctx, accountID, templateID)
if err != nil {
log.Fatalf("Error getting template: %v", err)
}
// A send from this template must supply every required variable.
for _, variable := range response.Variables {
fmt.Printf("%s required=%t\n", variable.Name, variable.Required)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const templateId = "00000000-0000-4000-8000-000000000009";
const template = await client.templates.get(templateId);
console.log("Template found.", { id: template.id, name: template.name });
responses:
'200':
description: Template
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
'400':
description: Invalid template_id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `templates:read` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Template not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
summary: Update Template
description: |
Changes a transactional template. Every field but `name` goes to the
template's draft, the same draft the dashboard edits, and sends use the
published copy until the draft is published: pass `publish: true`, or call
Publish Template. A publish publishes the whole draft, including changes
made in the dashboard. A draft that ends up equal to the published copy is
not kept, and a request that changes nothing changes nothing, so the same
request can be repeated safely.
`name` is not drafted: it changes when the request succeeds, as its last
step. A field the request leaves out is neither changed nor checked,
apart from a custom text kept beside a new design (see
`TemplateContentInput`).
When the template changes in the dashboard or through another request
while this one writes it, the request applies its fields again over the
new draft. It answers 503 when that keeps happening; retry it.
operationId: updateTemplate
tags:
- Templates
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: template_id
in: path
required: true
description: Template ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["templates:write"]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTemplateRequest'
responses:
'200':
description: Template updated. The Template object is the published copy; `has_draft` says whether a draft is left.
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
'400':
description: Invalid template_id, an invalid body or field, a request with no changes, or a publish with nothing to publish or a draft that cannot be rendered. The message names the field and the problem.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `templates:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Template not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
$ref: '#/components/responses/TemplateBeingChanged'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/common"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
templateID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
// Only the fields you set change. They go to the template's draft, the
// same draft the dashboard edits; Publish publishes the whole draft. An
// empty ReplyTo clears the reply-to address.
response, _, err := client.TemplatesAPI.UpdateTemplate(ctx, accountID, templateID, requests.UpdateTemplateRequest{
Subject: ahasend.String("Your password reset link"),
ReplyTo: &common.SenderAddress{},
Publish: true,
})
if err != nil {
log.Fatalf("Error updating template: %v", err)
}
fmt.Printf("Updated template %s, has draft: %t\n", response.Name, response.HasDraft)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const templateId = "00000000-0000-4000-8000-000000000009";
// Fields go to the template's draft; publish: true also publishes it.
const template = await client.templates.update(templateId, {
subject: "Welcome to the team, {{ first_name }}",
preheader: null,
publish: true,
});
console.log("Template updated.", { id: template.id, hasDraft: template.has_draft });
delete:
summary: Delete Template
description: |
Deletes a transactional template, as the dashboard does. Sends of it fail
from then on, and a second delete answers 404.
operationId: deleteTemplate
tags:
- Templates
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: template_id
in: path
required: true
description: Template ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["templates:delete"]
responses:
'200':
description: Template deleted
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Invalid template_id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `templates:delete` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Template not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
templateID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
response, _, err := client.TemplatesAPI.DeleteTemplate(ctx, accountID, templateID)
if err != nil {
log.Fatalf("Error deleting template: %v", err)
}
fmt.Println(response.Message)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const templateId = "00000000-0000-4000-8000-000000000009";
const result = await client.templates.delete(templateId);
console.log("Template deleted.", { message: result.message });
/v2/accounts/{account_id}/templates/{template_id}/draft:
get:
summary: Get Template Draft
description: |
Returns a template's draft: the changes saved in the dashboard or
through the API that are not published yet. Sends use the published
copy, which Get Template returns, until the draft is published.
A template with no draft answers 404 `template has no draft`; its
`has_draft` is false.
operationId: getTemplateDraft
tags:
- Templates
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: template_id
in: path
required: true
description: Template ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["templates:read"]
responses:
'200':
description: Template draft
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateDraft'
'400':
description: Invalid template_id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `templates:read` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Template not found (`template not found`), or the template has no draft (`template has no draft`)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
templateID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
// A template with no draft returns 404; its HasDraft is false.
response, _, err := client.TemplatesAPI.GetTemplateDraft(ctx, accountID, templateID)
if err != nil {
log.Fatalf("Error getting template draft: %v", err)
}
fmt.Printf("Draft subject: %s, changed at %s\n", response.Subject, response.UpdatedAt)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const templateId = "00000000-0000-4000-8000-000000000009";
const draft = await client.templates.getDraft(templateId);
console.log("Template draft found.", { templateId: draft.template_id, subject: draft.subject });
delete:
summary: Discard Template Draft
description: |
Discards a template's draft, the changes saved in the dashboard or through
the API that are not published yet. A template with no draft is answered
as it is, so the request can be repeated safely.
operationId: discardTemplateDraft
tags:
- Templates
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: template_id
in: path
required: true
description: Template ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["templates:write"]
responses:
'200':
description: The template, with `has_draft` false
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
'400':
description: Invalid template_id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `templates:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Template not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
$ref: '#/components/responses/TemplateBeingChanged'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
templateID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
response, _, err := client.TemplatesAPI.DiscardTemplateDraft(ctx, accountID, templateID)
if err != nil {
log.Fatalf("Error discarding template draft: %v", err)
}
fmt.Printf("Template %s has draft: %t\n", response.Name, response.HasDraft)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const templateId = "00000000-0000-4000-8000-000000000009";
const template = await client.templates.discardDraft(templateId);
console.log("Template draft discarded.", { id: template.id, hasDraft: template.has_draft });
/v2/accounts/{account_id}/templates/{template_id}/publish:
post:
summary: Publish Template
description: |
Publishes a template's draft, so sends use it, and keeps it as a new
version. The whole draft is published, including changes made in the
dashboard. A template with no draft has nothing to publish and is answered
as it is when its published copy has a body, so the request can be
repeated safely.
The operation takes no request body; one sent is ignored.
operationId: publishTemplate
tags:
- Templates
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: template_id
in: path
required: true
description: Template ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["templates:write"]
responses:
'200':
description: Template published
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
'400':
description: Invalid template_id, a template with nothing to publish (`template has no content to publish`), or a draft whose design holds a `{{`, `{%` or `{#` that cannot be rendered
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `templates:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Template not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
$ref: '#/components/responses/TemplateBeingChanged'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
templateID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
// The whole draft is published, including changes made in the dashboard.
// The SDK sends a fresh Idempotency-Key with this POST and reuses it on
// its own retries.
response, _, err := client.TemplatesAPI.PublishTemplate(ctx, accountID, templateID)
if err != nil {
log.Fatalf("Error publishing template: %v", err)
}
fmt.Printf("Published template %s\n", response.Name)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const templateId = "00000000-0000-4000-8000-000000000009";
const template = await client.templates.publish(templateId);
console.log("Template published.", { id: template.id, hasDraft: template.has_draft });
/v2/accounts/{account_id}/templates/{template_id}/versions:
get:
summary: List Template Versions
description: |
Returns a template's published versions, newest first, without their
content. Every publish of a draft makes a version. A template keeps its
50 most recent versions, so the list is not paginated. Get Template
Version returns one version with its content.
operationId: listTemplateVersions
tags:
- Templates
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: template_id
in: path
required: true
description: Template ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["templates:read"]
responses:
'200':
description: Template versions
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateVersionsResponse'
'400':
description: Invalid template_id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `templates:read` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Template not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
templateID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
// Versions come newest first, at most 50, with no pagination.
response, _, err := client.TemplatesAPI.GetTemplateVersions(ctx, accountID, templateID)
if err != nil {
log.Fatalf("Error listing template versions: %v", err)
}
for _, version := range response.Data {
publisher := "unknown"
if version.PublishedBy != nil {
publisher = version.PublishedBy.Type + " " + version.PublishedBy.ID.String()
}
fmt.Printf("v%d %s published by %s\n", version.Version, version.PublishedAt, publisher)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const templateId = "00000000-0000-4000-8000-000000000009";
const versions = await client.templates.listVersions(templateId);
console.log("Template versions listed.", { count: versions.data.length });
/v2/accounts/{account_id}/templates/{template_id}/versions/{version_id}:
get:
summary: Get Template Version
description: |
Returns one published version of a template with its content.
operationId: getTemplateVersion
tags:
- Templates
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: template_id
in: path
required: true
description: Template ID
schema:
type: string
format: uuid
- name: version_id
in: path
required: true
description: Version ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["templates:read"]
responses:
'200':
description: Template version
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateVersionDetail'
'400':
description: Invalid template_id or version_id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `templates:read` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Template not found (`template not found`), or version not found (`template version not found`), also for a version of another template
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
templateID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
versionID := uuid.MustParse("22222222-2222-4222-8222-222222222222")
response, _, err := client.TemplatesAPI.GetTemplateVersion(ctx, accountID, templateID, versionID)
if err != nil {
log.Fatalf("Error getting template version: %v", err)
}
fmt.Printf("v%d subject: %s\n", response.Version, response.Subject)
if response.Content != nil {
fmt.Println(response.Content.Text)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const templateId = "00000000-0000-4000-8000-000000000009";
const versionId = "00000000-0000-4000-8000-000000000012";
const version = await client.templates.getVersion(templateId, versionId);
console.log("Template version found.", { id: version.id, version: version.version });
/v2/accounts/{account_id}/templates/{template_id}/versions/{version_id}/restore:
post:
summary: Restore Template Version
description: |
Restores a published version into the template's draft. With
`publish: true` the draft is then published, as Publish Template does;
a version the publish checks refuse is refused before the restore, and
the draft is left as it was.
operationId: restoreTemplateVersion
tags:
- Templates
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: template_id
in: path
required: true
description: Template ID
schema:
type: string
format: uuid
- name: version_id
in: path
required: true
description: Version ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["templates:write"]
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/RestoreTemplateVersionRequest'
responses:
'200':
description: Version restored. The Template object is the published copy; `has_draft` says whether a draft is left.
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
'400':
description: Invalid template_id or version_id, an invalid body, or a publish the publish checks refuse
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `templates:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Template not found (`template not found`), or version not found (`template version not found`), also for a version of another template
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
$ref: '#/components/responses/TemplateBeingChanged'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
templateID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
versionID := uuid.MustParse("22222222-2222-4222-8222-222222222222")
// The version goes into the draft; Publish then publishes it, so sends use
// it again.
response, _, err := client.TemplatesAPI.RestoreTemplateVersion(ctx, accountID, templateID, versionID, requests.RestoreTemplateVersionRequest{
Publish: true,
})
if err != nil {
log.Fatalf("Error restoring template version: %v", err)
}
fmt.Printf("Restored template %s, has draft: %t\n", response.Name, response.HasDraft)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const templateId = "00000000-0000-4000-8000-000000000009";
const versionId = "00000000-0000-4000-8000-000000000012";
const template = await client.templates.restoreVersion(templateId, versionId, { publish: true });
console.log("Template version restored.", { id: template.id, hasDraft: template.has_draft });
# Campaign template endpoints
/v2/accounts/{account_id}/campaign-templates:
get:
summary: List Campaign Templates
description: |
Returns a cursor-paginated list of the account's campaign templates,
newest first. Transactional templates are a different resource and
never appear here. Each campaign template is listed without its
`content`; Get Campaign Template returns it.
operationId: listCampaignTemplates
tags:
- Campaign Templates
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: limit
in: query
description: Maximum number of items to return (1-100)
schema:
type: integer
minimum: 1
maximum: 100
default: 100
- name: after
in: query
description: Pagination cursor for the next page. Provide the value from `next_cursor` in the response.
schema:
type: string
- name: before
in: query
description: Pagination cursor for the previous page. Provide the value from `previous_cursor` in the response.
schema:
type: string
security:
- BearerAuth: ["templates:read"]
responses:
'200':
description: Paginated campaign templates
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedCampaignTemplatesResponse'
'400':
description: Invalid limit or cursor
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `templates:read` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// Campaign templates are listed without their content; Get Campaign
// Template returns it.
response, _, err := client.CampaignTemplatesAPI.ListCampaignTemplates(ctx, accountID, requests.ListCampaignTemplatesParams{
Limit: ahasend.Int32(100),
})
if err != nil {
log.Fatalf("Error listing campaign templates: %v", err)
}
for _, template := range response.Data {
fmt.Printf("%s %s (%s)\n", template.ID, template.Name, template.Editor)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const page = await client.campaignTemplates.list({ limit: 20 });
console.log("Campaign templates listed.", { count: page.data.length });
post:
summary: Create Campaign Template
description: |
Creates a campaign template. A campaign template has no draft: what
the request sets is what a campaign made from the template copies.
`content.mjml` makes an `advanced` campaign template and
`content.html` an `html` one. A campaign template with neither must
name its `editor`; without `content` it is created with an empty
design, which the dashboard's editor opens. The editor never changes
after create.
MJML is compiled in strict mode, and HTML must use full `https://`
URLs for its images and stylesheets: the API cannot upload files.
operationId: createCampaignTemplate
tags:
- Campaign Templates
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["templates:write"]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCampaignTemplateRequest'
responses:
'201':
description: Campaign template created
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignTemplate'
'400':
description: 'Invalid request: the body or a field. The message names the field and the problem.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `templates:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// HTML content makes an html campaign template; MJML would make an
// advanced one. The text is made from the HTML when it is left out.
response, _, err := client.CampaignTemplatesAPI.CreateCampaignTemplate(ctx, accountID, requests.CreateCampaignTemplateRequest{
Name: "Monthly newsletter",
Content: &requests.TemplateContentInput{
HTML: ahasend.String(`Hi {{ first_name }},
Here is our news.
Unsubscribe
`),
},
})
if err != nil {
log.Fatalf("Error creating campaign template: %v", err)
}
fmt.Printf("Created %s campaign template %s\n", response.Editor, response.ID)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const template = await client.campaignTemplates.create({
name: "Monthly newsletter",
content: {
html: 'Hello {{ first_name }}.
Unsubscribe
',
},
});
console.log("Campaign template created.", { id: template.id, editor: template.editor });
/v2/accounts/{account_id}/campaign-templates/{template_id}:
get:
summary: Get Campaign Template
description: |
Returns one of the account's campaign templates with its content. A
transactional template's ID is not addressable here and answers 404.
operationId: getCampaignTemplate
tags:
- Campaign Templates
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: template_id
in: path
required: true
description: Campaign template ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["templates:read"]
responses:
'200':
description: Campaign template
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignTemplate'
'400':
description: Invalid template_id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `templates:read` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Campaign template not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
templateID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
response, _, err := client.CampaignTemplatesAPI.GetCampaignTemplate(ctx, accountID, templateID)
if err != nil {
log.Fatalf("Error getting campaign template: %v", err)
}
// A campaign can be made from the template only once it has HTML.
hasHTML := response.Content != nil && response.Content.HTML != ""
fmt.Printf("%s (%s), has HTML: %t\n", response.Name, response.Editor, hasHTML)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const templateId = "00000000-0000-4000-8000-000000000013";
const template = await client.campaignTemplates.get(templateId);
console.log("Campaign template found.", { id: template.id, name: template.name });
put:
summary: Update Campaign Template
description: |
Changes a campaign template's name, its content, or both. A field the
request leaves out is neither changed nor checked. The change applies
at once; campaigns already made from the template keep their own
copies. A name or content equal to the stored one changes nothing, so
the same request can be repeated safely. The editor never changes.
The design of a `simple` campaign template can be changed only in the
dashboard: send only `content.text` for one. A design saved later in
the dashboard, also from an editor opened before this request,
replaces the design this request wrote.
operationId: updateCampaignTemplate
tags:
- Campaign Templates
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: template_id
in: path
required: true
description: Campaign template ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["templates:write"]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCampaignTemplateRequest'
responses:
'200':
description: Campaign template updated
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignTemplate'
'400':
description: Invalid template_id, an invalid body or field, or a request with no changes. The message names the field and the problem.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `templates:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Campaign template not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
templateID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
// Only the fields you set change, at once. Campaigns already made from
// the template keep their own copies.
response, _, err := client.CampaignTemplatesAPI.UpdateCampaignTemplate(ctx, accountID, templateID, requests.UpdateCampaignTemplateRequest{
Name: ahasend.String("Monthly newsletter, 2026"),
})
if err != nil {
log.Fatalf("Error updating campaign template: %v", err)
}
fmt.Printf("Updated campaign template %s\n", response.Name)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const templateId = "00000000-0000-4000-8000-000000000013";
// Campaigns already made from the template keep their own copies.
const template = await client.campaignTemplates.update(templateId, {
name: "Monthly newsletter (2026)",
});
console.log("Campaign template updated.", { id: template.id, name: template.name });
delete:
summary: Delete Campaign Template
description: |
Deletes a campaign template, as the dashboard does. Campaigns made
from it keep their own copies, and a second delete answers 404.
operationId: deleteCampaignTemplate
tags:
- Campaign Templates
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: template_id
in: path
required: true
description: Campaign template ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["templates:delete"]
responses:
'200':
description: Campaign template deleted
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Invalid template_id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `templates:delete` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Campaign template not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
templateID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
// Campaigns made from the template keep their own copies.
response, _, err := client.CampaignTemplatesAPI.DeleteCampaignTemplate(ctx, accountID, templateID)
if err != nil {
log.Fatalf("Error deleting campaign template: %v", err)
}
fmt.Println(response.Message)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const templateId = "00000000-0000-4000-8000-000000000013";
const result = await client.campaignTemplates.delete(templateId);
console.log("Campaign template deleted.", { message: result.message });
/v2/accounts/{account_id}/campaigns:
get:
summary: List Campaigns
description: |
Returns a cursor-paginated list of the account's marketing campaigns,
newest first. Each campaign is listed without its lists, content and
issues; Get Campaign returns them.
operationId: listCampaigns
tags:
- Campaigns
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: status
in: query
description: Only campaigns in this status.
schema:
$ref: '#/components/schemas/CampaignStatus'
- name: limit
in: query
description: Maximum number of items to return (1-100)
schema:
type: integer
minimum: 1
maximum: 100
default: 100
- name: after
in: query
description: Pagination cursor for the next page. Provide the value from `next_cursor` in the response.
schema:
type: string
- name: before
in: query
description: Pagination cursor for the previous page. Provide the value from `previous_cursor` in the response.
schema:
type: string
security:
- BearerAuth: ["campaigns:read"]
responses:
'200':
description: Paginated campaigns
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedCampaignsResponse'
'400':
description: Invalid status, limit or cursor
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `campaigns:read` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/common"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// Leave Status nil to list campaigns in every status.
response, _, err := client.CampaignsAPI.ListCampaigns(ctx, accountID, requests.ListCampaignsParams{
Status: ahasend.String(common.CampaignStatusScheduled),
Limit: ahasend.Int32(100),
})
if err != nil {
log.Fatalf("Error listing campaigns: %v", err)
}
for _, campaign := range response.Data {
if campaign.SendAt != nil {
fmt.Printf("%s %s sends at %s\n", campaign.ID, campaign.Name, campaign.SendAt)
}
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const page = await client.campaigns.list({ status: "draft", limit: 20 });
console.log("Campaigns listed.", { count: page.data.length });
post:
summary: Create Campaign
description: |
Creates a draft marketing campaign. Every field but `name` is
optional and can be set later with Update Campaign; the campaign
answers its `issues` until it is ready to send.
The design comes from `content` (`content.mjml` makes an `advanced`
design and `content.html` an `html` one), from an `editor` alone (an
empty design the dashboard's editor opens), or from a campaign
template named by `template_id`, which the campaign copies. MJML is
compiled in strict mode, and HTML must use full `https://` URLs for
its images and stylesheets: the API cannot upload files.
The subject, preview text, sender and reply-to are checked by the
rules of the dashboard, and their refusals use the dashboard's
sentences.
operationId: createCampaign
tags:
- Campaigns
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["campaigns:write"]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCampaignRequest'
responses:
'201':
description: Campaign created
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'400':
description: 'Invalid request: the body or a field, a list or campaign template that does not exist. The message names the field and the problem.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `campaigns:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/common"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
listID := uuid.MustParse("22222222-2222-4222-8222-222222222222")
templateID := uuid.MustParse("33333333-3333-4333-8333-333333333333")
// The campaign copies the campaign template's design; later changes to
// the template do not reach it. Every field but Name can be set later.
response, _, err := client.CampaignsAPI.CreateCampaign(ctx, accountID, requests.CreateCampaignRequest{
Name: "October newsletter",
Subject: ahasend.String("Our news for October, {{ first_name }}"),
Preheader: ahasend.String("Three things we shipped this month"),
From: &common.SenderAddress{
Email: "news@yourdomain.com",
Name: ahasend.String("Example"),
},
ListIDs: []uuid.UUID{listID},
TemplateID: &templateID,
})
if err != nil {
log.Fatalf("Error creating campaign: %v", err)
}
fmt.Printf("Created campaign %s, ready: %t\n", response.ID, response.Ready != nil && *response.Ready)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const campaign = await client.campaigns.create({
name: "October newsletter",
subject: "What is new in October",
preheader: "Three things we shipped this month",
from: { email: "news@example.com", name: "Example" },
list_ids: ["00000000-0000-4000-8000-000000000010"],
template_id: "00000000-0000-4000-8000-000000000013",
});
console.log("Campaign created.", { id: campaign.id, ready: campaign.ready });
/v2/accounts/{account_id}/campaigns/{campaign_id}:
get:
summary: Get Campaign
description: |
Returns one of the account's campaigns with its lists, its content
and, for a draft, the issues that keep it from being sent.
operationId: getCampaign
tags:
- Campaigns
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: campaign_id
in: path
required: true
description: Campaign ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["campaigns:read"]
responses:
'200':
description: Campaign
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'400':
description: Invalid campaign_id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `campaigns:read` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
campaignID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
response, _, err := client.CampaignsAPI.GetCampaign(ctx, accountID, campaignID)
if err != nil {
log.Fatalf("Error getting campaign: %v", err)
}
fmt.Printf("%s is %s, sending to %d lists\n", response.Name, response.Status, len(response.ListIDs))
// A draft lists what keeps it from being sent.
for _, issue := range response.Issues {
fmt.Printf("%s: %s\n", issue.Code, issue.Message)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const campaignId = "00000000-0000-4000-8000-000000000014";
const campaign = await client.campaigns.get(campaignId);
console.log("Campaign found.", { id: campaign.id, status: campaign.status, ready: campaign.ready });
put:
summary: Update Campaign
description: |
Changes a draft campaign. A field the request leaves out is neither
changed nor checked, and `null` clears `subject`, `preheader`, `from`
and `reply_to`. A campaign that is not a draft cannot be changed.
The change waits for any other change of the same campaign, from the
dashboard or the API, and a send that starts after it reads it. The
design of a `simple` campaign can be changed only in the dashboard:
send only `content.text` for one. Between this request and a
dashboard editor open on the same campaign, the later design save
wins.
operationId: updateCampaign
tags:
- Campaigns
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: campaign_id
in: path
required: true
description: Campaign ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["campaigns:write"]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCampaignRequest'
responses:
'200':
description: Campaign updated
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'400':
description: Invalid campaign_id, an invalid body or field, a list that does not exist, or a request with no changes. The message names the field and the problem.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `campaigns:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/CampaignConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
campaignID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
// Only the fields you set change, and only while the campaign is a
// draft. A ReplyTo that points at "" clears the reply-to address.
response, _, err := client.CampaignsAPI.UpdateCampaign(ctx, accountID, campaignID, requests.UpdateCampaignRequest{
Subject: ahasend.String("Our news for October"),
ReplyTo: ahasend.String(""),
})
if err != nil {
log.Fatalf("Error updating campaign: %v", err)
}
fmt.Printf("Updated campaign %s, %d issues left\n", response.Name, len(response.Issues))
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const campaignId = "00000000-0000-4000-8000-000000000014";
// Only a draft can change; null clears the reply-to address.
const campaign = await client.campaigns.update(campaignId, {
subject: "What we shipped in October",
reply_to: null,
});
console.log("Campaign updated.", { id: campaign.id, ready: campaign.ready });
delete:
summary: Delete Campaign
description: |
Deletes a draft campaign with its design and its list choices. A
campaign that is not a draft cannot be deleted, and a second delete
answers 404.
operationId: deleteCampaign
tags:
- Campaigns
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: campaign_id
in: path
required: true
description: Campaign ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["campaigns:delete"]
responses:
'200':
description: Campaign deleted
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Invalid campaign_id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `campaigns:delete` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: The campaign is not a draft
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
campaignID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
// Only a draft can be deleted.
response, _, err := client.CampaignsAPI.DeleteCampaign(ctx, accountID, campaignID)
if err != nil {
log.Fatalf("Error deleting campaign: %v", err)
}
fmt.Println(response.Message)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const campaignId = "00000000-0000-4000-8000-000000000014";
const result = await client.campaigns.delete(campaignId);
console.log("Campaign deleted.", { message: result.message });
/v2/accounts/{account_id}/campaigns/{campaign_id}/duplicate:
post:
summary: Duplicate Campaign
description: |
Makes a new draft from a campaign in any status: a copy of its
design, its subject, preview text, sender and reply-to address, and
its lists that still exist, in the same order. The copy's design is
its own.
operationId: duplicateCampaign
tags:
- Campaigns
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: campaign_id
in: path
required: true
description: Campaign ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["campaigns:write"]
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/DuplicateCampaignRequest'
responses:
'201':
description: Campaign duplicated
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'400':
description: Invalid campaign_id, or an invalid body or name
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `campaigns:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
campaignID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
// The copy is a new draft. Leave Name nil to name it "Copy of" and the
// source's name.
response, _, err := client.CampaignsAPI.DuplicateCampaign(ctx, accountID, campaignID, requests.DuplicateCampaignRequest{
Name: ahasend.String("November newsletter"),
})
if err != nil {
log.Fatalf("Error duplicating campaign: %v", err)
}
fmt.Printf("Created draft %s %s\n", response.ID, response.Name)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const campaignId = "00000000-0000-4000-8000-000000000014";
const copy = await client.campaigns.duplicate(campaignId, { name: "November newsletter" });
console.log("Campaign duplicated.", { id: copy.id, status: copy.status });
/v2/accounts/{account_id}/campaigns/{campaign_id}/send:
post:
summary: Send Campaign
description: |
Sends a draft campaign now, or at `send_at`. A campaign with any
issue is refused with the issues. The send then checks what would
stop the campaign at its send time: its sender domain must still be
verified and not paused, the account must be able to send, and its
lists must have subscribed contacts. For a send at a later time, a
block that a payment or the next billing period can clear is a
warning instead of a refusal.
The campaign moves to `validating` and goes through the same list
validation and review as a send from the dashboard, which move it on
from there. Read `status` and `status_reason` with Get Campaign. To
change the send time, unschedule the campaign and send it again.
operationId: sendCampaign
tags:
- Campaigns
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: campaign_id
in: path
required: true
description: Campaign ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["campaigns:send"]
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/SendCampaignRequest'
responses:
'202':
description: The send was accepted. The campaign is in `validating`, as the send left it.
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignSend'
'400':
description: Invalid campaign_id, an invalid body or `send_at`, a campaign with issues (with `issues`), or a check of the send that failed. The message says what to fix, in the dashboard's words for the checks the dashboard shares.
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignNotReady'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `campaigns:send` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/CampaignConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"time"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
campaignID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
// Leave SendAt nil to send now.
response, _, err := client.CampaignsAPI.SendCampaign(ctx, accountID, campaignID, requests.SendCampaignRequest{
SendAt: ahasend.Time(time.Now().Add(24 * time.Hour)),
})
if notReady, ok := api.AsCampaignNotReady(err); ok {
for _, issue := range notReady.Issues {
fmt.Printf("%s: %s\n", issue.Code, issue.Message)
}
os.Exit(1)
}
if err != nil {
log.Fatalf("Error sending campaign: %v", err)
}
fmt.Printf("Campaign %s is %s\n", response.ID, response.Status)
for _, warning := range response.Warnings {
fmt.Println("Warning:", warning)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const campaignId = "00000000-0000-4000-8000-000000000014";
// Leave send_at out to send now. The campaign is checked before it sends.
const campaign = await client.campaigns.send(campaignId, { send_at: "2030-01-01T09:00:00Z" });
console.log("Campaign send accepted.", { status: campaign.status, warnings: campaign.warnings });
/v2/accounts/{account_id}/campaigns/{campaign_id}/unschedule:
post:
summary: Unschedule Campaign
description: |
Returns a `validating` or `scheduled` campaign to `draft`: it cancels
the list validation that runs, or the scheduled send. A campaign that
has queued mail, or that is in any other status, cannot be
unscheduled. The request takes no body.
operationId: unscheduleCampaign
tags:
- Campaigns
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: campaign_id
in: path
required: true
description: Campaign ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["campaigns:send"]
responses:
'200':
description: The campaign, back in `draft`
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'400':
description: Invalid campaign_id, or a body that is not an empty JSON object
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `campaigns:send` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/CampaignConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
campaignID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
// A validating or scheduled campaign goes back to draft. To change the
// send time, unschedule it and send it again.
response, _, err := client.CampaignsAPI.UnscheduleCampaign(ctx, accountID, campaignID)
if err != nil {
log.Fatalf("Error unscheduling campaign: %v", err)
}
fmt.Printf("Campaign %s is %s\n", response.ID, response.Status)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const campaignId = "00000000-0000-4000-8000-000000000014";
const campaign = await client.campaigns.unschedule(campaignId);
console.log("Campaign unscheduled.", { id: campaign.id, status: campaign.status });
/v2/accounts/{account_id}/campaigns/{campaign_id}/test:
post:
summary: Test Campaign
description: |
Sends a test of a draft campaign to up to 5 addresses. Each address
gets the design with placeholders for the contact's fields; its
links lead to a contact that does not exist. A campaign with any
issue but `unsubscribe_link_missing` is refused with the issues.
An account can send 50 test emails per day (UTC), counted per
address, from the API and the dashboard together. An address the
mail server refused still counts; a test that sent nothing (502)
does not.
With an `Idempotency-Key`, a 2xx answer is stored and replayed, so a
retry with the same key sends nothing again. Unlike other
operations, a 4xx answer is not stored: it releases the key, so a
retry with the same key, for example after the daily limit resets,
is answered afresh.
operationId: testCampaign
tags:
- Campaigns
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: campaign_id
in: path
required: true
description: Campaign ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["campaigns:send"]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TestCampaignRequest'
responses:
'200':
description: What the test send did. With `result_unknown`, the test may have gone out.
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignTest'
'400':
description: Invalid campaign_id, an invalid body or address, no address or more than 5, a campaign with issues (with `issues`), a sender domain that is paused or no longer verified, or an account that cannot send
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignNotReady'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `campaigns:send` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/CampaignConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'429':
description: Too many requests, or the account's daily limit of 50 test emails is reached (`daily test send limit reached`). Neither is stored, so a retry may use the same `Idempotency-Key`.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'502':
description: The mail server could not take the test, and nothing was sent. Retry, with the same `Idempotency-Key` if you sent one.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
campaignID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
response, _, err := client.CampaignsAPI.TestCampaign(ctx, accountID, campaignID, requests.TestCampaignRequest{
To: []string{"Ann ", "bob@yourdomain.com"},
})
if err != nil {
log.Fatalf("Error sending test: %v", err)
}
if response.ResultUnknown {
fmt.Println("The test may have gone out; check the inboxes before you send another")
return
}
fmt.Printf("Sent to %v\n", response.SentTo)
for _, failure := range response.Failed {
fmt.Printf("Refused %s: %s\n", failure.Email, failure.Message)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const campaignId = "00000000-0000-4000-8000-000000000014";
const result = await client.campaigns.test(campaignId, { to: ["reviewer@example.com"] });
console.log("Campaign test sent.", {
sentTo: result.sent_to,
failed: result.failed.length,
resultUnknown: result.result_unknown,
});
/v2/accounts/{account_id}/campaigns/{campaign_id}/stats:
get:
summary: Get Campaign Stats
description: |
Returns the numbers of a campaign: its live counters, its stored
report and the rates from both, the numbers the dashboard's report
shows. The stored report is recounted from time to time; a request
that finds it missing or old asks for a recount and answers what is
stored.
operationId: getCampaignStats
tags:
- Campaigns
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: campaign_id
in: path
required: true
description: Campaign ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["campaigns:read"]
responses:
'200':
description: Campaign stats
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignStats'
'400':
description: Invalid campaign_id
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `campaigns:read` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
campaignID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
response, _, err := client.CampaignsAPI.GetCampaignStats(ctx, accountID, campaignID)
if err != nil {
log.Fatalf("Error getting campaign stats: %v", err)
}
fmt.Printf("Delivered %d of %d\n", response.Delivered, response.Recipients)
// A rate is nil until the report is counted and its base is not zero.
if response.Rates.OpenRate != nil {
fmt.Printf("Open rate: %.2f%%\n", *response.Rates.OpenRate)
}
if response.Report != nil {
for status, count := range response.Report.ByStatus {
fmt.Printf("%s: %d\n", status, count)
}
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const campaignId = "00000000-0000-4000-8000-000000000014";
const stats = await client.campaigns.getStats(campaignId);
console.log("Campaign stats loaded.", { delivered: stats.delivered, rates: stats.rates });
/v2/accounts/{account_id}/campaigns/{campaign_id}/recipients:
get:
summary: List Campaign Recipients
description: |
Returns a cursor-paginated list of a campaign's recipients in one
status or with one bounce classification, by contact ID, the highest
first. Send exactly one of `status` and `bounce_classification`.
operationId: listCampaignRecipients
tags:
- Campaigns
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: campaign_id
in: path
required: true
description: Campaign ID
schema:
type: string
format: uuid
- name: status
in: query
description: A status as a key of the stats' `by_status` names it, such as `Queued`, `Delivered` or `Administratively Bounced`.
schema:
type: string
minLength: 1
maxLength: 64
- name: bounce_classification
in: query
description: A key of the stats' `by_bounce_classification`, except `Unknown`, which has no recipient page.
schema:
type: string
minLength: 1
maxLength: 255
- name: limit
in: query
description: Maximum number of items to return (1-100)
schema:
type: integer
minimum: 1
maximum: 100
default: 100
- name: after
in: query
description: Pagination cursor for the next page. Provide the value from `next_cursor` in the response.
schema:
type: string
- name: before
in: query
description: Pagination cursor for the previous page. Provide the value from `previous_cursor` in the response. An empty page past the last recipient has no `previous_cursor`; read the first page with no cursor.
schema:
type: string
security:
- BearerAuth: ["campaigns:read"]
responses:
'200':
description: Paginated campaign recipients
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedCampaignRecipientsResponse'
'400':
description: Invalid campaign_id, filter, limit or cursor
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `campaigns:read` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
campaignID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
// Set exactly one of Status and BounceClassification, each a key of the
// campaign's stats report.
response, _, err := client.CampaignsAPI.ListCampaignRecipients(ctx, accountID, campaignID, requests.ListCampaignRecipientsParams{
Status: ahasend.String("Bounced"),
Limit: ahasend.Int32(100),
})
if err != nil {
log.Fatalf("Error listing campaign recipients: %v", err)
}
for _, recipient := range response.Data {
reason := ""
if recipient.BounceReason != nil {
reason = *recipient.BounceReason
}
fmt.Printf("%s (%s) %s\n", recipient.Email, recipient.ListName, reason)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const campaignId = "00000000-0000-4000-8000-000000000014";
// Send exactly one of status and bounce_classification.
const page = await client.campaigns.recipients.list(campaignId, { status: "Delivered", limit: 20 });
console.log("Campaign recipients listed.", { count: page.data.length });
# Account endpoints
/v2/accounts/{account_id}:
get:
summary: 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
security:
- BearerAuth: ["accounts:read"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
response, _, err := client.AccountsAPI.GetAccount(ctx, accountID)
if err != nil {
log.Fatalf("Error getting account: %v", err)
}
fmt.Printf("%s %s\n", response.ID, response.Name)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const account = await client.accounts.get();
console.log("Account found.", { id: account.id, name: account.name });
responses:
'200':
description: Account details
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Account not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
summary: Update Account
description: |
Updates account settings
**Validation Requirements:**
- `name` must be maximum 255 characters
- `website` must be a domain such as `acme.com`, or an http(s) URL such as `https://acme.com`; it is stored as the host, so `https://acme.com/team` is read back as `acme.com`. Maximum 255 characters
- `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
security:
- BearerAuth: ["accounts:write"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// Update the account name and open/click tracking settings
response, _, err := client.AccountsAPI.UpdateAccount(ctx, accountID, requests.UpdateAccountRequest{
Name: ahasend.String("Acme Corp"),
TrackOpens: ahasend.Bool(true),
TrackClicks: ahasend.Bool(true),
})
if err != nil {
log.Fatalf("Error updating account: %v", err)
}
fmt.Printf("Updated account %s\n", response.Name)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const account = await client.accounts.update({ name: "Example, Inc." });
console.log("Account updated.", { id: account.id, name: account.name });
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'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Account not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/members:
get:
summary: 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
security:
- BearerAuth: ["accounts:members:read"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
response, _, err := client.AccountsAPI.GetAccountMembers(ctx, accountID)
if err != nil {
log.Fatalf("Error listing account members: %v", err)
}
for _, member := range response.Data {
fmt.Printf("%s %s\n", member.UserID, member.Role)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const members = await client.accounts.listMembers();
console.log("Account members listed.", { count: members.data.length });
responses:
'200':
description: List of account members
content:
application/json:
schema:
$ref: '#/components/schemas/AccountMembersResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
summary: 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
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["accounts:members:add"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// The SDK sends a fresh Idempotency-Key with this POST and reuses it on
// its own retries, so a retried request is not applied twice.
response, _, err := client.AccountsAPI.AddAccountMember(ctx, accountID, requests.AddMemberRequest{
Email: "teammate@example.com",
Name: ahasend.String("Jordan Lee"),
Role: "Developer",
})
if err != nil {
log.Fatalf("Error adding account member: %v", err)
}
fmt.Printf("Added user %s as %s\n", response.UserID, response.Role)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const member = await client.accounts.addMember({
email: "developer@example.com",
role: "Developer",
});
console.log("Account member added.", { userId: member.user_id, role: member.role });
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddMemberRequest'
responses:
'201':
description: Member added successfully
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/UserAccount'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: |
Either the user is already a member of the account or the idempotency-key
execution is in progress. The in-progress case is identified only
by `Idempotent-Replayed: false` plus a positive integer
`Retry-After`. A new duplicate-member response has neither
header; a stored replay of that response has
`Idempotent-Replayed: true`. The message is not a stable
discriminator.
headers:
Idempotent-Replayed:
description: |
`false` with a positive `Retry-After` means an execution is in
progress. `true` means a stored duplicate-member 409 was
replayed. Absent means a fresh duplicate-member conflict.
schema:
type: string
enum: ['true', 'false']
Retry-After:
$ref: '#/components/headers/IdempotencyRetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/members/{user_id}:
delete:
summary: 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
- name: user_id
in: path
required: true
description: User ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["accounts:members:remove"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
userID := uuid.MustParse("5b9a1c1e-8f7d-4a55-9d0e-2c1f3b7a6e42")
response, _, err := client.AccountsAPI.RemoveAccountMember(ctx, accountID, userID)
if err != nil {
log.Fatalf("Error removing account member: %v", err)
}
fmt.Println(response.Message)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const userId = "00000000-0000-4000-8000-000000000003";
const result = await client.accounts.removeMember(userId);
console.log("Account member removed.", { message: result.message });
responses:
'200':
description: Member removed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Member not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
# Sub-account endpoints
/v2/accounts/{account_id}/sub-accounts:
get:
summary: List Sub Accounts
description: Returns a cursor-paginated list of sub accounts under the parent account. Soft-deleted sub accounts are not included; usage billed for sub accounts deleted during the current period is reported by the usage endpoint's `removed_sub_accounts` aggregate.
operationId: listSubAccounts
tags:
- Sub Accounts
parameters:
- name: account_id
in: path
required: true
description: Parent account ID
schema:
type: string
format: uuid
- name: limit
in: query
description: Maximum number of items to return (1-100)
schema:
type: integer
minimum: 1
maximum: 100
default: 100
- name: after
in: query
description: Pagination cursor for the next page. Provide the value from `next_cursor` in the response.
schema:
type: string
- name: before
in: query
description: Pagination cursor for the previous page. Provide the value from `previous_cursor` in the response.
schema:
type: string
security:
- BearerAuth: ["sub-accounts:read"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/common"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
response, _, err := client.SubAccountsAPI.ListSubAccounts(ctx, accountID, &common.PaginationParams{
Limit: ahasend.Int32(50),
})
if err != nil {
log.Fatalf("Error listing sub accounts: %v", err)
}
for _, sub := range response.Data {
fmt.Printf("%s %s %s\n", sub.ID, sub.Name, sub.Status)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const page = await client.subAccounts.list({ limit: 20 });
console.log("Sub-accounts listed.", { count: page.data.length });
responses:
'200':
description: List of sub accounts
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedSubAccountsResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Parent account not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
summary: Create Sub Account
description: Creates a new sub account under the parent account
operationId: createSubAccount
tags:
- Sub Accounts
parameters:
- name: account_id
in: path
required: true
description: Parent account ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["sub-accounts:write"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// The SDK sends a fresh Idempotency-Key with this POST and reuses it on
// its own retries, so a retried request is not applied twice.
response, _, err := client.SubAccountsAPI.CreateSubAccount(ctx, accountID, requests.CreateSubAccountRequest{
Name: "Acme Subsidiary",
Website: "acme.example.com",
MonthlyCredit: ahasend.Int64(0),
})
if err != nil {
log.Fatalf("Error creating sub account: %v", err)
}
fmt.Printf("Created sub account %s\n", response.ID)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const subAccount = await client.subAccounts.create({
name: "Example subsidiary",
website: "subsidiary.example.com",
});
console.log("Sub-account created.", { id: subAccount.id, status: subAccount.status });
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSubAccountRequest'
responses:
'201':
description: Sub account created successfully
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/SubAccount'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Parent account not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/sub-accounts/usage:
get:
summary: Get Sub-Account Usage
description: Returns current billing-period usage and proportional allocated cost for the parent and active sub accounts
operationId: getSubAccountsUsage
tags:
- Sub Accounts
parameters:
- name: account_id
in: path
required: true
description: Parent account ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["sub-accounts:usage"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
response, _, err := client.SubAccountsAPI.GetSubAccountsUsage(ctx, accountID)
if err != nil {
log.Fatalf("Error getting sub-accounts usage: %v", err)
}
fmt.Printf("Allocation method: %s\n", response.AllocationMethod)
fmt.Printf("Total: %d messages, %.2f %s\n", response.Total.ReceptionCount, response.Total.AllocatedCost, response.Currency)
for _, sub := range response.SubAccounts {
name := "(unnamed)"
if sub.Name != nil {
name = *sub.Name
} else if sub.AccountID != nil {
name = sub.AccountID.String()
}
fmt.Printf(" %s: %d messages, %.2f %s\n", name, sub.ReceptionCount, sub.AllocatedCost, response.Currency)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const usage = await client.subAccounts.usage();
console.log("Sub-account usage loaded.", {
currency: usage.currency,
subAccountCount: usage.sub_accounts.length,
});
responses:
'200':
description: Sub-account usage breakdown
content:
application/json:
schema:
$ref: '#/components/schemas/SubAccountUsageResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Parent account not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/sub-accounts/{sub_account_id}:
get:
summary: Get Sub Account
description: Returns a specific sub account under the parent account
operationId: getSubAccount
tags:
- Sub Accounts
parameters:
- name: account_id
in: path
required: true
description: Parent account ID
schema:
type: string
format: uuid
- name: sub_account_id
in: path
required: true
description: Sub account ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["sub-accounts:read"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
subAccountID := uuid.MustParse("7d3c9f5e-2a41-4b8e-9c6d-0f1e2a3b4c5d")
response, _, err := client.SubAccountsAPI.GetSubAccount(ctx, accountID, subAccountID)
if err != nil {
log.Fatalf("Error getting sub account: %v", err)
}
fmt.Printf("%s %s (%s)\n", response.Name, response.Website, response.Status)
fmt.Printf("Domains: %d, members: %d\n", response.DomainCount, response.MemberCount)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const subAccountId = "00000000-0000-4000-8000-000000000004";
const subAccount = await client.subAccounts.get(subAccountId);
console.log("Sub-account found.", { id: subAccount.id, status: subAccount.status });
responses:
'200':
description: Sub account details
content:
application/json:
schema:
$ref: '#/components/schemas/SubAccount'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Sub account not found under the parent account
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
summary: Update Sub Account
description: Updates a sub account's editable settings
operationId: updateSubAccount
tags:
- Sub Accounts
parameters:
- name: account_id
in: path
required: true
description: Parent account ID
schema:
type: string
format: uuid
- name: sub_account_id
in: path
required: true
description: Sub account ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["sub-accounts:write"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
subAccountID := uuid.MustParse("7d3c9f5e-2a41-4b8e-9c6d-0f1e2a3b4c5d")
response, _, err := client.SubAccountsAPI.UpdateSubAccount(ctx, accountID, subAccountID, requests.UpdateSubAccountRequest{
Name: ahasend.String("Acme Subsidiary"),
MonthlyCredit: ahasend.Int64(50000),
})
if err != nil {
log.Fatalf("Error updating sub account: %v", err)
}
fmt.Printf("%s monthly credit: %d\n", response.Name, response.MonthlyCredit)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const subAccountId = "00000000-0000-4000-8000-000000000004";
const subAccount = await client.subAccounts.update(subAccountId, {
name: "Renamed subsidiary",
});
console.log("Sub-account updated.", { id: subAccount.id, status: subAccount.status });
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSubAccountRequest'
responses:
'200':
description: Sub account updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SubAccount'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Sub account not found under the parent account
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
summary: Delete Sub Account
description: Soft-deletes a sub account under the parent account
operationId: deleteSubAccount
tags:
- Sub Accounts
parameters:
- name: account_id
in: path
required: true
description: Parent account ID
schema:
type: string
format: uuid
- name: sub_account_id
in: path
required: true
description: Sub account ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["sub-accounts:delete"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
subAccountID := uuid.MustParse("7d3c9f5e-2a41-4b8e-9c6d-0f1e2a3b4c5d")
response, _, err := client.SubAccountsAPI.DeleteSubAccount(ctx, accountID, subAccountID)
if err != nil {
log.Fatalf("Error deleting sub account: %v", err)
}
fmt.Println(response.Message)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const subAccountId = "00000000-0000-4000-8000-000000000004";
const result = await client.subAccounts.delete(subAccountId);
console.log("Sub-account deleted.", { message: result.message });
responses:
'200':
description: Sub account deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
example:
message: "sub account deleted"
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Sub account not found under the parent account
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/sub-accounts/{sub_account_id}/suspend:
post:
summary: Pause Sub Account
description: Pauses sending on a sub account under the parent account. The status of the sub account becomes `suspended`.
operationId: suspendSubAccount
tags:
- Sub Accounts
parameters:
- name: account_id
in: path
required: true
description: Parent account ID
schema:
type: string
format: uuid
- name: sub_account_id
in: path
required: true
description: Sub account ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["sub-accounts:suspend"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
subAccountID := uuid.MustParse("7d3c9f5e-2a41-4b8e-9c6d-0f1e2a3b4c5d")
response, _, err := client.SubAccountsAPI.SuspendSubAccount(ctx, accountID, subAccountID, requests.SuspendSubAccountRequest{
Reason: "Customer requested temporary pause",
})
if err != nil {
log.Fatalf("Error suspending sub account: %v", err)
}
fmt.Printf("%s is %s\n", response.ID, response.Status)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const subAccountId = "00000000-0000-4000-8000-000000000004";
const subAccount = await client.subAccounts.suspend(subAccountId, {
reason: "Requested by account administrator",
});
console.log("Sub-account suspended.", { id: subAccount.id, status: subAccount.status });
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SuspendSubAccountRequest'
responses:
'200':
description: Sub account paused successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SubAccount'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Sub account not found under the parent account
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/sub-accounts/{sub_account_id}/unsuspend:
post:
summary: Resume Sub Account
description: Resumes sending on a paused sub account under the parent account
operationId: unsuspendSubAccount
tags:
- Sub Accounts
parameters:
- name: account_id
in: path
required: true
description: Parent account ID
schema:
type: string
format: uuid
- name: sub_account_id
in: path
required: true
description: Sub account ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["sub-accounts:suspend"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
subAccountID := uuid.MustParse("7d3c9f5e-2a41-4b8e-9c6d-0f1e2a3b4c5d")
response, _, err := client.SubAccountsAPI.UnsuspendSubAccount(ctx, accountID, subAccountID)
if err != nil {
log.Fatalf("Error unsuspending sub account: %v", err)
}
fmt.Printf("%s is %s\n", response.ID, response.Status)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const subAccountId = "00000000-0000-4000-8000-000000000004";
const subAccount = await client.subAccounts.unsuspend(subAccountId);
console.log("Sub-account unsuspended.", { id: subAccount.id, status: subAccount.status });
responses:
'200':
description: Sub account resumed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SubAccount'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: |
Forbidden, or AhaSend paused the sub account. Only AhaSend support
can resume that pause.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Sub account not found under the parent account
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/sub-accounts/{sub_account_id}/domains/{domain}/unpause:
post:
summary: Unpause Sub Account Domain
description: |
Lifts the pause on a domain of a sub account under the parent account, so that the domain can send again.
The call is idempotent: if sending from the domain is not paused, it changes nothing and returns the domain.
A change of the pause can take some minutes to apply to new email.
operationId: unpauseSubAccountDomain
tags:
- Sub Accounts
parameters:
- name: account_id
in: path
required: true
description: Parent account ID
schema:
type: string
format: uuid
- name: sub_account_id
in: path
required: true
description: Sub account ID
schema:
type: string
format: uuid
- name: domain
in: path
required: true
description: Domain name
schema:
type: string
format: hostname
security:
- BearerAuth: ["sub-accounts:suspend"]
responses:
'200':
description: The domain, with sending not paused
content:
application/json:
schema:
$ref: '#/components/schemas/Domain'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Sub account not found under the parent account, or domain not found in the sub account
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
subAccountID := uuid.MustParse("7d3c9f5e-2a41-4b8e-9c6d-0f1e2a3b4c5d")
response, _, err := client.SubAccountsAPI.UnpauseSubAccountDomain(ctx, accountID, subAccountID, "example.com")
if err != nil {
log.Fatalf("Error unpausing sub account domain: %v", err)
}
fmt.Printf("%s paused: %t\n", response.Domain, response.Paused)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const subAccountId = "00000000-0000-4000-8000-000000000004";
const domain = await client.subAccounts.unpauseDomain(subAccountId, "mail.example.com");
console.log("Sub-account domain unpaused.", { name: domain.domain, paused: domain.paused });
/v2/accounts/{account_id}/sub-accounts/{sub_account_id}/api-keys:
get:
summary: List Sub-Account API Keys
description: Returns a cursor-paginated list of API keys owned by a sub account. The `secret_key` field is omitted from list responses.
operationId: listSubAccountAPIKeys
tags:
- Sub Accounts
parameters:
- name: account_id
in: path
required: true
description: Parent account ID
schema:
type: string
format: uuid
- name: sub_account_id
in: path
required: true
description: Sub account ID
schema:
type: string
format: uuid
- name: limit
in: query
description: Maximum number of items to return (1-100)
schema:
type: integer
minimum: 1
maximum: 100
default: 100
- name: after
in: query
description: Pagination cursor for the next page. Provide the value from `next_cursor` in the response.
schema:
type: string
- name: before
in: query
description: Pagination cursor for the previous page. Provide the value from `previous_cursor` in the response.
schema:
type: string
security:
- BearerAuth: ["sub-account-api-keys:read"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/common"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
subAccountID := uuid.MustParse("7d3c9f5e-2a41-4b8e-9c6d-0f1e2a3b4c5d")
// List responses never carry secret keys; only create returns one.
response, _, err := client.SubAccountsAPI.ListSubAccountAPIKeys(ctx, accountID, subAccountID, &common.PaginationParams{
Limit: ahasend.Int32(50),
})
if err != nil {
log.Fatalf("Error listing sub-account API keys: %v", err)
}
for _, key := range response.Data {
fmt.Printf("%s %s\n", key.ID, key.Label)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const subAccountId = "00000000-0000-4000-8000-000000000004";
const page = await client.subAccounts.apiKeys.list(subAccountId, { limit: 20 });
console.log("Sub-account API keys listed.", { count: page.data.length });
responses:
'200':
description: List of sub-account API keys
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedAPIKeysResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Sub account not found under the parent account
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
summary: Create Sub-Account API Key
description: |
Creates an API key owned by the sub account. Parent credentials must belong to the parent account and include `sub-account-api-keys:write`; sub-account credentials cannot manage nested API keys. The returned `secret_key` authenticates as the child account and should be stored immediately.
Bootstrap example:
1. Create the sub account with `POST /v2/accounts/{account_id}/sub-accounts` and a unique `Idempotency-Key`.
2. Create the bootstrap child API key with this endpoint and a different unique `Idempotency-Key`.
3. Store the one-time `secret_key` from the `201` response. Exact idempotent replays within 5 minutes return the same `secret_key`.
4. Use that child secret with the child `sub_account_id` as the `account_id` on ordinary v2 routes.
operationId: createSubAccountAPIKey
tags:
- Sub Accounts
parameters:
- name: account_id
in: path
required: true
description: Parent account ID
schema:
type: string
format: uuid
- name: sub_account_id
in: path
required: true
description: Sub account ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["sub-account-api-keys:write"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
subAccountID := uuid.MustParse("7d3c9f5e-2a41-4b8e-9c6d-0f1e2a3b4c5d")
// Bootstrap an API key for the sub account.
//
// The SDK sends a fresh Idempotency-Key with this POST and reuses it on
// its own retries, so a retried request is not applied twice.
response, _, err := client.SubAccountsAPI.CreateSubAccountAPIKey(ctx, accountID, subAccountID, requests.CreateAPIKeyRequest{
Label: "Bootstrap key",
Scopes: []string{"messages:send:all", "domains:read"},
// Optional: restrict the key to specific source IPs.
IPAllowList: []string{"203.0.113.0/24"},
})
if err != nil {
log.Fatalf("Error creating sub-account API key: %v", err)
}
// response.SecretKey is returned only on create (and on an idempotent
// replay of it): put it in your secret store now, and never log it.
fmt.Printf("Created API key %s (%s)\n", response.ID, response.Label)
}
- lang: shell
label: Bootstrap child API key
source: |
PARENT_ACCOUNT_ID="9d0cf9d0-4f5e-4674-bcf1-8ec39968b6e1"
PARENT_SECRET="aha-sk-parent-64-character-key"
curl -sS -X POST "https://api.ahasend.com/v2/accounts/${PARENT_ACCOUNT_ID}/sub-accounts" \
-H "Authorization: Bearer ${PARENT_SECRET}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: subacct-20240101-acme" \
-d '{"name":"Acme Subsidiary","website":"acme.example.com"}' \
> sub-account.json
CHILD_ACCOUNT_ID="$(jq -r '.id' sub-account.json)"
curl -sS -X POST "https://api.ahasend.com/v2/accounts/${PARENT_ACCOUNT_ID}/sub-accounts/${CHILD_ACCOUNT_ID}/api-keys" \
-H "Authorization: Bearer ${PARENT_SECRET}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: child-bootstrap-key-20240101-acme" \
-d '{"label":"Bootstrap key","scopes":["messages:send:all","domains:read"]}' \
> child-api-key.json
CHILD_SECRET="$(jq -r '.secret_key' child-api-key.json)"
printf 'Store this one-time child secret securely: %s\n' "${CHILD_SECRET}"
curl -sS "https://api.ahasend.com/v2/accounts/${CHILD_ACCOUNT_ID}/domains" \
-H "Authorization: Bearer ${CHILD_SECRET}"
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const subAccountId = "00000000-0000-4000-8000-000000000004";
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const apiKey = await client.subAccounts.apiKeys.create(subAccountId, {
label: "Bootstrap key",
scopes: ["messages:send:all"],
});
console.log("Sub-account API key created.", { id: apiKey.id, label: apiKey.label });
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAPIKeyRequest'
example:
label: "Bootstrap key"
scopes: ["messages:send:all", "domains:read"]
responses:
'201':
description: Sub-account API key created successfully
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/APIKey'
- type: object
required:
- secret_key
properties:
secret_key:
type: string
readOnly: true
description: |
One-time secret key. Store it immediately. Exact
successful idempotent replays return the same secret
during the 5-minute encrypted replay window.
example:
object: api_key
id: "13b3aa8e-78d3-48a1-92d2-4b8b1228c2dd"
created_at: "2024-01-01T00:05:00Z"
updated_at: "2024-01-01T00:05:00Z"
last_used_at: null
account_id: "2f3c5d2a-9ef8-4c91-a5f4-79990c8c1d3a"
label: "Bootstrap key"
public_key: "aha-pk-child-public-key"
secret_key: "aha-sk-child-secret-key"
scopes:
- id: "c574470d-76ef-4f74-9b24-70a583a17e03"
created_at: "2024-01-01T00:05:00Z"
updated_at: "2024-01-01T00:05:00Z"
api_key_id: "13b3aa8e-78d3-48a1-92d2-4b8b1228c2dd"
scope: "messages:send:all"
domain_id: null
ip_allow_list: []
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Sub account not found under the parent account
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/sub-accounts/{sub_account_id}/api-keys/{key_id}:
get:
summary: Get Sub-Account API Key
description: Returns a specific API key owned by a sub account. The `secret_key` field is omitted from read responses.
operationId: getSubAccountAPIKey
tags:
- Sub Accounts
parameters:
- name: account_id
in: path
required: true
description: Parent account ID
schema:
type: string
format: uuid
- name: sub_account_id
in: path
required: true
description: Sub account ID
schema:
type: string
format: uuid
- name: key_id
in: path
required: true
description: API key ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["sub-account-api-keys:read"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
subAccountID := uuid.MustParse("7d3c9f5e-2a41-4b8e-9c6d-0f1e2a3b4c5d")
keyID := uuid.MustParse("c5a32c40-b351-439f-8230-779daed3e42c")
response, _, err := client.SubAccountsAPI.GetSubAccountAPIKey(ctx, accountID, subAccountID, keyID)
if err != nil {
log.Fatalf("Error getting sub-account API key: %v", err)
}
fmt.Printf("%s %s (%d scopes)\n", response.ID, response.Label, len(response.Scopes))
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const subAccountId = "00000000-0000-4000-8000-000000000004";
const keyId = "00000000-0000-4000-8000-000000000005";
const apiKey = await client.subAccounts.apiKeys.get(subAccountId, keyId);
console.log("Sub-account API key found.", { id: apiKey.id, label: apiKey.label });
responses:
'200':
description: Sub-account API key details
content:
application/json:
schema:
$ref: '#/components/schemas/APIKey'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: API key or sub account not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
summary: Update Sub-Account API Key
description: Updates the label and scopes for an API key owned by a sub account. Updated scopes are validated against the child account.
operationId: updateSubAccountAPIKey
tags:
- Sub Accounts
parameters:
- name: account_id
in: path
required: true
description: Parent account ID
schema:
type: string
format: uuid
- name: sub_account_id
in: path
required: true
description: Sub account ID
schema:
type: string
format: uuid
- name: key_id
in: path
required: true
description: API key ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["sub-account-api-keys:write"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
subAccountID := uuid.MustParse("7d3c9f5e-2a41-4b8e-9c6d-0f1e2a3b4c5d")
keyID := uuid.MustParse("c5a32c40-b351-439f-8230-779daed3e42c")
response, _, err := client.SubAccountsAPI.UpdateSubAccountAPIKey(ctx, accountID, subAccountID, keyID, requests.UpdateAPIKeyRequest{
Label: ahasend.String("Updated bootstrap key"),
Scopes: &[]string{"messages:send:all", "domains:read"},
// Replaces the allowed source IPs. &[]string{} clears the list (any IP);
// leaving the field nil keeps the current list.
IPAllowList: &[]string{"203.0.113.0/24"},
})
if err != nil {
log.Fatalf("Error updating sub-account API key: %v", err)
}
fmt.Printf("Updated API key %s\n", response.ID)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const subAccountId = "00000000-0000-4000-8000-000000000004";
const keyId = "00000000-0000-4000-8000-000000000005";
const apiKey = await client.subAccounts.apiKeys.update(subAccountId, keyId, {
label: "Renamed bootstrap key",
});
console.log("Sub-account API key updated.", { id: apiKey.id, label: apiKey.label });
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAPIKeyRequest'
example:
label: "Updated bootstrap key"
scopes: ["messages:send:all", "domains:read"]
responses:
'200':
description: Sub-account API key updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/APIKey'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: API key or sub account not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
summary: Delete Sub-Account API Key
description: Deletes an API key owned by a sub account.
operationId: deleteSubAccountAPIKey
tags:
- Sub Accounts
parameters:
- name: account_id
in: path
required: true
description: Parent account ID
schema:
type: string
format: uuid
- name: sub_account_id
in: path
required: true
description: Sub account ID
schema:
type: string
format: uuid
- name: key_id
in: path
required: true
description: API key ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["sub-account-api-keys:delete"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
subAccountID := uuid.MustParse("7d3c9f5e-2a41-4b8e-9c6d-0f1e2a3b4c5d")
keyID := uuid.MustParse("c5a32c40-b351-439f-8230-779daed3e42c")
response, _, err := client.SubAccountsAPI.DeleteSubAccountAPIKey(ctx, accountID, subAccountID, keyID)
if err != nil {
log.Fatalf("Error deleting sub-account API key: %v", err)
}
fmt.Println(response.Message)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const subAccountId = "00000000-0000-4000-8000-000000000004";
const keyId = "00000000-0000-4000-8000-000000000005";
const result = await client.subAccounts.apiKeys.delete(subAccountId, keyId);
console.log("Sub-account API key deleted.", { message: result.message });
responses:
'200':
description: Sub-account API key deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
example:
message: "api key {id} ({label}) deleted successfully"
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: API key or sub account not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
# Contact endpoints
/v2/accounts/{account_id}/contacts:
post:
summary: Create Contact
description: |
Creates one account-global contact with no list membership. Email is
trimmed and lowercased. Writable attributes must match the account's
dashboard-managed definitions; validation, membership, and activity
fields are response-only. The contact cannot be campaign-targeted until
it is added to a list with the Lists endpoints. This operation does not
read or change suppression records.
The optional `Idempotency-Key` follows the ordinary 24-hour v2 replay contract.
Successful 201, controller-produced deterministic 400, and duplicate
contact 409 outcomes are stored for 24 hours. An identical request
replays the same status and semantically equivalent JSON body with
`Idempotent-Replayed: true`. Authentication, authorization, rate-limit,
payload-mismatch, and server-error responses are not stored. Reusing
the key with a different method, resolved path, or semantic JSON payload
returns 422.
operationId: createContact
tags:
- Contacts
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["contacts:write"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// The SDK sends a fresh Idempotency-Key with this POST and reuses it on
// its own retries, so a retried request is not applied twice.
response, _, err := client.ContactsAPI.CreateContact(ctx, accountID, requests.CreateContactRequest{
Email: "person@example.com",
FirstName: ahasend.String("Pat"),
Attributes: map[string]any{"customer": true},
})
if err != nil {
log.Fatalf("Error creating contact: %v", err)
}
fmt.Printf("Created contact %s\n", response.ID)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const contact = await client.contacts.create({
email: "person@example.com",
first_name: "Pat",
attributes: { customer: true },
});
console.log("Contact created.", { id: contact.id, status: contact.status });
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateContactRequest'
responses:
'201':
description: Contact created successfully
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'400':
description: Invalid request body, email, or attribute value
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `contacts:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: |
Either the normalized email already exists on the account or the
idempotency-key execution is in progress. The in-progress case is
identified only by `Idempotent-Replayed: false` plus a positive
integer `Retry-After`. A fresh duplicate-contact response has
neither header; a stored replay of that response has
`Idempotent-Replayed: true`.
headers:
Idempotent-Replayed:
description: |
`false` with a positive `Retry-After` means an execution is in
progress. `true` means a stored duplicate-contact 409 was
replayed. Absent means a fresh duplicate-contact conflict.
schema:
type: string
enum: ['true', 'false']
Retry-After:
$ref: '#/components/headers/IdempotencyRetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
get:
summary: List Contacts
description: |
Returns account-global contacts in newest-first `(created_at, id)` order.
`after` and `before` are mutually exclusive. Attribute values are
recursive legacy JSON; they are intentionally broader than canonical
values accepted by contact writes.
operationId: getContacts
tags:
- Contacts
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: limit
in: query
description: Maximum number of contacts to return
schema:
type: integer
minimum: 1
maximum: 100
default: 100
- name: after
in: query
description: Cursor for the next page; cannot be combined with `before`
schema:
type: string
- name: before
in: query
description: Cursor for the previous page; cannot be combined with `after`
schema:
type: string
- name: email
in: query
description: Normalized exact email filter
schema:
type: string
format: email
- name: status
in: query
description: Contact status filter
schema:
type: string
enum: [enabled, disabled, blocked]
- name: subscribed
in: query
description: Filter by global subscription state
schema:
type: boolean
- name: from_time
in: query
description: Include contacts created at or after this RFC3339 time
schema:
type: string
format: date-time
- name: to_time
in: query
description: Include contacts created at or before this RFC3339 time
schema:
type: string
format: date-time
security:
- BearerAuth: ["contacts:read"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
response, _, err := client.ContactsAPI.GetContacts(ctx, accountID, requests.GetContactsParams{
Limit: ahasend.Int32(100),
Status: ahasend.String("enabled"),
Subscribed: ahasend.Bool(true),
})
if err != nil {
log.Fatalf("Error listing contacts: %v", err)
}
for _, contact := range response.Data {
fmt.Printf("%s %s\n", contact.ID, contact.Email)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const page = await client.contacts.list({ status: "enabled", subscribed: true, limit: 20 });
console.log("Contacts listed.", { count: page.data.length });
responses:
'200':
description: Paginated contacts
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedContactsResponse'
'400':
description: Invalid filter or cursor
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `contacts:read` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/contacts/batch:
post:
summary: Batch upsert contacts
description: |
Synchronously creates or updates one through 1,000 account-global
contacts. Duplicate normalized emails all fail without application;
deterministic record failures do not block valid records. Successful
effects and the optional idempotency replay response commit atomically
and use the ordinary 24-hour replay window. Malformed, empty, and
over-cap request 400s are also deterministic and replayable. Reusing a
key with a different method, resolved path, or semantic JSON payload
returns 422. An identical keyed request replays the same status and a
semantically equivalent JSON response.
Measured pacing guidance: batch size is a cap, not a throughput target.
Measure end-to-end latency with representative data, submit the next
synchronous batch only after the previous response, and reduce batch
size or pace requests when latency grows. Honor 429 responses before
continuing; the API makes no fixed throughput guarantee.
operationId: batchUpsertContacts
tags: [Contacts]
parameters:
- name: account_id
in: path
required: true
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["contacts:write"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// The SDK sends a fresh Idempotency-Key with this POST and reuses it on
// its own retries, so a retried request is not applied twice.
response, _, err := client.ContactsAPI.BatchUpsertContacts(ctx, accountID, requests.BatchUpsertContactsRequest{
Data: []requests.BatchUpsertContactInput{
{Email: "one@example.com"},
{Email: "two@example.com", Unsubscribed: ahasend.Bool(true)},
},
})
if err != nil {
log.Fatalf("Error upserting contacts: %v", err)
}
// Each item succeeds or fails on its own.
fmt.Printf("created=%d updated=%d failed=%d\n", response.Created, response.Updated, response.Failed)
for _, result := range response.Data {
if result.Reason != "" {
fmt.Printf("%s: %s (%s)\n", result.Email, result.Outcome, result.Reason)
}
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const result = await client.contacts.batchUpsert({
data: [
{ email: "new@example.com", attributes: { customer: true } },
{ email: "existing@example.com", attributes: { obsolete: null } },
],
});
console.log("Contact batch completed.", { created: result.created, updated: result.updated });
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchUpsertContactsRequest'
responses:
'200':
description: Ordered per-contact outcomes
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/BatchUpsertContactsResponse'
'400':
description: |
Malformed, empty, or over-cap request. An identical keyed retry
replays the stored response with `Idempotent-Replayed: true`.
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `contacts:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: An idempotency-key execution is already in progress
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotencyInProgress'
Retry-After:
$ref: '#/components/headers/IdempotencyRetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/contacts/{id_or_email}:
get:
summary: Get Contact
description: |
Returns one account-scoped contact. UUID-shaped values resolve by ID;
all other values resolve by trimmed, lowercased email. Email identifiers
must be percent-encoded exactly once as URL path segments; pass a raw
email to SDKs, including addresses such as `user+tag@example.com`.
operationId: getContact
tags:
- Contacts
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: id_or_email
in: path
required: true
description: |
Contact UUID or email address. Percent-encode an email exactly once
as a path segment; SDK callers pass the raw email value.
schema:
type: string
security:
- BearerAuth: ["contacts:read"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// Address a contact by its ID or its email address; the SDK escapes the path.
response, _, err := client.ContactsAPI.GetContact(ctx, accountID, "user+tag@example.com")
if err != nil {
log.Fatalf("Error getting contact: %v", err)
}
fmt.Printf("%s %s unsubscribed=%t\n", response.ID, response.Email, response.Unsubscribed)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const idOrEmail = "User+Tag@Example.COM";
const contact = await client.contacts.get(idOrEmail);
console.log("Contact found.", { id: contact.id, status: contact.status });
responses:
'200':
description: Contact
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `contacts:read` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Contact not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
summary: Update Contact
description: |
Partially updates one account-scoped contact. UUID-shaped path values
resolve by ID; all other values resolve by trimmed, lowercased email.
Email identifiers must be percent-encoded exactly once as URL path
segments. A null attribute member deletes that key; the other writable
values remain canonical and dashboard-definition driven. Subscription
changes are independent of suppression records.
operationId: updateContact
tags:
- Contacts
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: id_or_email
in: path
required: true
description: |
Contact UUID or email address. Percent-encode an email exactly once
as a path segment; SDK callers pass the raw email value.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateContactRequest'
security:
- BearerAuth: ["contacts:write"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// Only the fields you set change. A nil attribute value deletes that key.
response, _, err := client.ContactsAPI.UpdateContact(ctx, accountID, "user+tag@example.com", requests.UpdateContactRequest{
FirstName: ahasend.String("Jordan"),
Attributes: map[string]any{"obsolete_key": nil},
})
if err != nil {
log.Fatalf("Error updating contact: %v", err)
}
fmt.Printf("Updated contact %s\n", response.ID)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const idOrEmail = "User+Tag@Example.COM";
const contact = await client.contacts.update(idOrEmail, {
unsubscribed: true,
attributes: { obsolete: null },
});
console.log("Contact updated.", { id: contact.id, unsubscribed: contact.unsubscribed });
responses:
'200':
description: Updated contact
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'400':
description: Invalid request body, replacement email, or attribute
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `contacts:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Contact not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Replacement email conflicts with another contact
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
summary: Delete Contact
description: |
Permanently deletes one account-scoped contact. UUID-shaped path values
resolve by ID; all other values resolve by trimmed, lowercased email;
email identifiers must be percent-encoded exactly once as URL path
segments.
This is destructive history removal. Running and paused workflow
instances and their active jobs are cancelled, while the cancelled
workflow rows and events remain for audit. The contact and its
unsubscribe record, list memberships, campaign-recipient records, opens,
and clicks are permanently removed by cascades. Complaint, permanent,
and protected suppressions remain byte-for-byte unchanged. Prefer unsubscribe over
delete when the intent is only to prevent marketing delivery.
operationId: deleteContact
tags:
- Contacts
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: id_or_email
in: path
required: true
description: |
Contact UUID or email address. Percent-encode an email exactly once
as a path segment; SDK callers pass the raw email value.
schema:
type: string
security:
- BearerAuth: ["contacts:delete"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
response, _, err := client.ContactsAPI.DeleteContact(ctx, accountID, "user+tag@example.com")
if err != nil {
log.Fatalf("Error deleting contact: %v", err)
}
fmt.Println(response.Message)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const idOrEmail = "User+Tag@Example.COM";
const result = await client.contacts.delete(idOrEmail);
console.log("Contact deleted.", { message: result.message });
responses:
'200':
description: Contact deleted
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `contacts:delete` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Contact not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
# Lists endpoints
/v2/accounts/{account_id}/lists:
get:
summary: List Lists
description: |
Returns the account's lists in newest-first `(created_at, id)` order.
`after` and `before` are mutually exclusive. Every list carries
`contact_count`, the number of members a campaign to it would reach.
operationId: getLists
tags:
- Lists
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: limit
in: query
description: Maximum number of lists to return
schema:
type: integer
minimum: 1
maximum: 100
default: 100
- name: after
in: query
description: Cursor for the next page; cannot be combined with `before`
schema:
type: string
- name: before
in: query
description: Cursor for the previous page; cannot be combined with `after`
schema:
type: string
- name: name
in: query
description: |
Case-insensitive substring match on the list name. `%`, `_`, and `\`
match literally rather than as wildcards. The value is trimmed
before it is matched, so one that is empty or all whitespace filters
nothing and the full collection is returned.
schema:
type: string
security:
- BearerAuth: ["lists:read"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
response, _, err := client.ListsAPI.GetLists(ctx, accountID, requests.GetListsParams{
Limit: ahasend.Int32(100),
Name: ahasend.String("newsletter"),
})
if err != nil {
log.Fatalf("Error listing lists: %v", err)
}
for _, list := range response.Data {
fmt.Printf("%s %s (%d contacts)\n", list.ID, list.Name, list.ContactCount)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const page = await client.lists.list({ name: "newsletter", limit: 20 });
console.log("Lists listed.", { count: page.data.length });
responses:
'200':
description: Paginated lists
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedContactListsResponse'
'400':
description: Invalid filter or cursor
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `lists:read` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
summary: Create List
description: |
Creates one list. Lists are static, private, and single opt-in, and
names are not unique within an account. A new list has no members, so
its `contact_count` is 0.
The optional `Idempotency-Key` follows the ordinary 24-hour v2 replay
contract. An identical request replays the same status and semantically
equivalent JSON body with `Idempotent-Replayed: true`. Reusing the key
with a different method, resolved path, or semantic JSON payload
returns 422.
operationId: createList
tags:
- Lists
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["lists:write"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// The SDK sends a fresh Idempotency-Key with this POST and reuses it on
// its own retries, so a retried request is not applied twice.
response, _, err := client.ListsAPI.CreateList(ctx, accountID, requests.CreateListRequest{
Name: "Product updates",
Description: ahasend.String("Monthly release notes"),
Tags: []string{"product"},
})
if err != nil {
log.Fatalf("Error creating list: %v", err)
}
fmt.Printf("Created list %s\n", response.ID)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const list = await client.lists.create({
name: "Product updates",
description: "Monthly release notes",
tags: ["product"],
});
console.log("List created.", { id: list.id, contactCount: list.contact_count });
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateContactListRequest'
responses:
'201':
description: List created successfully
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/ContactList'
'400':
description: |
Invalid request body, or a property that is not writable. An
identical keyed retry replays the stored response with
`Idempotent-Replayed: true`.
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `lists:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/lists/{list_id}:
get:
summary: Get List
description: |
Returns one account-scoped list, including `contact_count`.
operationId: getList
tags:
- Lists
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: list_id
in: path
required: true
description: List ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["lists:read"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
listID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
response, _, err := client.ListsAPI.GetList(ctx, accountID, listID)
if err != nil {
log.Fatalf("Error getting list: %v", err)
}
fmt.Printf("%s (%d contacts)\n", response.Name, response.ContactCount)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const listId = "00000000-0000-4000-8000-000000000010";
const list = await client.lists.get(listId);
console.log("List found.", { id: list.id, contactCount: list.contact_count });
responses:
'200':
description: List
content:
application/json:
schema:
$ref: '#/components/schemas/ContactList'
'400':
description: Malformed `list_id`
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `lists:read` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: List not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
summary: Update List
description: |
Partially updates one account-scoped list. An omitted or null property
leaves the stored value unchanged; a present `tags` array replaces the
stored tags, and an empty one clears them. A stored value that breaks a
bound this API introduces reads back fine and fails only when it is
re-sent here.
operationId: updateList
tags:
- Lists
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: list_id
in: path
required: true
description: List ID
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateContactListRequest'
security:
- BearerAuth: ["lists:write"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
listID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
// Only the fields you set change; an empty tags slice clears the tags.
response, _, err := client.ListsAPI.UpdateList(ctx, accountID, listID, requests.UpdateListRequest{
Name: ahasend.String("Product updates"),
Tags: &[]string{},
})
if err != nil {
log.Fatalf("Error updating list: %v", err)
}
fmt.Printf("Updated list %s\n", response.Name)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const listId = "00000000-0000-4000-8000-000000000010";
const list = await client.lists.update(listId, { name: "Product news", tags: [] });
console.log("List updated.", { id: list.id, name: list.name });
responses:
'200':
description: Updated list
content:
application/json:
schema:
$ref: '#/components/schemas/ContactList'
'400':
description: Malformed `list_id`, invalid request body, or a property that is not writable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `lists:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: List not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
summary: Delete List
description: |
Soft-deletes one account-scoped list. The list stops being readable and
stops contributing recipients to any campaign, but every membership row
is kept, so deleting a list never discards the record that someone
unsubscribed from it or reported it as spam. Those memberships stop
being readable with the list: this list answers 404 afterwards, and it
no longer appears among a contact's lists.
Deleting a list that is already gone returns 404, so a client retrying
to convergence converges.
operationId: deleteList
tags:
- Lists
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: list_id
in: path
required: true
description: List ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["lists:delete"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
listID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
response, _, err := client.ListsAPI.DeleteList(ctx, accountID, listID)
if err != nil {
log.Fatalf("Error deleting list: %v", err)
}
fmt.Println(response.Message)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const listId = "00000000-0000-4000-8000-000000000010";
const result = await client.lists.delete(listId);
console.log("List deleted.", { message: result.message });
responses:
'200':
description: List deleted
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Malformed `list_id`
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `lists:delete` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: List not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: |
A campaign that still needs this list references it. Campaigns
in `draft`, `validating`, `scheduled`, `sending`,
`paused`, or `waiting_for_review` block the delete, while `sent`,
`failed`, and `canceled` campaigns do not. This conflict carries no
idempotency headers.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/lists/{list_id}/contacts:
get:
summary: List Contacts on a List
description: |
Returns one list's members, newest first on the membership's own
`(created_at, id)`. Each item carries the membership, its `contact_id`,
and the contact's normalized email; `include_contacts=true` embeds the
whole contact and additionally requires the `contacts:read` scope.
`after` and `before` are mutually exclusive.
`subscription_status=confirmed` answers who a campaign on this list can
reach, subject to the account-wide checks campaign initialization also
applies. The filter accepts `complained` as well, because such a
membership exists and must be findable even though no caller can write
that status.
operationId: getListContacts
tags:
- Lists
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: list_id
in: path
required: true
description: List ID
schema:
type: string
format: uuid
- name: limit
in: query
description: Maximum number of memberships to return
schema:
type: integer
minimum: 1
maximum: 100
default: 100
- name: after
in: query
description: Cursor for the next page; cannot be combined with `before`
schema:
type: string
- name: before
in: query
description: Cursor for the previous page; cannot be combined with `after`
schema:
type: string
- name: subscription_status
in: query
description: Per-list consent filter
schema:
type: string
enum: [unconfirmed, confirmed, unsubscribed, complained]
- name: email
in: query
description: |
Exact email filter. The value is normalized before it is
compared, so one that is empty or all whitespace filters nothing
and the full collection is returned. It is compared against the
address as stored, so an address that was stored unnormalized
renders normalized in this collection and is still not matched by
this filter.
schema:
type: string
format: email
- name: include_contacts
in: query
description: |
Embed the whole contact in every item. Requires the `contacts:read`
scope in addition to `lists:read`.
schema:
type: boolean
security:
- BearerAuth: ["lists:read"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
listID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
response, _, err := client.ListsAPI.GetListContacts(ctx, accountID, listID, requests.GetListContactsParams{
SubscriptionStatus: ahasend.String(requests.ListContactStatusConfirmed),
})
if err != nil {
log.Fatalf("Error listing list contacts: %v", err)
}
for _, member := range response.Data {
fmt.Printf("%s %s\n", member.Email, member.SubscriptionStatus)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const listId = "00000000-0000-4000-8000-000000000010";
const page = await client.lists.contacts.list(listId, {
subscription_status: "confirmed",
limit: 20,
});
console.log("List members listed.", { count: page.data.length });
responses:
'200':
description: Paginated list memberships
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedListContactsResponse'
'400':
description: Malformed `list_id`, invalid filter, or invalid cursor
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: |
Missing `lists:read` scope, or `include_contacts=true` without the
`contacts:read` scope. The expansion check runs before the list is
resolved, so an unauthorized expansion naming a list that does not
exist answers 403 rather than 404.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: List not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/lists/{list_id}/contacts/batch:
post:
summary: Batch add contacts to a list
description: |
Synchronously adds one through 1,000 existing contacts to one list.
This operation only ever inserts: an entry whose membership already
exists is reported `already_member` and the stored row is left exactly
as it stands, whatever its status, so bulk work can never erase an
unsubscribe. A membership it creates is `confirmed`. No contact is
created, and an entry naming nobody in this account is reported
`not_found`.
One malformed entry does not cost the others their result. An entry is
reported `invalid` when it is not an object, names neither or both of
`email` and `id`, carries any other property, holds an `id` that is
not a string or not a UUID, or an `email` that is not a string or fails
the validation contact writes apply, or repeats an identifier another
entry already used. Duplicates are
counted on the normalized identifier, so `A@x.com` and `a@x.com` are
one identifier and both entries fail. A contact named twice by
different kinds of identifier is settled by payload order: the earliest
position that would create the membership takes `added`, and every
later one takes `already_member`. An unknown property beside `data` is
still a 400 for the whole request.
The memberships and the optional idempotency replay response commit
atomically and use the ordinary 24-hour replay window. Every status
this operation's handler produces is stored and replayable: the 200,
the 404 for a list that is not there, and each of the 400s below.
Reusing a key with a different method, resolved path, or semantic JSON
payload returns 422. An identical keyed request replays the same status
and a semantically equivalent JSON response.
Measured pacing guidance: batch size is a cap, not a throughput target.
Measure end-to-end latency with representative data, submit the next
synchronous batch only after the previous response, and reduce batch
size or pace requests when latency grows. Honor 429 responses before
continuing; the API makes no fixed throughput guarantee.
operationId: batchAddListContacts
tags:
- Lists
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: list_id
in: path
required: true
description: List ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["lists:write"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/AhaSend/ahasend-go/models/responses"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
listID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
// Name each contact by email or by ID.
contactID := uuid.MustParse("22222222-2222-4222-8222-222222222222")
// The SDK sends a fresh Idempotency-Key with this POST and reuses it on
// its own retries, so a retried request is not applied twice.
response, _, err := client.ListsAPI.BatchAddListContacts(ctx, accountID, listID, requests.BatchAddListContactsRequest{
Data: []requests.BatchAddListContactInput{
{Email: ahasend.String("one@example.com")},
{ID: &contactID},
},
})
if err != nil {
log.Fatalf("Error adding contacts to the list: %v", err)
}
// Each item succeeds or fails on its own.
fmt.Printf("added=%d skipped=%d failed=%d\n", response.Added, response.Skipped, response.Failed)
for _, result := range response.Data {
if result.Outcome != responses.BatchListContactOutcomeAdded {
fmt.Printf("item %d: %s %s\n", result.Position, result.Outcome, result.Reason)
}
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const listId = "00000000-0000-4000-8000-000000000010";
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const result = await client.lists.contacts.batchAdd(listId, {
data: [{ email: "one@example.com" }, { id: "00000000-0000-4000-8000-000000000011" }],
});
console.log("List batch completed.", { added: result.added, failed: result.failed });
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchAddListContactsRequest'
responses:
'200':
description: Ordered per-entry outcomes
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/BatchAddListContactsResponse'
'400':
description: |
A malformed `list_id`, a body that is not a single JSON object, an
unknown property beside `data`, a `data` that is absent, null or not
an array, an empty `data` array, or more than 1,000 entries. An
identical keyed retry replays the stored response with
`Idempotent-Replayed: true`.
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `lists:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: |
List not found. The handler produces this status, so it is stored
against the idempotency key: an identical keyed retry replays it
with `Idempotent-Replayed: true` rather than looking the list up
again.
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/lists/{list_id}/contacts/{id_or_email}:
put:
summary: Add or Update a List Contact
description: |
Adds one existing contact to one list, or updates the membership that
is already there, and returns the membership either way. No contact is
created.
A membership this call creates is `confirmed` unless the body names
another status. On a membership that already exists, a body naming no
status leaves the stored status exactly as it is: a PUT is not an
implicit resubscribe, and naming a status is the deliberate act that
may resubscribe. A write that names the status the membership already
holds changes nothing at all, `updated_at` included, so a retry leaves
the row identical.
`confirmed` sets `subscribed_at` and clears `unsubscribed_at`;
`unsubscribed` sets `unsubscribed_at` and leaves `subscribed_at` as it
was; `unconfirmed` sets neither.
UUID-shaped path values resolve by ID; all other values resolve by
trimmed, lowercased email. Email identifiers must be percent-encoded
exactly once as URL path segments; pass a raw email to SDKs, including
addresses such as `user+tag@example.com`.
operationId: upsertListContact
tags:
- Lists
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: list_id
in: path
required: true
description: List ID
schema:
type: string
format: uuid
- name: id_or_email
in: path
required: true
description: |
Contact UUID or email address. Percent-encode an email exactly once
as a path segment; SDK callers pass the raw email value.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertListContactRequest'
security:
- BearerAuth: ["lists:write"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
listID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
// Record that the contact unsubscribed from this list. Setting confirmed
// would subscribe them again, so only do that when they asked for it.
response, _, err := client.ListsAPI.UpsertListContact(ctx, accountID, listID, "user+tag@example.com", requests.UpsertListContactRequest{
SubscriptionStatus: ahasend.String(requests.ListContactStatusUnsubscribed),
})
if err != nil {
log.Fatalf("Error updating the list membership: %v", err)
}
fmt.Printf("%s is %s\n", response.Email, response.SubscriptionStatus)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const listId = "00000000-0000-4000-8000-000000000010";
const idOrEmail = "User+Tag@Example.COM";
const membership = await client.lists.contacts.upsert(listId, idOrEmail, {
subscription_status: "unsubscribed",
});
console.log("List membership saved.", { status: membership.subscription_status });
responses:
'200':
description: The membership, whether this request created it or updated one
content:
application/json:
schema:
$ref: '#/components/schemas/ListContact'
'400':
description: |
Malformed `list_id`, an absent or non-object body, a property that
is not writable, or a `subscription_status` outside `confirmed`,
`unconfirmed`, and `unsubscribed`. The body is validated before the
membership is read, so naming `complained` is 400 whatever the
stored row holds.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `lists:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: |
The list does not exist on this account, or no contact matches
`{id_or_email}`. The message says which.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: |
The membership is `complained`: the contact reported this list as
spam, that verdict is the mailbox provider's rather than the
caller's, and writing over it would clear the only record of when
the complaint landed. The membership is frozen and nothing is
changed, including by a request naming no status. This conflict
carries no idempotency headers.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
summary: Remove a Contact from a List
description: |
Removes one contact from one list. UUID-shaped path values resolve by
ID; all other values resolve by trimmed, lowercased email. Email
identifiers must be percent-encoded exactly once as URL path segments;
pass a raw email to SDKs, including addresses such as
`user+tag@example.com`.
This deletes the membership row, and with it any record that the
contact unsubscribed from this list, so re-adding them later is silent.
Prefer unsubscribe over delete when the intent is only to prevent
marketing delivery: `PUT` the same path with
`{"subscription_status": "unsubscribed"}` instead, which is reversible
and keeps the record. A `complained` membership, one whose contact
reported the list as spam, cannot be removed and returns 409, so the
contact cannot be added back as `confirmed`. Removing a membership that
is not there returns 404.
operationId: deleteListContact
tags:
- Lists
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: list_id
in: path
required: true
description: List ID
schema:
type: string
format: uuid
- name: id_or_email
in: path
required: true
description: |
Contact UUID or email address. Percent-encode an email exactly once
as a path segment; SDK callers pass the raw email value.
schema:
type: string
security:
- BearerAuth: ["lists:write"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
listID := uuid.MustParse("11111111-1111-4111-8111-111111111111")
// Removing drops the membership. To stop sending to the contact while
// keeping the record, set its status to unsubscribed instead.
response, _, err := client.ListsAPI.DeleteListContact(ctx, accountID, listID, "user+tag@example.com")
if err != nil {
log.Fatalf("Error removing the contact from the list: %v", err)
}
fmt.Println(response.Message)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const listId = "00000000-0000-4000-8000-000000000010";
const idOrEmail = "User+Tag@Example.COM";
const result = await client.lists.contacts.delete(listId, idOrEmail);
console.log("Contact removed from list.", { message: result.message });
responses:
'200':
description: Contact removed from the list
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Malformed `list_id`
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `lists:write` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: |
The list does not exist on this account, no contact matches
`{id_or_email}`, or the contact is not on this list. The message
says which.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: The contact reported this list as spam; the membership is kept
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/contacts/{id_or_email}/lists:
get:
summary: List a Contact's Lists
description: |
Returns the lists one contact is on, newest first on the membership's
own `(created_at, id)`. Each item carries the membership with the list
embedded, and soft-deleted lists are excluded. This is the reverse of
`GET /v2/accounts/{account_id}/lists/{list_id}/contacts`, and the only
way to answer what one person is subscribed to without walking every
list. `after` and `before` are mutually exclusive.
UUID-shaped path values resolve by ID; all other values resolve by
trimmed, lowercased email. Email identifiers must be percent-encoded
exactly once as URL path segments; pass a raw email to SDKs, including
addresses such as `user+tag@example.com`.
To stop marketing mail to someone everywhere at once, `PUT
/v2/accounts/{account_id}/contacts/{id_or_email}` with
`{"unsubscribed": true}`; there is no remove-from-all-lists operation.
That is an account-wide verdict campaigns honour, and it does not
change any membership here: every row still reads back with the status
it holds, though the contact no longer counts toward any list's
`contact_count`. To record the decision on one list, `PUT` that
membership with `{"subscription_status": "unsubscribed"}`.
operationId: getContactLists
tags:
- Lists
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: id_or_email
in: path
required: true
description: |
Contact UUID or email address. Percent-encode an email exactly once
as a path segment; SDK callers pass the raw email value.
schema:
type: string
- name: limit
in: query
description: Maximum number of memberships to return
schema:
type: integer
minimum: 1
maximum: 100
default: 100
- name: after
in: query
description: Cursor for the next page; cannot be combined with `before`
schema:
type: string
- name: before
in: query
description: Cursor for the previous page; cannot be combined with `after`
schema:
type: string
- name: subscription_status
in: query
description: Per-list consent filter
schema:
type: string
enum: [unconfirmed, confirmed, unsubscribed, complained]
security:
- BearerAuth: ["lists:read"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
response, _, err := client.ListsAPI.GetContactLists(ctx, accountID, "user+tag@example.com", requests.GetContactListsParams{
SubscriptionStatus: ahasend.String(requests.ListContactStatusConfirmed),
})
if err != nil {
log.Fatalf("Error getting the contact's lists: %v", err)
}
for _, membership := range response.Data {
if membership.List != nil {
fmt.Printf("%s %s\n", membership.List.Name, membership.SubscriptionStatus)
}
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const idOrEmail = "User+Tag@Example.COM";
const page = await client.contacts.lists.list(idOrEmail, { subscription_status: "confirmed" });
console.log("Contact lists listed.", { count: page.data.length });
responses:
'200':
description: Paginated list memberships, each with its list embedded
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedListContactsResponse'
'400':
description: Invalid filter or cursor
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Missing `lists:read` scope
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Contact not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
# Suppressions endpoints
/v2/accounts/{account_id}/suppressions:
get:
summary: Get Suppressions
description: |
Returns a list of suppressions for the account
**Query Parameters:**
- `domain`: Filter by domain (optional)
- `email`: Filter by email (optional)
- `from_time`: Filter suppressions created after this time (RFC3339 format, optional)
- `to_time`: Filter suppressions created before this time (RFC3339 format, optional)
- `limit`: Maximum number of items to return (1-100, default: 100)
- `after`: Pagination cursor for the next page
- `before`: Pagination cursor for the previous page
operationId: getSuppressions
tags:
- Suppressions
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: domain
in: query
description: Filter by domain
schema:
type: string
- name: email
in: query
description: Email address
schema:
type: string
format: email
- name: from_time
in: query
description: Filter suppressions created after this time (RFC3339 format)
schema:
type: string
format: date-time
- name: to_time
in: query
description: Filter suppressions created before this time (RFC3339 format)
schema:
type: string
format: date-time
- name: limit
in: query
description: Maximum number of items to return (1-100)
schema:
type: integer
minimum: 1
maximum: 100
default: 100
- name: after
in: query
description: Pagination cursor for the next page. Provide the value provided in `next_cursor` from the response.
schema:
type: string
- name: before
in: query
description: Pagination cursor for the previous page. Provide the value provided in `previous_cursor` from the response.
schema:
type: string
security:
- BearerAuth: ["suppressions:read"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
response, _, err := client.SuppressionsAPI.GetSuppressions(ctx, accountID, requests.GetSuppressionsParams{})
if err != nil {
log.Fatalf("Error getting suppressions: %v", err)
}
for _, suppression := range response.Data {
fmt.Printf("%s until %s: %s\n", suppression.Email, suppression.ExpiresAt, suppression.Reason)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const page = await client.suppressions.list({ limit: 20 });
console.log("Suppressions listed.", { count: page.data.length });
responses:
'200':
description: List of suppressions
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedSuppressionsResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Domain not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
summary: Create Suppression
description: |
Creates a new suppression for an email address
**Validation Requirements:**
- `email` must be a valid email address
- `expires_at` must be in RFC3339 format
- `domain` is optional - if not provided, applies to all account domains
operationId: createSuppression
tags:
- Suppressions
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["suppressions:write"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"time"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// The SDK sends a fresh Idempotency-Key with this POST and reuses it on
// its own retries, so a retried request is not applied twice.
response, _, err := client.SuppressionsAPI.CreateSuppression(ctx, accountID, requests.CreateSuppressionRequest{
Email: "test@example.com",
Reason: ahasend.String("Inbox full"),
ExpiresAt: time.Now().Add(30 * 24 * time.Hour),
})
if err != nil {
log.Fatalf("Error creating suppression: %v", err)
}
fmt.Printf("Created %d suppression(s)\n", len(response.Data))
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const result = await client.suppressions.create({
email: "recipient@example.net",
reason: "User requested removal",
expires_at: "2030-01-01T00:00:00Z",
});
console.log("Suppression created.", { count: result.data.length });
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSuppressionRequest'
responses:
'201':
description: Suppression created successfully
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSuppressionResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: |
Either the suppression already exists or the idempotency-key
execution is in progress. The in-progress case is identified only
by `Idempotent-Replayed: false` plus a positive integer
`Retry-After`. A new duplicate-suppression response has neither
header; a stored replay of that response has
`Idempotent-Replayed: true`. The message is not a stable
discriminator.
headers:
Idempotent-Replayed:
description: |
`false` with a positive `Retry-After` means an execution is in
progress. `true` means a stored duplicate-suppression 409 was
replayed. Absent means a fresh duplicate-suppression conflict.
schema:
type: string
enum: ['true', 'false']
Retry-After:
$ref: '#/components/headers/IdempotencyRetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
summary: Delete Suppression
description: |
Deletes suppressions for an email address
**Query Parameters:**
- `email`: Required email address to delete from suppression list
- `domain`: Optional domain filter to delete suppressions for specific domain only
operationId: deleteSuppression
tags:
- Suppressions
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: email
in: query
required: true
description: Email address
schema:
type: string
format: email
- name: domain
in: query
description: Optional domain filter
schema:
type: string
security:
- BearerAuth: ["suppressions:delete"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// Removes the suppression for one address; pass nil instead of a domain
// to remove it for every domain.
response, _, err := client.SuppressionsAPI.DeleteSuppression(
ctx,
accountID,
"info@example.com",
ahasend.String("notifications.example.com"),
)
if err != nil {
log.Fatalf("Error deleting suppression: %v", err)
}
fmt.Println(response.Message)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const result = await client.suppressions.delete({ email: "recipient@example.net" });
console.log("Suppression deleted.", { message: result.message });
responses:
'200':
description: Suppression deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Suppression not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/suppressions/all:
delete:
summary: Delete All Suppressions
description: |
Deletes the account's suppressions, except protected ones. A suppression is
protected when the recipient made the decision themselves, by unsubscribing or by
reporting the message as spam; those are kept. The response message reports how
many were kept when any were.
**Query Parameters:**
- `domain`: Optional domain filter to delete suppressions for specific domain only
operationId: deleteAllSuppressions
tags:
- Suppressions
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: domain
in: query
description: Optional domain filter
schema:
type: string
security:
- BearerAuth: ["suppressions:wipe"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// Pass a domain instead of nil to limit the wipe to that domain.
response, _, err := client.SuppressionsAPI.DeleteAllSuppressions(ctx, accountID, nil)
if err != nil {
log.Fatalf("Error deleting all suppressions: %v", err)
}
fmt.Println(response.Message)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const result = await client.suppressions.wipe({ domain: "example.com" });
console.log("Domain suppressions deleted.", { message: result.message });
responses:
'200':
description: Suppressions deleted successfully, protected ones kept
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Domain not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
# Routes endpoints
/v2/accounts/{account_id}/routes:
get:
summary: Get Routes
description: |
Returns a list of routes for the account. A domain-scoped key must
provide the matching `domain` query parameter; the global read role can
list without that filter.
operationId: getRoutes
tags:
- Routes
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: domain
in: query
description: Domain to filter routes by. Required when using a domain-scoped routes:read:{domain} API key.
schema:
type: string
- name: limit
in: query
description: Maximum number of items to return (1-100)
schema:
type: integer
minimum: 1
maximum: 100
default: 100
- name: after
in: query
description: Pagination cursor for the next page. Provide the value provided in `next_cursor` from the response.
schema:
type: string
- name: before
in: query
description: Pagination cursor for the previous page.
schema:
type: string
security:
- BearerAuth: ["routes:read:all"]
- BearerAuth: ["routes:read:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
response, _, err := client.RoutesAPI.GetRoutes(ctx, accountID, nil)
if err != nil {
log.Fatalf("Error getting routes: %v", err)
}
for _, route := range response.Data {
fmt.Printf("%s %s -> %s\n", route.ID, route.Recipient, route.URL)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const page = await client.routes.list({ domain: "example.com", limit: 20 });
console.log("Routes listed.", { count: page.data.length });
responses:
'200':
description: List of routes
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedRoutesResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
summary: Create Route
description: |
Creates a new route for inbound email routing. Authorization uses the
domain in `recipient`: the global write role or its matching
domain-specific write role is sufficient.
operationId: createRoute
tags:
- Routes
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["routes:write:all"]
- BearerAuth: ["routes:write:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// The SDK sends a fresh Idempotency-Key with this POST and reuses it on
// its own retries, so a retried request is not applied twice.
response, _, err := client.RoutesAPI.CreateRoute(ctx, accountID, requests.CreateRouteRequest{
Name: "My Route",
URL: "https://example.com/tickets",
Recipient: "ticket-*@example.com",
Enabled: ahasend.Bool(true),
Attachments: true,
Headers: true,
StripReplies: true,
})
if err != nil {
log.Fatalf("Error creating route: %v", err)
}
fmt.Printf("Created route %s\n", response.ID)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const route = await client.routes.create({
name: "Inbound messages",
url: "https://example.com/inbound",
recipient: "inbound@example.com",
});
console.log("Route created.", { id: route.id, name: route.name });
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRouteRequest'
responses:
'201':
description: Route created successfully
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/CreatedRoute'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/routes/{route_id}:
get:
summary: Get Route
description: |
Returns a specific route by ID. Access requires the global read role or
a read role matching the route's recipient domain.
operationId: getRoute
tags:
- Routes
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: route_id
in: path
required: true
description: Route ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["routes:read:all"]
- BearerAuth: ["routes:read:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
routeID := uuid.MustParse("c5a32c40-b351-439f-8230-779daed3e42c")
response, _, err := client.RoutesAPI.GetRoute(ctx, accountID, routeID)
if err != nil {
log.Fatalf("Error getting route: %v", err)
}
fmt.Printf("%s %s -> %s\n", response.Name, response.Recipient, response.URL)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const routeId = "00000000-0000-4000-8000-000000000006";
const route = await client.routes.get(routeId);
console.log("Route found.", { id: route.id, name: route.name });
responses:
'200':
description: Route details
content:
application/json:
schema:
$ref: '#/components/schemas/Route'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Route not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
summary: Update Route
description: |
Updates an existing route. A domain-scoped key must authorize the
existing recipient domain and, when `recipient` changes, the new domain;
`routes:write:all` satisfies both checks.
operationId: updateRoute
tags:
- Routes
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: route_id
in: path
required: true
description: Route ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["routes:write:all"]
- BearerAuth: ["routes:write:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
routeID := uuid.MustParse("c5a32c40-b351-439f-8230-779daed3e42c")
response, _, err := client.RoutesAPI.UpdateRoute(ctx, accountID, routeID, requests.UpdateRouteRequest{
Name: ahasend.String("Updated Name"),
URL: ahasend.String("https://example.com/new-tickets"),
})
if err != nil {
log.Fatalf("Error updating route: %v", err)
}
fmt.Printf("Updated route %s\n", response.ID)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const routeId = "00000000-0000-4000-8000-000000000006";
const route = await client.routes.update(routeId, {
url: "https://example.com/inbound-v2",
});
console.log("Route updated.", { id: route.id, name: route.name });
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateRouteRequest'
responses:
'200':
description: Route updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Route'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Route not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
summary: Delete Route
description: |
Deletes a route. Access requires the global delete role or a delete role
matching the route's recipient domain.
operationId: deleteRoute
tags:
- Routes
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: route_id
in: path
required: true
description: Route ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["routes:delete:all"]
- BearerAuth: ["routes:delete:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
routeID := uuid.MustParse("c5a32c40-b351-439f-8230-779daed3e42c")
response, _, err := client.RoutesAPI.DeleteRoute(ctx, accountID, routeID)
if err != nil {
log.Fatalf("Error deleting route: %v", err)
}
fmt.Println(response.Message)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const routeId = "00000000-0000-4000-8000-000000000006";
const result = await client.routes.delete(routeId);
console.log("Route deleted.", { message: result.message });
responses:
'200':
description: Route deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Route not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
# Webhooks endpoints
/v2/accounts/{account_id}/webhooks:
get:
summary: Get Webhooks
description: |
Returns a list of webhooks for the account
The global read role sees all webhooks. Domain-scoped read roles return
only webhooks associated with at least one authorized domain.
**Query Parameters:**
- `enabled`: Filter by enabled status
- Event filters: `on_reception`, `on_delivered`, `on_transient_error`, `on_failed`, `on_bounced`, `on_suppressed`, `on_opened`, `on_clicked`, `on_suppression_created`, `on_dns_error`
- `limit`: Maximum number of items to return (1-100, default: 100)
- `after`: Pagination cursor for the next page
- `before`: Pagination cursor for the previous page
operationId: getWebhooks
tags:
- Webhooks
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: enabled
in: query
description: Filter by enabled status
schema:
type: boolean
- name: on_reception
in: query
description: Filter by reception event trigger
schema:
type: boolean
- name: on_delivered
in: query
description: Filter by delivery event trigger
schema:
type: boolean
- name: on_transient_error
in: query
description: Filter by transient error event trigger
schema:
type: boolean
- name: on_failed
in: query
description: Filter by failure event trigger
schema:
type: boolean
- name: on_bounced
in: query
description: Filter by bounce event trigger
schema:
type: boolean
- name: on_suppressed
in: query
description: Filter by suppression event trigger
schema:
type: boolean
- name: on_opened
in: query
description: Filter by open event trigger
schema:
type: boolean
- name: on_clicked
in: query
description: Filter by click event trigger
schema:
type: boolean
- name: on_suppression_created
in: query
description: Filter by suppression creation event trigger
schema:
type: boolean
- name: on_dns_error
in: query
description: Filter by DNS error event trigger
schema:
type: boolean
- name: limit
in: query
description: Maximum number of items to return (1-100)
schema:
type: integer
minimum: 1
maximum: 100
default: 100
- name: after
in: query
description: Pagination cursor for the next page. Provide the value provided in `next_cursor` from the response.
schema:
type: string
- name: before
in: query
description: Pagination cursor for the previous page.
schema:
type: string
security:
- BearerAuth: ["webhooks:read:all"]
- BearerAuth: ["webhooks:read:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
params := api.GetWebhooksParams{Enabled: ahasend.Bool(true)}
params.Limit = ahasend.Int32(100)
response, _, err := client.WebhooksAPI.GetWebhooks(ctx, accountID, params)
if err != nil {
log.Fatalf("Error getting webhooks: %v", err)
}
for _, webhook := range response.Data {
fmt.Printf("%s %s -> %s\n", webhook.ID, webhook.Name, webhook.URL)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const page = await client.webhooks.list({ limit: 20 });
console.log("Webhooks listed.", { count: page.data.length });
responses:
'200':
description: List of webhooks
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedWebhooksResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
summary: Create Webhook
description: |
Creates a new webhook for event notifications. A `scoped` webhook
requires at least one domain and the key must have write permission for
every supplied domain. A `global` webhook requires
`webhooks:write:all`; supplied domains are accepted but ignored, and
the response contains `domains: []`.
operationId: createWebhook
tags:
- Webhooks
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["webhooks:write:all"]
- BearerAuth: ["webhooks:write:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// The SDK sends a fresh Idempotency-Key with this POST and reuses it on
// its own retries, so a retried request is not applied twice.
response, _, err := client.WebhooksAPI.CreateWebhook(ctx, accountID, requests.CreateWebhookRequest{
Name: "Failures",
URL: "https://example.com/webhook",
Scope: "global",
Enabled: ahasend.Bool(true),
OnBounced: true,
OnTransientError: true,
OnFailed: true,
})
if err != nil {
log.Fatalf("Error creating webhook: %v", err)
}
// Use the secret to verify the signature of each delivery.
fmt.Printf("Created webhook %s, secret: %s\n", response.ID, response.Secret)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const webhook = await client.webhooks.create({
name: "Delivery events",
url: "https://example.com/webhooks/ahasend",
scope: "global",
on_delivered: true,
});
console.log("Webhook created.", { id: webhook.id, name: webhook.name });
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhookRequest'
responses:
'201':
description: Webhook created successfully
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/CreatedWebhook'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/webhooks/{webhook_id}:
get:
summary: Get Webhook
description: |
Returns a specific webhook by ID. Access requires the global read role
or a read role matching at least one associated domain.
operationId: getWebhook
tags:
- Webhooks
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: webhook_id
in: path
required: true
description: Webhook ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["webhooks:read:all"]
- BearerAuth: ["webhooks:read:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
webhookID := uuid.MustParse("c5a32c40-b351-439f-8230-779daed3e42c")
response, _, err := client.WebhooksAPI.GetWebhook(ctx, accountID, webhookID)
if err != nil {
log.Fatalf("Error getting webhook: %v", err)
}
fmt.Printf("%s -> %s (enabled: %t)\n", response.Name, response.URL, response.Enabled)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const webhookId = "00000000-0000-4000-8000-000000000007";
const webhook = await client.webhooks.get(webhookId);
console.log("Webhook found.", { id: webhook.id, name: webhook.name });
responses:
'200':
description: Webhook details
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Webhook not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
summary: Update Webhook
description: |
Updates an existing webhook. Omitted or null fields are unchanged.
Omitted/null `domains` preserves associations, while `[]` clears the
associations of a resulting-scoped webhook. Moving from global to
scoped requires a non-empty `domains` array in the same request. Moving
to global clears associations and ignores supplied domains.
A domain-scoped key must be authorized for the existing webhook and
every newly supplied domain; changing to global requires
`webhooks:write:all`.
**Note:** The webhook secret is not updatable
operationId: updateWebhook
tags:
- Webhooks
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: webhook_id
in: path
required: true
description: Webhook ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["webhooks:write:all"]
- BearerAuth: ["webhooks:write:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
webhookID := uuid.MustParse("c5a32c40-b351-439f-8230-779daed3e42c")
response, _, err := client.WebhooksAPI.UpdateWebhook(ctx, accountID, webhookID, requests.UpdateWebhookRequest{
Name: ahasend.String("Failures"),
URL: ahasend.String("https://example.com/webhook"),
Enabled: ahasend.Bool(true),
OnBounced: ahasend.Bool(true),
})
if err != nil {
log.Fatalf("Error updating webhook: %v", err)
}
fmt.Printf("Updated webhook %s\n", response.ID)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const webhookId = "00000000-0000-4000-8000-000000000007";
const webhook = await client.webhooks.update(webhookId, {
name: "Transactional delivery events",
});
console.log("Webhook updated.", { id: webhook.id, name: webhook.name });
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWebhookRequest'
responses:
'200':
description: Webhook updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Webhook not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
summary: Delete Webhook
description: |
Deletes a webhook. Access requires the global delete role or a delete
role matching at least one associated domain.
operationId: deleteWebhook
tags:
- Webhooks
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: webhook_id
in: path
required: true
description: Webhook ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["webhooks:delete:all"]
- BearerAuth: ["webhooks:delete:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
webhookID := uuid.MustParse("c5a32c40-b351-439f-8230-779daed3e42c")
response, _, err := client.WebhooksAPI.DeleteWebhook(ctx, accountID, webhookID)
if err != nil {
log.Fatalf("Error deleting webhook: %v", err)
}
fmt.Println(response.Message)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const webhookId = "00000000-0000-4000-8000-000000000007";
const result = await client.webhooks.delete(webhookId);
console.log("Webhook deleted.", { message: result.message });
responses:
'200':
description: Webhook deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Webhook not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
# SMTP Credentials endpoints
/v2/accounts/{account_id}/smtp-credentials:
get:
summary: Get SMTP Credentials
description: |
Returns a list of SMTP credentials for the account. The global read role
sees all credentials; domain-scoped roles return credentials associated
with at least one authorized domain.
operationId: getSMTPCredentials
tags:
- SMTP Credentials
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: limit
in: query
description: Maximum number of items to return (1-100)
schema:
type: integer
minimum: 1
maximum: 100
default: 100
- name: after
in: query
description: Pagination cursor for the next page. Provide the value provided in `next_cursor` from the response.
schema:
type: string
- name: before
in: query
description: Pagination cursor for the previous page.
schema:
type: string
security:
- BearerAuth: ["smtp-credentials:read:all"]
- BearerAuth: ["smtp-credentials:read:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
response, _, err := client.SMTPCredentialsAPI.GetSMTPCredentials(ctx, accountID, nil)
if err != nil {
log.Fatalf("Error getting SMTP credentials: %v", err)
}
for _, credential := range response.Data {
fmt.Printf("%s %s %s\n", credential.ID, credential.Name, credential.Username)
}
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const page = await client.smtpCredentials.list({ limit: 20 });
console.log("SMTP credentials listed.", { count: page.data.length });
responses:
'200':
description: List of SMTP credentials
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedSMTPCredentialsResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
summary: Create SMTP Credential
description: |
Creates a new SMTP credential for SMTP authentication. A `scoped`
credential requires at least one domain and the key must have write
permission for every supplied domain. A `global` credential requires
`smtp-credentials:write:all`; supplied domains are accepted but ignored,
and the response contains `domains: []`. SMTP credentials have no
update endpoint.
operationId: createSMTPCredential
tags:
- SMTP Credentials
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
security:
- BearerAuth: ["smtp-credentials:write:all"]
- BearerAuth: ["smtp-credentials:write:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
// The SDK sends a fresh Idempotency-Key with this POST and reuses it on
// its own retries, so a retried request is not applied twice.
response, _, err := client.SMTPCredentialsAPI.CreateSMTPCredential(ctx, accountID, requests.CreateSMTPCredentialRequest{
Name: "My SMTP Credential",
Scope: "global",
Sandbox: true,
})
if err != nil {
log.Fatalf("Error creating SMTP credential: %v", err)
}
// response.Password is returned only on create: put it in your secret
// store now, and never log it.
fmt.Printf("Created SMTP credential for username %s\n", response.Username)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
// The SDK sends a fresh Idempotency-Key automatically and reuses it on its own retries.
const credential = await client.smtpCredentials.create({
name: "Production SMTP",
scope: "global",
});
console.log("SMTP credential created.", { id: credential.id, name: credential.name });
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSMTPCredentialRequest'
responses:
'201':
description: SMTP credential created successfully
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
$ref: '#/components/schemas/CreatedSMTPCredential'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
$ref: '#/components/responses/IdempotencyConflict'
'422':
$ref: '#/components/responses/IdempotencyPayloadMismatch'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/smtp-credentials/{smtp_credential_id}:
get:
summary: Get SMTP Credential
description: |
Returns a specific SMTP credential by ID. Access requires the global
read role or a read role matching at least one associated domain.
operationId: getSMTPCredential
tags:
- SMTP Credentials
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: smtp_credential_id
in: path
required: true
description: SMTP Credential ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["smtp-credentials:read:all"]
- BearerAuth: ["smtp-credentials:read:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
smtpCredentialID := uuid.MustParse("0194f7ac-2f6a-7d29-9f0c-9a27b19f2d1c")
response, _, err := client.SMTPCredentialsAPI.GetSMTPCredential(ctx, accountID, smtpCredentialID)
if err != nil {
log.Fatalf("Error getting SMTP credential: %v", err)
}
fmt.Printf("%s %s (%s)\n", response.Name, response.Username, response.Scope)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const credentialId = "00000000-0000-4000-8000-000000000008";
const credential = await client.smtpCredentials.get(credentialId);
console.log("SMTP credential found.", { id: credential.id, name: credential.name });
responses:
'200':
description: SMTP credential details
content:
application/json:
schema:
$ref: '#/components/schemas/SMTPCredential'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: SMTP credential not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
summary: Delete SMTP Credential
description: |
Deletes an SMTP credential. Access requires the global delete role or a
delete role matching at least one associated domain.
operationId: deleteSMTPCredential
tags:
- SMTP Credentials
parameters:
- name: account_id
in: path
required: true
description: Account ID
schema:
type: string
format: uuid
- name: smtp_credential_id
in: path
required: true
description: SMTP Credential ID
schema:
type: string
format: uuid
security:
- BearerAuth: ["smtp-credentials:delete:all"]
- BearerAuth: ["smtp-credentials:delete:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/AhaSend/ahasend-go/api"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
smtpCredentialID := uuid.MustParse("0194f7ac-2f6a-7d29-9f0c-9a27b19f2d1c")
response, _, err := client.SMTPCredentialsAPI.DeleteSMTPCredential(ctx, accountID, smtpCredentialID)
if err != nil {
log.Fatalf("Error deleting SMTP credential: %v", err)
}
fmt.Println(response.Message)
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const credentialId = "00000000-0000-4000-8000-000000000008";
const result = await client.smtpCredentials.delete(credentialId);
console.log("SMTP credential deleted.", { message: result.message });
responses:
'200':
description: SMTP credential deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: SMTP credential not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
# Statistics endpoints
/v2/accounts/{account_id}/statistics/transactional/deliverability:
get:
summary: Get Deliverability Statistics
description: |
Returns transactional deliverability statistics grouped by status
The global statistics role can query all sender domains. A
domain-scoped key is limited to authorized domains and must authorize
every comma-separated value supplied in `sender_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 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
- name: from_time
in: query
description: Filter statistics after this datetime (RFC3339 format)
schema:
type: string
format: date-time
- name: to_time
in: query
description: Filter statistics before this datetime (RFC3339 format)
schema:
type: string
format: date-time
- name: sender_domain
in: query
description: Comma-separated sender domains; the key must authorize every requested domain
schema:
type: string
- 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
- name: group_by
in: query
description: Group by time period
schema:
type: string
enum: [hour, day, week, month]
default: day
security:
- BearerAuth: ["statistics-transactional:read:all"]
- BearerAuth: ["statistics-transactional:read:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"time"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
fromTime := time.Now().Add(-30 * 24 * time.Hour)
response, _, err := client.StatisticsAPI.GetDeliverabilityStatistics(ctx, accountID, requests.GetDeliverabilityStatisticsParams{
FromTime: &fromTime,
SenderDomain: ahasend.String("example.com"),
RecipientDomains: ahasend.String("gmail.com"),
GroupBy: ahasend.String("week"),
})
if err != nil {
log.Fatalf("Error getting deliverability statistics: %v", err)
}
fmt.Printf("Got %d weekly buckets\n", len(response.Data))
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const statistics = await client.statistics.deliverability({
from_time: "2026-01-01T00:00:00Z",
to_time: "2026-01-02T00:00:00Z",
});
console.log("Deliverability statistics loaded.", { buckets: statistics.data.length });
responses:
'200':
description: Deliverability statistics
content:
application/json:
schema:
$ref: '#/components/schemas/DeliverabilityStatisticsResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests (rate limited to 1 request per second)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/statistics/transactional/bounce:
get:
summary: Get Bounce Statistics
description: |
Returns transactional bounce statistics grouped by classification
The global statistics role can query all sender domains. A
domain-scoped key is limited to authorized domains and must authorize
every comma-separated value supplied in `sender_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 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
- name: from_time
in: query
description: Filter statistics after this datetime (RFC3339 format)
schema:
type: string
format: date-time
- name: to_time
in: query
description: Filter statistics before this datetime (RFC3339 format)
schema:
type: string
format: date-time
- name: sender_domain
in: query
description: Comma-separated sender domains; the key must authorize every requested domain
schema:
type: string
- 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
- name: group_by
in: query
description: Group by time period
schema:
type: string
enum: [hour, day, week, month]
default: day
security:
- BearerAuth: ["statistics-transactional:read:all"]
- BearerAuth: ["statistics-transactional:read:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"time"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
fromTime := time.Now().Add(-30 * 24 * time.Hour)
response, _, err := client.StatisticsAPI.GetBounceStatistics(ctx, accountID, requests.GetBounceStatisticsParams{
FromTime: &fromTime,
SenderDomain: ahasend.String("example.com"),
RecipientDomains: ahasend.String("gmail.com"),
GroupBy: ahasend.String("week"),
})
if err != nil {
log.Fatalf("Error getting bounce statistics: %v", err)
}
fmt.Printf("Got %d weekly buckets\n", len(response.Data))
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const statistics = await client.statistics.bounces({
from_time: "2026-01-01T00:00:00Z",
to_time: "2026-01-02T00:00:00Z",
});
console.log("Bounce statistics loaded.", { buckets: statistics.data.length });
responses:
'200':
description: Bounce statistics
content:
application/json:
schema:
$ref: '#/components/schemas/BounceStatisticsResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests (rate limited to 1 request per second)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v2/accounts/{account_id}/statistics/transactional/delivery-time:
get:
summary: Get Delivery Time Statistics
description: |
Returns transactional delivery time statistics grouped by recipient domain
The global statistics role can query all sender domains. A
domain-scoped key is limited to authorized domains and must authorize
every comma-separated value supplied in `sender_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
- name: from_time
in: query
description: Filter statistics after this datetime (RFC3339 format)
schema:
type: string
format: date-time
- name: to_time
in: query
description: Filter statistics before this datetime (RFC3339 format)
schema:
type: string
format: date-time
- name: sender_domain
in: query
description: Comma-separated sender domains; the key must authorize every requested domain
schema:
type: string
- 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
- name: group_by
in: query
description: Group by time period
schema:
type: string
enum: [hour, day, week, month]
default: day
security:
- BearerAuth: ["statistics-transactional:read:all"]
- BearerAuth: ["statistics-transactional:read:{domain}"]
x-code-samples:
- lang: go
label: AhaSend Go SDK
source: |
package main
import (
"context"
"fmt"
"log"
"os"
"time"
"github.com/AhaSend/ahasend-go"
"github.com/AhaSend/ahasend-go/api"
"github.com/AhaSend/ahasend-go/models/requests"
"github.com/google/uuid"
)
func main() {
client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
ctx := context.Background()
fromTime := time.Now().Add(-30 * 24 * time.Hour)
response, _, err := client.StatisticsAPI.GetDeliveryTimeStatistics(ctx, accountID, requests.GetDeliveryTimeStatisticsParams{
FromTime: &fromTime,
SenderDomain: ahasend.String("example.com"),
RecipientDomains: ahasend.String("gmail.com"),
GroupBy: ahasend.String("week"),
})
if err != nil {
log.Fatalf("Error getting delivery time statistics: %v", err)
}
fmt.Printf("Got %d weekly buckets\n", len(response.Data))
}
- lang: javascript
label: Node.js 22+ (AhaSend SDK)
source: |
import { AhaSendClient } from "@ahasend/sdk";
const client = AhaSendClient.fromEnv();
const statistics = await client.statistics.deliveryTimes({
from_time: "2026-01-01T00:00:00Z",
to_time: "2026-01-02T00:00:00Z",
});
console.log("Delivery-time statistics loaded.", { buckets: statistics.data.length });
responses:
'200':
description: Delivery time statistics
content:
application/json:
schema:
$ref: '#/components/schemas/DeliveryTimeStatisticsResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests (rate limited to 1 request per second)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
tags:
- name: Utility
description: Utility endpoints for health checks and diagnostics
- name: API Keys
description: Manage API keys for authentication and access control
- name: Domains
description: Manage sending domains
- name: Messages
description: Send and manage transactional messages
- name: Accounts
description: Manage account settings and members
- name: Contacts
description: Read, create, update, batch upsert, and delete account-global contacts
- name: Templates
description: Create, change, publish and delete the account's transactional templates, and read them with their drafts, their published versions and the variables a send must supply
- name: Campaign Templates
description: Create, change, read and delete the account's campaign templates, the designs a campaign copies when it is made from one
- name: Campaigns
description: Create, change, read, duplicate, delete, test and send the account's marketing campaigns, and read their stats and recipients
- name: Lists
description: Manage contact lists and the contacts on them
- name: Suppressions
description: Manage email suppressions
- name: Routes
description: Manage inbound email routing
- name: Webhooks
description: Manage webhook notifications
- name: SMTP Credentials
description: Manage SMTP authentication credentials
- name: Statistics
description: Access transactional email statistics
- name: Message Events
description: Webhooks for outbound message delivery events
- name: Suppression Events
description: Webhooks for suppression list changes
- name: Domain Events
description: Webhooks for domain configuration issues
- name: Route Events
description: Webhooks for inbound email routing