Send a Campaign Test via the API

Send a test of a draft AhaSend marketing campaign to up to 5 addresses to check it in a real inbox. An account can send 50 test emails per day (UTC).

POST /v2/accounts/{account_id}/campaigns/{campaign_id}/test

AhaSend Go SDK

Go

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 <[e-mail]>", "[e-mail]"},
  })
  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)
  }
}

200

{
  "object": "campaign_test",
  "sent_to": [
    "<string>"
  ],
  "failed": [
    {
      "email": "<string>",
      "message": "<string>"
    }
  ],
  "result_unknown": true
}

The AhaSend API sends a test of a draft campaign. Access requires campaigns:send.

Addresses:

• to holds 1 to 5 addresses. Addresses that differ only in case count once.
• An entry can have a display name, such as Ann <[e-mail]>. The test goes to the address only.

What the test holds:

• Each address gets the design with placeholders for the contact’s fields.
• The links in the test lead to a contact that does not exist, so a click on the unsubscribe link does not unsubscribe anyone.

When the API refuses the test:

• The campaign must be a draft. Any other status answers 409.
• A campaign with issues is refused with 400, and the response holds the issues. The issue unsubscribe_link_missing does not stop a test. See Issues.
• The domain of the sender must be verified and not paused. If not, the test is refused with 400.
• An account that is blocked until a person acts, for example a sub-account in the parent-suspended status, whose parent account is suspended, cannot send tests: the test is refused with 400. An account that is blocked only until it pays, for example one with no credits left, can still send tests, because tests use no credits.

Daily limit:

• Your account can send 50 test emails per day (UTC). Each address of a test counts as one test email. Test sends from the API and from the dashboard count together.
• The API refuses the whole test when its addresses would take the day’s total over 50. For example, with 48 test emails used, a test to 5 addresses is refused, and a test to 2 addresses is sent.
• The API answers 429 when it refuses a test for the limit. Its message currently reads daily test send limit reached. Backoff does not clear this 429. A test to fewer addresses can still fit in the test emails left for the day, as in the example above. Otherwise, the limit clears when the UTC day changes. To plan for it, keep count of the test emails you send each UTC day. A 429 from Test Campaign that stays after backoff is the daily limit.
• An address that the mail server refused still counts, and so does a test with result_unknown. A test that sent nothing (502) does not count.

Response:

• sent_to lists the addresses that the mail server accepted, and failed lists the addresses it refused, each with the reason. An address in failed is given as the mail server reported it, so it can differ from the addresses in to.
• When result_unknown is true, the mail server took the request, but its answer could not be read. The test may have gone out, and sent_to and failed are empty. Check the inboxes before you send another test.
• When the mail server could not take the test, the API answers 502 and nothing was sent. Retry the request.

Idempotency: This operation accepts an Idempotency-Key header. A 2xx answer is stored, so a retry with the same key replays it and sends nothing again. Unlike other operations, a 4xx answer is not stored. A retry with the same key, for example after the daily limit resets, gets a new answer. A 502 is not stored either, so you can retry it with the same key. See Idempotency.

Related Guides

• API authentication, Permission scopes, Idempotency.
• Send Campaign, API errors, API rate limits.

Authorizations

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.

Headers

Idempotency-Key · string

Optional idempotency key for safe request retries. Must be a unique string for each logical request. An identical request with a completed stored outcome returns the original status and body. An in-progress execution returns 409, a changed method/path/body returns 422, and a released 5xx execution may run again. Keys for non-secret responses expire after 24 hours. API-key create responses include a one-time secret_key, so successful encrypted replay responses for those operations expire after 5 minutes.

Maximum string length: 255

Path Parameters

account_id · string<uuid> · required

Account ID

campaign_id · string<uuid> · required

Campaign ID

Body

application/json

The addresses to send a test to.

to · string[] · required

1 to 5 addresses, counted after addresses that differ only in case are dropped. An entry may carry a display name, such as Ann <[e-mail]>; the test goes to the address alone.

Minimum array length: 1

Response

200

application/json

What the test send did. With result_unknown, the test may have gone out.

What a test send did.

object · enum<string> · required

Object type identifier

Available options: campaign_test

sent_to · string[] · required

The addresses the mail server accepted

failed · object[] · required

The addresses the mail server refused

Show child attributes

result_unknown · boolean · required

True when the mail server took the request but its answer could not be read. The test may have gone out; sent_to and failed are empty. Check the inboxes before you send another.