A/B Testing

A/B tests let you send different variants of a campaign to a subset of your audience and automatically promote the winning variant to the remainder. You choose the test metric, sample size, and duration.

Auth scope: send or send:marketing

Endpoints

| Method | Path | Description | |--------|------|-------------| | GET | /api/v1/ab-tests | List A/B tests | | POST | /api/v1/ab-tests | Create an A/B test | | GET | /api/v1/ab-tests/:id | Get test details and results | | POST | /api/v1/ab-tests/:id/winner | Pick and send the winning variant |

GET /api/v1/ab-tests

List all A/B tests for the authenticated account.

curl "https://api.misar.io/mail/v1/ab-tests?page=1&limit=20" \
  -H "Authorization: Bearer msk_YOUR_API_KEY"

Response

{
  "success": true,
  "ab_tests": [
    {
      "id":              "abt_abc123",
      "campaign_id":     "camp_xyz789",
      "status":          "running",
      "metric":          "open_rate",
      "test_size_percent":20,
      "variant_count":   2,
      "winner_id":       null,
      "created_at":      "2026-04-01T08:00:00Z"
    }
  ],
  "total": 4
}

POST /api/v1/ab-tests

Create an A/B test tied to an existing campaign. The campaign must be in draft status.

curl -X POST https://api.misar.io/mail/v1/ab-tests \
  -H "Authorization: Bearer msk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id":        "camp_xyz789",
    "test_size_percent":  20,
    "metric":             "open_rate",
    "auto_send_winner":   true,
    "auto_send_after_hours": 4,
    "variants": [
      {
        "name":    "Variant A",
        "subject": "Your exclusive offer inside"
      },
      {
        "name":    "Variant B",
        "subject": "{{first_name}}, we have something special for you"
      }
    ]
  }'

Request Fields

| Field | Type | Required | Notes | |-------|------|----------|-------| | campaign_id | string | ✓ | Campaign to test — must be in draft status | | variants | array | ✓ | 2–5 variants; each overrides campaign fields | | test_size_percent | number | ✓ | Percentage of audience for the test (e.g. 20 = 20%) | | metric | string | ✓ | Success metric — see options below | | auto_send_winner | boolean | — | Automatically send winner when test concludes (default: false) | | auto_send_after_hours | number | — | Hours to wait before picking a winner (default: 24) |

Metric Options

| Metric | Description | |--------|-------------| | open_rate | Variant with highest unique open rate wins | | click_rate | Variant with highest unique click rate wins | | reply_rate | Variant with most direct replies wins |

Variant Fields (each overrides the base campaign for that variant's send)

| Field | Notes | |-------|-------| | name | Display name for reporting | | subject | Override subject line — supports merge tags | | body_html | Override HTML body | | body_text | Override plain text body | | from_name | Override sender display name |

Response

{
  "success": true,
  "ab_test": {
    "id":          "abt_abc123",
    "status":      "draft",
    "variants": [
      { "id": "var_1", "name": "Variant A", "send_count": 0 },
      { "id": "var_2", "name": "Variant B", "send_count": 0 }
    ]
  }
}

GET /api/v1/ab-tests/:id

Get current test results per variant.

curl https://api.misar.io/mail/v1/ab-tests/abt_abc123 \
  -H "Authorization: Bearer msk_YOUR_API_KEY"

Response

{
  "success": true,
  "ab_test": {
    "id":     "abt_abc123",
    "status": "running",
    "metric": "open_rate",
    "variants": [
      {
        "id":         "var_1",
        "name":       "Variant A",
        "send_count": 500,
        "opens":      180,
        "clicks":     45,
        "open_rate":  0.360,
        "click_rate": 0.090
      },
      {
        "id":         "var_2",
        "name":       "Variant B",
        "send_count": 500,
        "opens":      215,
        "clicks":     62,
        "open_rate":  0.430,
        "click_rate": 0.124
      }
    ],
    "winner_id":   null,
    "concludes_at":"2026-04-06T12:00:00Z"
  }
}

POST /api/v1/ab-tests/:id/winner

Manually pick the winning variant and send it to the remainder of the audience. Call this before auto_send_after_hours to override the automatic selection.

curl -X POST https://api.misar.io/mail/v1/ab-tests/abt_abc123/winner \
  -H "Authorization: Bearer msk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "variant_id": "var_2" }'

Request Fields

| Field | Type | Required | Notes | |-------|------|----------|-------| | variant_id | string | ✓ | ID of the winning variant to send |

Response

{
  "success":          true,
  "winner_variant_id":"var_2",
  "remaining_sends":  4000,
  "campaign_id":      "camp_xyz789",
  "status":           "sending"
}

A/B Test Status Values

| Status | Meaning | |--------|---------| | draft | Created but not yet launched | | running | Test variants are being sent and measured | | concluded | Measurement period ended — awaiting winner selection | | completed | Winner sent to remaining audience | | canceled | Test stopped before completion |