API Reference

Run deliverability tests programmatically. RESTful JSON API with Bearer auth.

Authentication

Two auth methods are supported:

Session Token

Obtained via POST /v1/auth/verify-code. Use in the dashboard or client apps.

API Key

Per-project keys, format: gms_live_.... Use for server-to-server integration.

Authorization: Bearer gms_live_a1b2c3d4e5f6...

Endpoints

POST /v1/public/tests

Create an anonymous test. Returns a test address and public token.

Response 202

{
  "public_token": "abc123xyz789",
  "test_address": "test-abc123xyz789@gomailscore.com",
  "expires_at": "2025-01-16T12:00:00Z"
}

GET /v1/public/tests/{token}

Check test status. Poll until status: "complete".

Response 200

{
  "public_token": "abc123xyz789",
  "status": "complete",
  "created_at": "2025-01-15T12:00:00Z",
  "expires_at": "2025-01-16T12:00:00Z",
  "email_received_at": "2025-01-15T12:01:23Z"
}

GET /v1/public/tests/{token}/details

Full analysis result. Only available when status is complete.

Response 200 (truncated)

{
  "overall_score_100": 85,
  "display_score_10": 8.5,
  "category_scores": {
    "authentication": 100,
    "infrastructure": 75,
    "content": 90
  },
  "auth_results": { "spf": {...}, "dkim": {...}, "dmarc": {...} },
  "infra_findings": [...],
  "content_findings": [...],
  "recommendations": [
    { "priority": "high", "title": "...", "action": "..." }
  ]
}

POST /v1/tests auth required

Create a test assigned to your project. Same response format as public endpoint.

GET /v1/tests auth required

List your project's tests with status and scores.

Status Codes

202 Test created, waiting for email

200 Success

404 Unknown token or resource

410 Expired test token

429 Rate limit exceeded