Navigation
SuperSend

Placement Test API

Interfaces to manage email placement tests


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.

ℹ️

V2 API Available

V2 provides standardized responses for placement test endpoints.

List Placement Tests

Get all placement tests for your organization.

V2 API (Recommended)

bash
curl -X GET 'https://api.supersend.io/v2/placement-tests?team_id=xxx&sender_id=yyy&status=completed&search=Q4&sort_by=created_at&sort_order=desc&include_summary=true&limit=20' \
  -H "Authorization: Bearer YOUR_API_KEY"
# Response (200 OK)
{
  "success": true,
  "data": [
    {
      "object": "placement_test",
      "id": "test-uuid",
      "name": "Q4 Campaign Test",
      "status": "completed",
      "tracking_code": "ss-abc123",
      "score": 85,
      "credit_cost": 10,
      "total_seeds": 10,
      "auto_send": false,
      "is_auto_test": false,
      "results_summary": {
        "inbox": 8,
        "spam": 1,
        "not_received": 1
      },
      "sender": {
        "id": "sender-uuid",
        "email": "sales@example.com",
        "provider": "smtp"
      },
      "created_by": {
        "id": "user-uuid",
        "name": "John Doe",
        "email": "john@example.com"
      },
      "sent_at": "2025-11-27T10:35:00Z",
      "completed_at": "2025-11-27T10:45:00Z",
      "created_at": "2025-11-27T10:30:00Z",
      "updated_at": "2025-11-27T10:45:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 20,
    "offset": 0,
    "has_more": false
  },
  "summary": {
    "total_tests": 25,
    "completed_tests": 20,
    "average_score": 82.5,
    "tests_this_month": 5,
    "last_test": {
      "id": "test-uuid",
      "name": "Q4 Campaign Test",
      "score": 85,
      "status": "completed",
      "created_at": "2025-11-27T10:30:00Z"
    }
  },
  "request_id": "req_a1b2c3d4e5f6789012345678"
}

V2 Query Parameters:

ParameterTypeRequiredDescription
team_idstringNoFilter by team ID
sender_idstringNoFilter by sender ID
statusstringNoFilter by status: pending, sending, sent, completed, failed
searchstringNoSearch in test name
sort_bystringNoSort field: created_at, name, status, score (default: created_at)
sort_orderstringNoSort direction: asc or desc (default: desc)
include_summarybooleanNoInclude summary statistics (default: true)
limitnumberNoResults per page (default: 50, max: 100)
offsetnumberNoPagination offset (default: 0)


V1 API

bash
curl -X GET 'https://api.supersend.io/v1/placement-tests?status=sent&limit=50&sortBy=createdAt&sortOrder=desc' \
  -H "Authorization: Bearer YOUR_API_KEY"
# Response
{
  "tests": [...],
  "count": 1,
  "limit": 50,
  "offset": 0,
  "hasMore": false
}

V1 Query Parameters:

  • search - Search in test name

  • status - Filter: pending, sent, completed, failed

  • sortBy - Sort field: name, status, createdAt, score

  • sortOrder - asc or desc

  • limit - Results per page (default: 50)

  • offset - Pagination offset

    • Get Placement Test

    Get detailed information about a specific test.

    V2 API (Recommended)

    bash
    curl -X GET 'https://api.supersend.io/v2/placement-tests/test-uuid' \
      -H "Authorization: Bearer YOUR_API_KEY"
    # Response (200 OK)
    {
      "success": true,
      "data": {
        "object": "placement_test",
        "id": "test-uuid",
        "name": "Q4 Campaign Test",
        "status": "completed",
        "tracking_code": "ss-abc123",
        "score": 85,
        "credit_cost": 10,
        "total_seeds": 10,
        "auto_send": false,
        "test_email_subject": "Test Email Subject",
        "test_email_from": "sales@example.com",
        "seed_addresses": [
          {
            "email": "seed1@hotmail.com"
          },
          {
            "email": "seed2@gmail.com"
          }
        ],
        "results_summary": {
          "inbox": 8,
          "spam": 1,
          "not_received": 1
        },
        "placement_results": [
          {
            "id": "result-uuid",
            "seed_email": "seed1@hotmail.com",
            "placement": "inbox",
            "received_at": "2025-11-27T10:35:00Z",
            "checked_at": "2025-11-27T10:36:00Z",
            "check_attempts": 1,
            "metadata": {},
            "tags": []
          },
          {
            "id": "result-uuid-2",
            "seed_email": "seed2@gmail.com",
            "placement": "spam",
            "received_at": null,
            "checked_at": "2025-11-27T10:36:00Z",
            "check_attempts": 2,
            "metadata": {},
            "tags": []
          }
        ],
        "sender": {
          "id": "sender-uuid",
          "email": "sales@example.com",
          "provider": "smtp"
        },
        "created_by": {
          "id": "user-uuid",
          "name": "John Doe",
          "email": "john@example.com"
        },
        "sent_at": "2025-11-27T10:35:00Z",
        "completed_at": "2025-11-27T10:45:00Z",
        "created_at": "2025-11-27T10:30:00Z",
        "updated_at": "2025-11-27T10:45:00Z"
      },
      "request_id": "req_a1b2c3d4e5f6789012345678"
    }

    V1 API

    bash
    curl -X GET 'https://api.supersend.io/v1/placement-tests/test-uuid' \
      -H "Authorization: Bearer YOUR_API_KEY"

    Create Placement Test

    Create a new placement test. The system automatically selects seed emails from different providers.

    V2 API (Recommended)

    bash
    curl -X POST 'https://api.supersend.io/v2/placement-tests' \
      -H "Authorization: Bearer YOUR_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,
        "sender_id": "sender-uuid",
        "team_id": "team-uuid",
        "auto_send": false
      }'
    # Response (201 Created)
    {
      "success": true,
      "data": {
        "object": "placement_test",
        "id": "test-uuid",
        "name": "Q4 Campaign Test",
        "status": "pending",
        "tracking_code": "ss-abc123",
        "total_seeds": 10,
        "credit_cost": 10,
        "auto_send": false,
        "sender_id": "sender-uuid",
        "team_id": "team-uuid",
        "seed_addresses": [
          { "email": "seed1@hotmail.com" },
          { "email": "seed2@tucows.com" }
        ],
        "created_at": "2025-11-27T10:30:00Z"
      },
      "request_id": "req_a1b2c3d4e5f6789012345678"
    }

    V2 Create Parameters:

    ParameterTypeRequiredDescription
    namestringNoTest name (default: "Untitled Test", max: 255 chars)
    test_email_subjectstringNoEmail subject line
    test_email_bodystringNoEmail body content
    test_email_fromstringNoFrom email address
    seed_countnumberNoNumber of seed addresses (1-50, default: 10)
    sender_idstringNoSender ID to use for test (UUID or null)
    team_idstringNoTeam ID (UUID or null)
    auto_sendbooleanNoAutomatically send test email (default: false)


    Note: Seed addresses are automatically selected from different email providers (Gmail, Outlook, Yahoo, etc.).

    V1 API

    bash
    curl -X POST 'https://api.supersend.io/v1/placement-tests' \
      -H "Authorization: Bearer YOUR_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",
        "seed_count": 10
      }'

    Request Fields

    FieldTypeRequiredDescription
    namestringNoTest name (default: "Untitled Test")
    test_email_subjectstringNoSubject line for test email
    test_email_bodystringNoBody content for test email
    test_email_fromstringNoFrom email address
    seed_countnumberNoNumber of seeds (default: 10, max: 50)
    SenderIdstringNoSender UUID to use
    auto_sendbooleanNoAuto-send test emails (default: false)


    Understanding Results

    Placement Status

    StatusDescription
    pendingTest created, awaiting send
    sentTest emails sent, checking results
    completedResults available
    failedTest failed to complete


    Placement Types

    PlacementDescription
    inboxEmail landed in inbox
    spamEmail landed in spam/junk
    not_receivedEmail not found


    Score Calculation

    The score is calculated as: (inbox_count / total_seeds) * 100

    A score of 85+ is generally considered good.

    Confirm Test Sent (V1 Only)

    Mark a placement test as sent. This triggers result checking.

    bash
    curl -X POST 'https://api.supersend.io/v1/placement-tests/test-uuid/confirm-sent' \
      -H "Authorization: Bearer YOUR_API_KEY"
    # 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."
    }

    Get Test Emails (V1 Only)

    Get all emails sent for a specific placement test.

    bash
    curl -X GET 'https://api.supersend.io/v1/placement-tests/test-uuid/emails' \
      -H "Authorization: Bearer YOUR_API_KEY"
    # Response
    {
      "emails": [
        {
          "id": "email-uuid",
          "to_email": "seed1@hotmail.com",
          "subject": "Test Email Subject",
          "status": "sent",
          "sent_at": "2025-11-27T10:35:00Z"
        }
      ],
      "stats": {
        "total": 10,
        "sent": 8,
        "failed": 1,
        "pending": 1
      }
    }

    Delete Placement Test (V1 Only)

    Soft delete a placement test.

    bash
    curl -X DELETE 'https://api.supersend.io/v1/placement-tests/test-uuid' \
      -H "Authorization: Bearer YOUR_API_KEY"
    # Response
    {
      "message": "Placement test deleted successfully."
    }

    V1 vs V2 Endpoint Mapping

    ActionV1 EndpointV2 Endpoint
    ListGET /v1/placement-testsGET /v2/placement-tests
    GetGET /v1/placement-tests/:idGET /v2/placement-tests/:id
    CreatePOST /v1/placement-testsPOST /v2/placement-tests
    Confirm SentPOST /v1/placement-tests/:id/confirm-sentNot available
    Get EmailsGET /v1/placement-tests/:id/emailsNot available
    DeleteDELETE /v1/placement-tests/:idNot available