# Test Send Email Campaign

POST https://services.leadconnectorhq.com/emails/locations/{locationId}/campaigns/emails/{campaignId}/test

Send this campaign as a test to one to five email addresses: version A, or the A/B version picked with `variationIndex` (1 = B, 2 = C, ...), with the saved campaign subject and sender unless overridden; merge fields are filled with sample contact data, not the real recipient values. Limited to 20 test requests per location per hour, shared with template tests. Send an Idempotency-Key so a retry does not send twice. Acceptance does not confirm delivery.

## Authentication

Send `Authorization: Bearer <token>` using:

- **Sub-Account token: OAuth access token or Private Integration Token.** Scopes: `emails/campaigns.write`

## Parameters

### Header Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Idempotency-Key` | string | No | Unique key per intended write (max 255 chars). Retrying with the same key and body within 24 hours returns the first response instead of creating another resource. Reusing the key with a different body returns 422; a retry while the first request is still running returns 409. |
| `Version` | string | Yes | API Version |

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `locationId` | string | Yes | Location ID |
| `campaignId` | string | Yes | Campaign ID |

## OpenAPI Specification

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "LeadConnector API",
    "version": "v3"
  },
  "servers": [
    {
      "url": "https://services.leadconnectorhq.com"
    }
  ],
  "paths": {
    "/emails/locations/{locationId}/campaigns/emails/{campaignId}/test": {
      "post": {
        "summary": "Test Send Email Campaign",
        "operationId": "testSendEmailCampaign",
        "description": "Send this campaign as a test to one to five email addresses: version A, or the A/B version picked with `variationIndex` (1 = B, 2 = C, ...), with the saved campaign subject and sender unless overridden; merge fields are filled with sample contact data, not the real recipient values. Limited to 20 test requests per location per hour, shared with template tests. Send an Idempotency-Key so a retry does not send twice. Acceptance does not confirm delivery.",
        "parameters": [
          {
            "name": "locationId",
            "required": true,
            "in": "path",
            "description": "Location ID",
            "schema": {
              "example": "ve9EPM428h8vShlRW1KT",
              "type": "string"
            }
          },
          {
            "name": "campaignId",
            "required": true,
            "in": "path",
            "description": "Campaign ID",
            "schema": {
              "example": "67f15c2ae99226d5bcccb8f3",
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Unique key per intended write (max 255 chars). Retrying with the same key and body within 24 hours returns the first response instead of creating another resource. Reusing the key with a different body returns 422; a retry while the first request is still running returns 409.",
            "required": false,
            "schema": {
              "type": "string",
              "example": "0f8fad5b-d9cb-469f-a165-70867728950e"
            }
          },
          {
            "name": "Version",
            "in": "header",
            "description": "API Version",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "v3"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TestEmailCampaignPublicV3BodyDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestEmailPublicV3ResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestDTO"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedDTO"
                }
              }
            }
          },
          "403": {
            "description": "The token does not have access to this location",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvalidLocationDTO"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundDTO"
                }
              }
            }
          },
          "409": {
            "description": "A request with the same Idempotency-Key is still in progress; retry after a short delay"
          },
          "422": {
            "description": "Unprocessable Entity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnprocessableDTO"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests - rate limit exceeded; retry after a short delay"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Location-Access": [
              "emails/campaigns.write"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.",
        "type": "http"
      },
      "Location-Access": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.",
        "type": "http"
      },
      "Location-Access-Only": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Sub-Account.",
        "type": "http"
      },
      "Agency-Access": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.",
        "type": "http"
      },
      "Agency-Access-Only": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "name": "Authorization",
        "in": "header",
        "description": "Use the Access Token generated with user type as Agency.",
        "type": "http"
      }
    },
    "schemas": {
      "TestEmailCampaignPublicV3BodyDto": {
        "type": "object",
        "properties": {
          "subject": {
            "type": "string",
            "description": "Subject to use for this request. Omit to use the stored subject; an empty string fails send validation.",
            "example": "Holiday sale starts now"
          },
          "fromName": {
            "type": "string",
            "description": "Sender display name for this request. Defaults to the stored sender name; empty string omits the display name.",
            "example": "Anz Studio"
          },
          "fromEmail": {
            "type": "string",
            "description": "Sender email address for this request. Must be a valid email address. Defaults to the stored fromAddress.",
            "example": "hello@anzstudio.com"
          },
          "emails": {
            "description": "One to 5 recipient addresses (any inbox, for example a QA or client address). Limited to 20 test requests per location per hour.",
            "minItems": 1,
            "maxItems": 5,
            "example": [
              "owner@anzstudio.com"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "userId": {
            "type": "string",
            "description": "Active user of this location the test is sent as (conversations requires one). Defaults to the token user; required when the token has no user (location and MCP tokens), so look it up with Search Users.",
            "example": "wlZTJPotcy10MZxNiwLK"
          },
          "variationIndex": {
            "type": "number",
            "description": "A/B version to test-send: 1 = version B, 2 = version C, ... (see `abVersions` in Get Email Campaign). Omit for version A, the campaign itself. 404 when that version does not exist; nothing is created.",
            "minimum": 1,
            "maximum": 9,
            "example": 1
          }
        },
        "required": [
          "emails"
        ],
        "title": "TestEmailCampaignPublicV3BodyDto"
      },
      "TestEmailPublicV3ResponseDto": {
        "type": "object",
        "properties": {
          "accepted": {
            "type": "boolean",
            "description": "True when the test was accepted for sending. This does not confirm delivery.",
            "example": true
          },
          "recipients": {
            "description": "Recipient addresses the test was sent to.",
            "example": [
              "owner@anzstudio.com"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "note": {
            "type": "string",
            "description": "Delivery caveat.",
            "example": "Accepted for sending; delivery is not confirmed. Merge fields are filled with sample contact data, not the real recipient values."
          }
        },
        "required": [
          "accepted",
          "recipients",
          "note"
        ],
        "title": "TestEmailPublicV3ResponseDto"
      },
      "BadRequestDTO": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 400
          },
          "message": {
            "type": "string",
            "example": "Bad Request"
          }
        },
        "title": "BadRequestDTO"
      },
      "UnauthorizedDTO": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 401
          },
          "message": {
            "type": "string",
            "example": "Invalid token: access token is invalid"
          },
          "error": {
            "type": "string",
            "example": "Unauthorized"
          }
        },
        "title": "UnauthorizedDTO"
      },
      "InvalidLocationDTO": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "description": "HTTP status code for invalid location access",
            "example": 403
          },
          "message": {
            "type": "string",
            "description": "Error message describing the location access failure",
            "example": "The token does not have access to this location"
          }
        },
        "title": "InvalidLocationDTO"
      },
      "NotFoundDTO": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "description": "HTTP status code for not found",
            "example": 404
          },
          "message": {
            "type": "string",
            "description": "Error message describing the not found failure",
            "example": "Not Found"
          },
          "error": {
            "type": "string",
            "description": "Error type identifier",
            "example": "The requested resource was not found"
          }
        },
        "title": "NotFoundDTO"
      },
      "UnprocessableDTO": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 422
          },
          "message": {
            "example": [
              "Unprocessable Entity"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "error": {
            "type": "string",
            "example": "Unprocessable Entity"
          }
        },
        "title": "UnprocessableDTO"
      },
      "InternalServerErrorDTO": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "description": "HTTP status code for an unexpected server error",
            "example": 500
          },
          "message": {
            "type": "string",
            "description": "Error message describing the server failure",
            "example": "Internal Server Error"
          }
        },
        "title": "InternalServerErrorDTO"
      }
    }
  }
}
```

## Code Examples

**cURL**

```bash
curl -L -X POST 'https://services.leadconnectorhq.com/emails/locations/<locationId>/campaigns/emails/<campaignId>/test' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Version: v3' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "subject": "Holiday sale starts now",
  "fromName": "Anz Studio",
  "fromEmail": "hello@anzstudio.com",
  "emails": [
    "owner@anzstudio.com"
  ],
  "userId": "wlZTJPotcy10MZxNiwLK",
  "variationIndex": 1
}'
```

**Node.js**

```javascript
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <TOKEN>',
    Version: 'v3',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "subject": "Holiday sale starts now",
      "fromName": "Anz Studio",
      "fromEmail": "hello@anzstudio.com",
      "emails": [
        "owner@anzstudio.com"
      ],
      "userId": "wlZTJPotcy10MZxNiwLK",
      "variationIndex": 1
  })
};

try {
  const response = await fetch('https://services.leadconnectorhq.com/emails/locations/<locationId>/campaigns/emails/<campaignId>/test', options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**Python**

```python
import requests

url = "https://services.leadconnectorhq.com/emails/locations/{locationId}/campaigns/emails/{campaignId}/test"

headers = {
    "Authorization": "Bearer <TOKEN>",
    "Version": "v3"
}

payload = {
    "subject": "Holiday sale starts now",
    "fromName": "Anz Studio",
    "fromEmail": "hello@anzstudio.com",
    "emails": [
        "owner@anzstudio.com"
    ],
    "userId": "wlZTJPotcy10MZxNiwLK",
    "variationIndex": 1
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

**PHP**

```php
<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://services.leadconnectorhq.com/emails/locations/<locationId>/campaigns/emails/<campaignId>/test',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <TOKEN>',
    'Version: v3',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => '{
  "subject": "Holiday sale starts now",
  "fromName": "Anz Studio",
  "fromEmail": "hello@anzstudio.com",
  "emails": [
    "owner@anzstudio.com"
  ],
  "userId": "wlZTJPotcy10MZxNiwLK",
  "variationIndex": 1
}',
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
```

**Java**

```java
HttpResponse<String> response = Unirest
  .post("https://services.leadconnectorhq.com/emails/locations/<locationId>/campaigns/emails/<campaignId>/test")
  .header("Authorization", "Bearer <TOKEN>")
  .header("Version", "v3")
  .header("Content-Type", "application/json")
  .body("{\"subject\":\"Holiday sale starts now\",\"fromName\":\"Anz Studio\",\"fromEmail\":\"hello@anzstudio.com\",\"emails\":[\"owner@anzstudio.com\"],\"userId\":\"wlZTJPotcy10MZxNiwLK\",\"variationIndex\":1}")
  .asString();
```

**Go**

```go
package main

import (
  "fmt"
  "net/http"
  "io"
  "strings"
)

func main() {
  url := "https://services.leadconnectorhq.com/emails/locations/<locationId>/campaigns/emails/<campaignId>/test"
  payload := strings.NewReader(`{
  "subject": "Holiday sale starts now",
  "fromName": "Anz Studio",
  "fromEmail": "hello@anzstudio.com",
  "emails": [
    "owner@anzstudio.com"
  ],
  "userId": "wlZTJPotcy10MZxNiwLK",
  "variationIndex": 1
}`)
  req, _ := http.NewRequest("POST", url, payload)
  req.Header.Add("Authorization", "Bearer <TOKEN>")
  req.Header.Add("Version", "v3")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  fmt.Println(string(body))
}
```

**Ruby**

```ruby
require 'uri'
require 'net/http'

url = URI("https://services.leadconnectorhq.com/emails/locations/<locationId>/campaigns/emails/<campaignId>/test")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <TOKEN>"
request["Version"] = "v3"
request["Content-Type"] = "application/json"
request.body = '{
  "subject": "Holiday sale starts now",
  "fromName": "Anz Studio",
  "fromEmail": "hello@anzstudio.com",
  "emails": [
    "owner@anzstudio.com"
  ],
  "userId": "wlZTJPotcy10MZxNiwLK",
  "variationIndex": 1
}'

response = http.request(request)
puts response.read_body
```

**PowerShell**

```powershell
$headers = @{
  "Authorization" = "Bearer <TOKEN>"
  "Version" = "v3"
}

$body = '{
  "subject": "Holiday sale starts now",
  "fromName": "Anz Studio",
  "fromEmail": "hello@anzstudio.com",
  "emails": [
    "owner@anzstudio.com"
  ],
  "userId": "wlZTJPotcy10MZxNiwLK",
  "variationIndex": 1
}'

$response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/emails/locations/<locationId>/campaigns/emails/<campaignId>/test' -Method 'POST' -Headers $headers -Body $body -ContentType 'application/json'
$response | ConvertTo-Json
```
