List and Search Sent Emails via the API

List emails sent through AhaSend and filter them by status, sender, recipient, subject, Message-ID header, tags or time range, with cursor-based pagination.

GET /v2/accounts/{account_id}/messages

AhaSend Go SDK

Go

package main

import (
  "context"
  "fmt"
  "log"

  "github.com/AhaSend/ahasend-go"
  "github.com/AhaSend/ahasend-go/api"
  "github.com/AhaSend/ahasend-go/models/requests"
  "github.com/google/uuid"
)

func main() {
  // Create API client with authentication
  client := api.NewAPIClient(
    api.WithAPIKey("aha-sk-your-64-character-key"),
  )

  accountID := uuid.New()

  // Create context for the API call
  ctx := context.Background()

  // Call the ping endpoint
  response, httpResp, err := client.MessagesAPI.GetMessages(
    ctx,
    accountID,
    requests.GetMessagesParams{
      Status: ahasend.String("Bounced,Failed"),
      Sender: ahasend.String("[e-mail]"),
      Tags:   []string{"billing", "urgent"},
    },
  )
  if err != nil {
    log.Fatalf("Error getting messages: %v", err)
  }

  // Check response
  if httpResp.StatusCode == 200 {
    fmt.Printf("✅ Status: %d\n", httpResp.StatusCode)
    if response != nil {
      fmt.Printf("Found %d messages\n", len(response.Data))
    }
  } else {
    fmt.Printf("❌ Unexpected status code: %d\n", httpResp.StatusCode)
  }
}

200

{
  "object": "list",
  "data": [
    {
      "object": "message",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "sent_at": "2023-11-07T05:31:56Z",
      "delivered_at": "2023-11-07T05:31:56Z",
      "retain_until": "2023-11-07T05:31:56Z",
      "direction": "inbound",
      "is_bounce_notification": true,
      "bounce_classification": "<string>",
      "delivery_attempts": [
        {
          "time": "2023-11-07T05:31:56Z",
          "log": "<string>",
          "status": "<string>"
        }
      ],
      "message_id": "<string>",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "subject": "<string>",
      "tags": [
        "<string>"
      ],
      "sender": "[e-mail]",
      "recipient": "[e-mail]",
      "status": "<string>",
      "num_attempts": 123,
      "click_count": 123,
      "open_count": 123,
      "reference_message_id": 123,
      "domain_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6MTIzNH0="
  }
}

The AhaSend API returns a list of message summaries for the account. Can be filtered by various parameters.

messages:read:all can read across the account. Domain-scoped keys see only messages for domains authorized by their matching read roles.

The content field is omitted from list responses for performance reasons. Use the Get Message endpoint to retrieve the full message content.

Related Guides

• API authentication, Permission scopes, Sending guide.
• Message CLI, SMTP settings, Node.js SDK.
• Go SDK, API errors, API rate limits.

Authorizations

BearerAuthBearerAuth

Authorization · string · header · required

API key for authentication. Non-empty Security Requirement values are AhaSend API-key roles. Roles listed within one requirement object are jointly required; separate requirement objects are alternatives.

Path Parameters

account_id · string<uuid> · required

Account ID

Query Parameters

status · string

Filter by comma-separated list of message statuses. Allowed values are: Received, Delivered, Deferred, Bounced, Failed, Suppressed, Sandbox Delivered, Sandbox Deferred, Sandbox Failed, Sandbox Bounced, and Sandbox Suppressed.

sender · string<email>

Sender email address (must be from domain in API key scopes)

recipient · string<email>

Recipient email address

subject · string

Filter by subject text

message_id_header · string

Filter by message ID header (same ID returned by CreateMessage API)

tags · string

Filter by comma-separated list of tags (max 20)

from_time · string<date-time>

Filter messages created after this time (RFC3339 format)

to_time · string<date-time>

Filter messages created before this time (RFC3339 format)

limit · integer · default: 100

Maximum number of items to return (1-100)

Required range: 1 <= x <= 100

after · string

Pagination cursor for the next page. Provide the value provided in next_cursor from the response.

before · string

Pagination cursor for the previous page.

Response

200

application/json

List of messages

object · enum<string> · required

Object type identifier

Available options: list

data · object[] · required

Array of message summaries (content and content_parsed fields omitted for performance)

Show child attributes

pagination · object · required

Show child attributes

Example:

{
  "has_more": true,
  "next_cursor": "eyJpZCI6MTIzNH0="
}