Skip to content
Docs Sandbox

Sandbox

Build and test for free: test keys, test addresses, simulated results for every verdict, and test bulk jobs.

The sandbox lets you build against the API and the MCP server before you pay for anything. Test addresses at example.com return simulated results for every result type. No real address is checked, nothing is charged, and nothing counts toward your usage.

Who gets it

  • Every account can create test keys on the API keys page of the dashboard.
  • Free accounts get test keys only. Live keys come with a plan or a credit pack.
  • Free accounts that sign in from an AI app get a sandbox connection. It answers the same test addresses and turns live as soon as the account has a plan or a credit pack. There is nothing to reconnect.
  • Paying accounts keep their live keys and can also create test keys.

Test keys

A test key starts with eva_test_ followed by 64 hex characters. You choose Live or Test when you create a key. A key cannot switch afterwards: create a new one instead.

A Free account can hold up to 3 test keys. A paying account can hold up to 5 test keys next to its live keys. Any account can create up to 20 test keys in 24 hours, revoked ones included. Use a test key exactly like a live one:

test-call.sh
curl "https://api.kavik.email/api/v1/verify?email=safe@example.com" \
  -H "X-API-Key: eva_test_your_key"

The same endpoints work: single and batch verification, domain deliverability, domain authentication, bulk jobs and GET /api/v1/account. Only the answers are simulated.

Test addresses

Every address below is at example.com. The local part picks the result. Case does not matter, and a +tag is allowed: safe+one@example.com answers like safe@example.com, with has_sub_addressing set to true and sub_address_base filled in.

Each body below is the full answer a test key receives, "livemode": false included. See livemode.

Address risk What it simulates
safe@example.com safe A plain deliverable mailbox.
free_provider@example.com safe A mailbox at a free provider. is_free_provider is true.
role@example.com safe A role address such as info@. is_role_account is true.
catch_all@example.com catchall The domain accepts every address. Never billed on a live key.
full_inbox@example.com risky The mailbox is full. is_full_inbox is true.
spam_trap@example.com safe Score 74 with spam_trap_risk set to high. The verdict stays safe, so read the risk field as well.
disposable@example.com risky A disposable address. is_disposable is true.
mailbox_not_found@example.com invalid The mail server says the mailbox does not exist.
disabled@example.com invalid The account is disabled. is_disabled is true.
no_mx@example.com invalid The domain has no mail server. mx_found is false.
typo@example.com invalid A domain typo. suggested_correction holds typo@gmail.com.
greylisted@example.com unknown The mail server asked for a later retry. Never billed on a live key.
slow@example.com safe A slow mail server. response_latency_ms is 4800. See the MCP note below.

The full answer for each address:

safe@example.com

{}safe.json
{
  "data": {
    "email": "safe@example.com",
    "score": 99,
    "risk": "safe",
    "syntax_valid": true,
    "mx_found": true,
    "smtp_check": "deliverable",
    "is_disposable": false,
    "is_watchlisted": false,
    "is_role_account": false,
    "is_catch_all": false,
    "is_free_provider": false,
    "is_b2b": false,
    "spam_trap_risk": "low",
    "has_sub_addressing": false,
    "suggested_correction": null,
    "mx_records": [
      "mx1.example.com",
      "mx2.example.com"
    ],
    "livemode": false
  }
}

free_provider@example.com

{}free_provider.json
{
  "data": {
    "email": "free_provider@example.com",
    "score": 99,
    "risk": "safe",
    "syntax_valid": true,
    "mx_found": true,
    "smtp_check": "deliverable",
    "is_disposable": false,
    "is_watchlisted": false,
    "is_role_account": false,
    "is_catch_all": false,
    "is_free_provider": true,
    "is_b2b": false,
    "spam_trap_risk": "low",
    "has_sub_addressing": false,
    "suggested_correction": null,
    "mx_records": [
      "mx1.example.com",
      "mx2.example.com"
    ],
    "livemode": false
  }
}

role@example.com

{}role.json
{
  "data": {
    "email": "role@example.com",
    "score": 94,
    "risk": "safe",
    "syntax_valid": true,
    "mx_found": true,
    "smtp_check": "deliverable",
    "is_disposable": false,
    "is_watchlisted": false,
    "is_role_account": true,
    "is_catch_all": false,
    "is_free_provider": false,
    "is_b2b": false,
    "spam_trap_risk": "low",
    "has_sub_addressing": false,
    "suggested_correction": null,
    "mx_records": [
      "mx1.example.com",
      "mx2.example.com"
    ],
    "livemode": false
  }
}

catch_all@example.com

{}catch_all.json
{
  "data": {
    "email": "catch_all@example.com",
    "score": 69,
    "risk": "catchall",
    "reason": "catch_all",
    "syntax_valid": true,
    "mx_found": true,
    "smtp_check": "deliverable",
    "is_disposable": false,
    "is_watchlisted": false,
    "is_role_account": false,
    "is_catch_all": true,
    "is_free_provider": false,
    "is_b2b": false,
    "spam_trap_risk": "low",
    "has_sub_addressing": false,
    "suggested_correction": null,
    "mx_records": [
      "mx1.example.com",
      "mx2.example.com"
    ],
    "livemode": false
  }
}

full_inbox@example.com

{}full_inbox.json
{
  "data": {
    "email": "full_inbox@example.com",
    "score": 50,
    "risk": "risky",
    "reason": "full_inbox",
    "syntax_valid": true,
    "mx_found": true,
    "smtp_check": "risky",
    "is_disposable": false,
    "is_watchlisted": false,
    "is_role_account": false,
    "is_catch_all": false,
    "is_free_provider": false,
    "is_b2b": false,
    "spam_trap_risk": "low",
    "has_sub_addressing": false,
    "suggested_correction": null,
    "mx_records": [
      "mx1.example.com",
      "mx2.example.com"
    ],
    "is_full_inbox": true,
    "livemode": false
  }
}

spam_trap@example.com

{}spam_trap.json
{
  "data": {
    "email": "spam_trap@example.com",
    "score": 74,
    "risk": "safe",
    "syntax_valid": true,
    "mx_found": true,
    "smtp_check": "deliverable",
    "is_disposable": false,
    "is_watchlisted": false,
    "is_role_account": false,
    "is_catch_all": false,
    "is_free_provider": false,
    "is_b2b": false,
    "spam_trap_risk": "high",
    "has_sub_addressing": false,
    "suggested_correction": null,
    "mx_records": [
      "mx1.example.com",
      "mx2.example.com"
    ],
    "livemode": false
  }
}

disposable@example.com

{}disposable.json
{
  "data": {
    "email": "disposable@example.com",
    "score": 45,
    "risk": "risky",
    "reason": "disposable",
    "syntax_valid": true,
    "mx_found": true,
    "smtp_check": "deliverable",
    "is_disposable": true,
    "is_watchlisted": false,
    "is_role_account": false,
    "is_catch_all": false,
    "is_free_provider": false,
    "is_b2b": false,
    "spam_trap_risk": "low",
    "has_sub_addressing": false,
    "suggested_correction": null,
    "mx_records": [
      "mx1.example.com",
      "mx2.example.com"
    ],
    "livemode": false
  }
}

mailbox_not_found@example.com

{}mailbox_not_found.json
{
  "data": {
    "email": "mailbox_not_found@example.com",
    "score": 8,
    "risk": "invalid",
    "reason": "mailbox_not_found",
    "syntax_valid": true,
    "mx_found": true,
    "smtp_check": "undeliverable",
    "is_disposable": false,
    "is_watchlisted": false,
    "is_role_account": false,
    "is_catch_all": false,
    "is_free_provider": false,
    "is_b2b": false,
    "spam_trap_risk": "low",
    "has_sub_addressing": false,
    "suggested_correction": null,
    "mx_records": [
      "mx1.example.com",
      "mx2.example.com"
    ],
    "livemode": false
  }
}

disabled@example.com

{}disabled.json
{
  "data": {
    "email": "disabled@example.com",
    "score": 3,
    "risk": "invalid",
    "reason": "disabled",
    "syntax_valid": true,
    "mx_found": true,
    "smtp_check": "undeliverable",
    "is_disposable": false,
    "is_watchlisted": false,
    "is_role_account": false,
    "is_catch_all": false,
    "is_free_provider": false,
    "is_b2b": false,
    "spam_trap_risk": "low",
    "has_sub_addressing": false,
    "suggested_correction": null,
    "mx_records": [
      "mx1.example.com",
      "mx2.example.com"
    ],
    "is_disabled": true,
    "livemode": false
  }
}

no_mx@example.com

{}no_mx.json
{
  "data": {
    "email": "no_mx@example.com",
    "score": 5,
    "risk": "invalid",
    "reason": "no_mx",
    "syntax_valid": true,
    "mx_found": false,
    "smtp_check": "unknown",
    "is_disposable": false,
    "is_watchlisted": false,
    "is_role_account": false,
    "is_catch_all": false,
    "is_free_provider": false,
    "is_b2b": false,
    "spam_trap_risk": "low",
    "has_sub_addressing": false,
    "suggested_correction": null,
    "mx_records": [],
    "livemode": false
  }
}

typo@example.com

{}typo.json
{
  "data": {
    "email": "typo@example.com",
    "score": 5,
    "risk": "invalid",
    "reason": "no_mx",
    "syntax_valid": true,
    "mx_found": false,
    "smtp_check": "unknown",
    "is_disposable": false,
    "is_watchlisted": false,
    "is_role_account": false,
    "is_catch_all": false,
    "is_free_provider": false,
    "is_b2b": false,
    "spam_trap_risk": "low",
    "has_sub_addressing": false,
    "suggested_correction": "typo@gmail.com",
    "mx_records": [],
    "livemode": false
  }
}

greylisted@example.com

{}greylisted.json
{
  "data": {
    "email": "greylisted@example.com",
    "score": 55,
    "risk": "unknown",
    "reason": "greylisted",
    "syntax_valid": true,
    "mx_found": true,
    "smtp_check": "unknown",
    "is_disposable": false,
    "is_watchlisted": false,
    "is_role_account": false,
    "is_catch_all": false,
    "is_free_provider": false,
    "is_b2b": false,
    "spam_trap_risk": "low",
    "has_sub_addressing": false,
    "suggested_correction": null,
    "mx_records": [
      "mx1.example.com",
      "mx2.example.com"
    ],
    "livemode": false
  }
}

slow@example.com

{}slow.json
{
  "data": {
    "email": "slow@example.com",
    "score": 99,
    "risk": "safe",
    "syntax_valid": true,
    "mx_found": true,
    "smtp_check": "deliverable",
    "is_disposable": false,
    "is_watchlisted": false,
    "is_role_account": false,
    "is_catch_all": false,
    "is_free_provider": false,
    "is_b2b": false,
    "spam_trap_risk": "low",
    "has_sub_addressing": false,
    "suggested_correction": null,
    "mx_records": [
      "mx1.example.com",
      "mx2.example.com"
    ],
    "response_latency_ms": 4800,
    "livemode": false
  }
}

A malformed entry, such as not-an-email, gets the same syntax answer a live key gives. It carries no deliverability or domain_age enrichment.

Domain deliverability

GET /api/v1/domain/example.com/deliverability returns one healthy report. Any other domain is refused (see What is refused).

{}deliverability.json
{
  "data": {
    "domain": "example.com",
    "score": 100,
    "grade": "A",
    "authentication": {
      "spf": {
        "found": true,
        "record": "v=spf1 include:_spf.example.com -all",
        "strictness": "strict",
        "include_count": 1
      },
      "dkim": {
        "found": true,
        "selectors": [
          "default"
        ]
      },
      "dmarc": {
        "found": true,
        "record": "v=DMARC1; p=reject; rua=mailto:dmarc@example.com",
        "policy": "reject"
      }
    },
    "blacklist": {
      "listed": false,
      "listed_count": 0,
      "total_checks": 12,
      "high_confidence_count": 0,
      "evaluated_checks": 12
    },
    "transport_security": {
      "mta_sts": true,
      "tls_rpt": true,
      "bimi": false
    },
    "has_mx": true,
    "checked_at": "2026-01-01T00:00:00Z",
    "livemode": false
  }
}

checked_at is the time of your request.

Domain authentication

GET /api/v1/domain/example.com/audit returns one healthy report. Any other domain is refused (see What is refused).

{}domain-audit-sandbox.json
{
  "data": {
    "domain": "example.com",
    "checked_at": "2026-01-01T00:00:00Z",
    "status": "pass",
    "counts": {
      "critical": 0,
      "warning": 0,
      "info": 0
    },
    "incomplete": [],
    "spf": {
      "status": "pass",
      "record": "v=spf1 include:_spf.example.com -all",
      "lookups": {
        "count": 1,
        "limit": 10,
        "void": 0,
        "void_limit": 2,
        "partial": false
      },
      "all": "-all",
      "ip4_addresses": 256,
      "ip6_prefixes": 1,
      "tree": [
        {
          "term": "include:_spf.example.com",
          "domain": "_spf.example.com",
          "lookups": 1
        }
      ]
    },
    "findings": [],
    "livemode": false
  }
}

checked_at is the time of your request.

Error triggers

Three more local parts return errors, so you can test your error handling. The status and body are the ones a live key gives. The header values are simulated.

Address Status code Simulated headers
quota_exceeded@example.com 429 QUOTA_EXCEEDED X-RateLimit-Limit: 20000, X-RateLimit-Remaining: 0, X-RateLimit-Reset one month out
rate_limited@example.com 429 RATE_LIMITED X-RateLimit-Limit: 60, X-RateLimit-Remaining: 0, X-RateLimit-Reset, Retry-After: 60
server_error@example.com 500 INTERNAL_ERROR none
{}quota_exceeded.json
{"error": "monthly quota exceeded; purchase credit packs to continue", "code": "QUOTA_EXCEEDED"}

In a batch or a bulk file, one error trigger fails the whole call in the same way. A bulk file that holds rate_limited@example.com answers 429, which a live bulk upload never does. Use it to test your retry code, and expect live bulk to answer with the codes in Errors.

What is refused

A test key answers example.com test addresses only. Everything else is refused, and nothing is looked up.

Status code When
403 LIVE_KEY_REQUIRED A test key was used on a real address or a real domain. A list is refused whole if it holds one real address.
403 PAID_PLAN_REQUIRED A live key on an account with no plan and no credits. Also a sandbox AI-app connection used on a real address or domain.
400 INVALID_INPUT An address at example.com that is not on the list above.
400 INVALID_INPUT A bulk file with more than 1,000 rows.
{}live-key-required.json
{"error": "jane@acmecorp.com is a real address, and this is a test key. Test keys answer the sandbox test addresses at example.com only. Live keys come with a plan or a credit pack: https://kavik.email/dashboard/billing. Test addresses: https://kavik.email/docs/sandbox/", "code": "LIVE_KEY_REQUIRED"}

On an account that already pays, the message points to your live keys at https://kavik.email/dashboard/keys instead of billing. A sandbox connection gets PAID_PLAN_REQUIRED with similar text, and it adds that the connection turns live as soon as the account has a plan or a credit pack.

{}invalid-input.json
{"error": "hello@example.com is not a sandbox test address. The list is at https://kavik.email/docs/sandbox/", "code": "INVALID_INPUT"}

Bulk jobs and webhooks

Bulk jobs use the same endpoints as live ones: upload, poll and fetch results. The rows are test addresses from the table above.

  • Timing. A job reads pending for its first second, then processing. It takes 20 ms a row, at least 3 seconds, so a 1,000-row file finishes in 20 seconds.
  • Size. Up to 1,000 rows a file. A longer file is refused.
  • Storage. Test jobs and their rows are deleted after 24 hours.
  • No rerun wait. POST /api/v1/verify/async/{id}/rerun-unknowns works as soon as a job has finished. The 30-minute wait of live jobs does not apply. A job that has not finished, or one with no unknown results, answers 400 INVALID_INPUT with the message a live job gets.
  • Dashboard. Test jobs and their webhook deliveries are not listed on the Lists and Webhooks pages of the dashboard. Use the API to see them.

A test job with a webhook_url fires bulk_job.completed when it finishes. The payload has the same fields as a live one, with "livemode": false:

{}webhook.json
{
  "event": "bulk_job.completed",
  "job_id": "5b0c8f2e-3a41-4d6e-9f27-8c1d2e7a9b10",
  "status": "completed",
  "total_count": 3,
  "completed_count": 3,
  "summary": {"safe": 2, "risky": 0, "catchall": 0, "invalid": 1, "unknown": 0},
  "result_url": "https://api.kavik.email/api/v1/verify/async/5b0c8f2e-3a41-4d6e-9f27-8c1d2e7a9b10/result",
  "timestamp": "2026-11-14T10:00:00Z",
  "livemode": false
}

The X-EVA-Signature header signs the body with your Test signing secret, shown on the Webhooks page of the dashboard. It is derived from your live secret, so regenerating the live secret changes it too. A test delivery never verifies against the live secret, so a leaked test key cannot forge a live webhook.

A test webhook fires at most once per job. That one delivery makes 3 attempts, and a restart can drop one that is in flight. Poll the job if you need certainty.

Slow addresses over MCP

On the MCP server, slow@example.com plays out a slow mail server. The first call replies checking and the next call for it returns the answer, as it does for a slow live server. The mark lasts 60 seconds, so a call after that replies checking again. All slow+tag@example.com addresses on one key share one mark: the first call among them says checking and the next call says the answer. On the REST API, slow@example.com answers safe at once.

Limits

Limit Value
Requests 60 a minute per account. Every sandbox request counts 1, including bulk calls. A batch counts 1.
Rows in a test file 1,000
Test jobs running at once 3
Test jobs created an hour 20
Retention Test jobs and rows are deleted after 24 hours
Test keys 3 on a Free account, 5 on a paying account. Up to 20 created in 24 hours

Past 60 requests in a minute a test key gets 429 RATE_LIMITED with the usual X-RateLimit-* and Retry-After headers. Too many running jobs, or too many jobs in an hour, returns 429 BULK_LIMIT_EXCEEDED.

GET /api/v1/account shows these limits for a test key under sandbox. See Account.

livemode

Every successful response object, on the API and over MCP, carries livemode: true for a live key and false for a test key. Error bodies do not. Check it in code that handles both. CSV and Excel downloads do not carry it.

Going live

Buy a plan or a credit pack at kavik.email/pricing. Then create a live key on the API keys page and swap it into your code. The endpoints, fields and error shapes stay the same. A sandbox AI-app connection turns live by itself.