Log InHome Page

APIs

Placement Test API

Placement tests help you check where your emails land (inbox, spam, or not received) across different email providers. You can create tests, send test emails, and view results.

Get All Placement Tests

Get a list of all placement tests for your organization with filtering, sorting, and pagination.

Query Parameters:

Optional:

  • search - string - Search in test name
  • status - string - Filter by status: pending, sent, completed, failed
  • sortBy - string - Sort field: name, status, createdAt, sent_at, completed_at, score (default: createdAt)
  • sortOrder - string - Sort direction: asc or desc (default: desc)
  • limit - number - Number of records to return (default: 50, max: 100)
  • offset - number - Number of records to skip (default: 0)
curl -X GET 'https://api.supersend.io/v1/placement-tests?status=sent&limit=50&offset=0&sortBy=createdAt&sortOrder=desc' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json"

# Response
{
  "tests": [
    {
      "id": "test-uuid",
      "name": "Q4 Campaign Test",
      "status": "completed",
      "tracking_code": "ss-abc123",
      "score": 85,
      "credit_cost": 10,
      "createdAt": "2025-11-27T10:30:00Z",
      "sent_at": "2025-11-27T10:35:00Z",
      "completed_at": "2025-11-27T10:45:00Z",
      "total_seeds": 10,
      "auto_send": false,
      "results_summary": {
        "inbox": 8,
        "spam": 1,
        "not_received": 1
      },
      "user": {
        "id": "user-uuid",
        "name": "John Doe",
        "email": "john@example.com"
      },
      "sender": {
        "id": "sender-uuid",
        "email": "sales@example.com"
      }
    }
  ],
  "count": 1,
  "limit": 50,
  "offset": 0,
  "hasMore": false
}

Create Placement Test

Create a new placement test. The system automatically selects seed emails from different providers (Hotmail, Tucows, personal) to ensure diversity.

Request Body:

Optional:

  • name - string - Test name (default: "Untitled Test", max: 255 characters)
  • test_email_subject - string - Subject line for test email (max: 255 characters)
  • test_email_body - string - Body content for test email
  • test_email_from - string - From email address
  • seed_count - number - Number of seed emails to use (default: 10, min: 1, max: 50)
  • SenderId - string - Sender UUID to use for the test (optional)
  • auto_send - boolean - Automatically send test emails (default: false)
curl -X POST 'https://api.supersend.io/v1/placement-tests' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Q4 Campaign Test",
  "test_email_subject": "Test Email Subject",
  "test_email_body": "This is a test email body",
  "test_email_from": "sales@example.com",
  "seed_count": 10,
  "SenderId": "sender-uuid",
  "auto_send": false
}'

# Response
{
  "id": "test-uuid",
  "tracking_code": "ss-abc123",
  "name": "Q4 Campaign Test",
  "status": "pending",
  "total_seeds": 10,
  "seed_addresses": [
    {
      "email": "seed1@hotmail.com"
    },
    {
      "email": "seed2@tucows.com"
    }
  ],
  "credit_cost": 10,
  "SenderId": "sender-uuid",
  "auto_send": false,
  "createdAt": "2025-11-27T10:30:00Z"
}

Note: The system automatically selects seed emails with diversity across tags (hotmail, tucows, personal) to ensure comprehensive testing across different email providers.

Get Placement Test

Get detailed information about a specific placement test, including all results.

Path Parameters:

  • id - string (required) - Placement test UUID
curl -X GET 'https://api.supersend.io/v1/placement-tests/<id>' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json"

# Response
{
  "id": "test-uuid",
  "name": "Q4 Campaign Test",
  "tracking_code": "ss-abc123",
  "status": "completed",
  "score": 85,
  "credit_cost": 10,
  "test_email_subject": "Test Email Subject",
  "test_email_from": "sales@example.com",
  "total_seeds": 10,
  "auto_send": false,
  "seed_addresses": [
    {
      "email": "seed1@hotmail.com"
    }
  ],
  "results": {
    "inbox": 8,
    "spam": 1,
    "not_received": 1,
    "placements": [
      {
        "email": "seed1@hotmail.com",
        "placement": "inbox",
        "received_at": "2025-11-27T10:35:00Z",
        "tags": ["hotmail", "personal"]
      },
      {
        "email": "seed2@tucows.com",
        "placement": "spam",
        "received_at": "2025-11-27T10:35:00Z",
        "tags": ["tucows"]
      }
    ]
  },
  "sent_at": "2025-11-27T10:35:00Z",
  "completed_at": "2025-11-27T10:45:00Z",
  "createdAt": "2025-11-27T10:30:00Z",
  "updatedAt": "2025-11-27T10:45:00Z",
  "user": {
    "id": "user-uuid",
    "name": "John Doe",
    "email": "john@example.com"
  },
  "sender": {
    "id": "sender-uuid",
    "email": "sales@example.com"
  },
  "placement_results": [
    {
      "id": "result-uuid",
      "seed_email": "seed1@hotmail.com",
      "placement": "inbox",
      "received_at": "2025-11-27T10:35:00Z",
      "checked_at": "2025-11-27T10:40:00Z",
      "check_attempts": 1,
      "metadata": {},
      "tags": ["hotmail", "personal"]
    }
  ]
}

Get Placement Test Emails

Get all emails sent for a specific placement test, including their status and delivery information.

Path Parameters:

  • id - string (required) - Placement test UUID
curl -X GET 'https://api.supersend.io/v1/placement-tests/<id>/emails' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json"

# Response
{
  "emails": [
    {
      "id": "email-uuid",
      "to_email": "seed1@hotmail.com",
      "subject": "Test Email Subject",
      "status": "sent",
      "email_id": "msg-123",
      "thread_id": "thread-456",
      "sent_at": "2025-11-27T10:35:00Z",
      "error_message": null,
      "attempt_count": 1,
      "sender": {
        "id": "sender-uuid",
        "email": "sales@example.com",
        "send_as": "Sales Team"
      },
      "createdAt": "2025-11-27T10:35:00Z",
      "updatedAt": "2025-11-27T10:35:00Z"
    },
    {
      "id": "email-uuid-2",
      "to_email": "seed2@tucows.com",
      "subject": "Test Email Subject",
      "status": "failed",
      "email_id": null,
      "thread_id": null,
      "sent_at": null,
      "error_message": "Delivery failed",
      "attempt_count": 3,
      "sender": {
        "id": "sender-uuid",
        "email": "sales@example.com",
        "send_as": "Sales Team"
      },
      "createdAt": "2025-11-27T10:35:00Z",
      "updatedAt": "2025-11-27T10:36:00Z"
    }
  ],
  "stats": {
    "total": 10,
    "sent": 8,
    "failed": 1,
    "pending": 1
  }
}

Confirm Test Sent

Mark a placement test as sent. This updates the test status and triggers result checking.

Path Parameters:

  • id - string (required) - Placement test UUID
curl -X POST 'https://api.supersend.io/v1/placement-tests/<id>/confirm-sent' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json"

# Response
{
  "id": "test-uuid",
  "status": "sent",
  "sent_at": "2025-11-27T10:35:00Z",
  "message": "Test marked as sent. Results will be available within 10 minutes."
}

Note: This endpoint can only be called on tests with pending status. Once marked as sent, the system will automatically check results within 10 minutes.

Delete Placement Test

Soft delete a placement test. The test is marked as deleted but not permanently removed.

Path Parameters:

  • id - string (required) - Placement test UUID
curl -X DELETE 'https://api.supersend.io/v1/placement-tests/<id>' \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json"

# Response
{
  "message": "Placement test deleted successfully."
}

Note: Deleted tests are soft-deleted (marked with deleted_at timestamp) and will not appear in the list of placement tests.

Previous
Managed Mailboxes
Next
Team