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

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

bash

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

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

bash

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"
}

Get Placement Test

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

bash

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"]
    }
  ]
}

bash

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
  }
}

bash

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."
}

Get Placement Test Emails

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

bash

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."
}

Confirm Test Sent

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.