API
22 articles
API keys, rate limits, endpoints, and code examples.
- API overview: endpoints, auth, response format, and rate limits at a glanceValid Email Checker's REST API. Base URL, the three endpoints, Bearer-token auth, response shape, status values, error codes, and the 60/min + 10k/day rate limits.
- API rate limits and error handling: every status code explainedPer-endpoint rate limits, response headers, every HTTP error code returned by the Valid Email Checker API, and code patterns for graceful error handling and exponential backoff.
- Bulk verification endpoint: submit a list, poll for resultsPOST /api/verify-bulk creates a task and returns a task_id. GET /api/get-results/{task_id} returns status and results when ready. Up to 1,000,000 emails per task. 15-day retention.
- Can I monitor API usage from the dashboard?Yes. The Developer page shows per-key credits used in the Your API Keys table, and Credits History lists every API verification with timestamps, endpoints, and per-bucket deductions. There is no real-time graph yet, but ledger data is exhaustive.
- Can I rename an API key after creating it?Yes. Open the Developer page in Valid Email Checker, click the three-dot menu next to the key, and choose Rename. The key value and credits-used history stay intact — only the friendly label changes. Names must be unique within your account.
- Does the API consume from monthly credits first?Yes. Valid Email Checker API requests deduct from your monthly subscription bucket first, then rollover, then Pay-As-You-Go. The order is identical to dashboard verifications and cannot be overridden per-request.
- Generating and managing API keysCreate your first API key from the Developer page after your first credit purchase. Confirm with a 6-digit email code. Rename, regenerate, disable, or delete any key.
- How do I authenticate Valid Email Checker API requests?Authentication is a Bearer token in the Authorization header. Format: Authorization: Bearer VEC<32 chars>. The header is required on every endpoint. Missing or malformed headers return 401 with a clear error message.
- How do I get a Valid Email Checker API key?API access unlocks after your first credit purchase. Then generate keys from the Developer page in your dashboard. Each key starts with "VEC", is shown exactly once at creation, and is stored SHA-256 hashed on our side.
- How do I open the API Access page in the dashboard?The API Access page in Valid Email Checker is labeled "Developer" in the left sidebar. It sits between Buy Credits and Account Settings, and only account owners can see it — team members do not.
- How do I verify a single email with the API?POST to https://app.validemailchecker.com/api/verify-single with your API key in the Authorization header and a JSON body containing the email. Response includes status, confidence score, and detailed flags. 1 credit per call.
- How does the API key prefix identify Valid Email Checker keys?Every Valid Email Checker API key starts with the three-letter prefix "VEC" (no underscore). The prefix is followed by 32 random characters from a confusable-free alphabet, giving a total length of 35 characters. Keys that do not start with VEC are not ours.
- Single verification endpoint: real-time email verificationPOST /api/verify-single returns a verification result in ~1–3 seconds. Bearer-token auth, JSON request, JSON response with status, risk_score, and detailed flags. 1 credit per call.
- What error code does the API return when out of credits?When your account has zero verifiable credits across all buckets, the Valid Email Checker API returns HTTP 402 Payment Required with an Insufficient credits message and the current balance. The same code applies to verify-single and verify-bulk.
- What error code does the API return when rate-limited?Rate-limit hits return HTTP 429 Too Many Requests with a JSON body that includes the limit, window, current count, and retry_after_seconds. The Retry-After header and X-RateLimit-* headers tell you exactly when to retry.
- What error code does the API return when the key is revoked?A revoked (disabled), suspended, or admin-flagged API key returns HTTP 403 Forbidden with an "API key is suspended" message. The Valid Email Checker API never returns a 401 for revoked keys — 403 is the signal that the key existed but is no longer authorized.
- What happens to in-flight verifications when an API key is revoked?Already-running verifications complete normally — VEC checks the key at the start of each request, not mid-flight. Requests that arrive after revocation get 403. Bulk tasks created before revocation continue to process, but you cannot poll results with the revoked key.
- What is the maximum number of active API keys I can have?Valid Email Checker does not cap the number of active API keys per account. Generate as many as you need — one per environment, one per integration, one per teammate. All keys on the same account share the rate-limit envelope and the same credit pool.
- What is the Valid Email Checker API endpoint URL?The Valid Email Checker API lives at https://app.validemailchecker.com/api/ — there is no separate api. subdomain. The three endpoints are /api/verify-single, /api/verify-bulk, and /api/get-results/{task_id}.
- What is the Valid Email Checker API rate limit?Per-minute limits: 60 requests for /verify-single and /verify-bulk, 120 requests for /get-results. Daily limit: 10,000 requests per account. Rate limits return HTTP 429 with a Retry-After header.
- What's the difference between revoking and deleting an API key?Revoke (disable) marks an API key inactive but keeps the row and its usage history in your account. Delete soft-removes the key from view permanently. Both stop the key from authenticating new requests immediately.
- Which credit bucket does the API consume from (monthly or PAYG)?Valid Email Checker API calls consume from the same buckets as the dashboard: monthly subscription credits first, then rollover credits, then Pay-As-You-Go. The deduction order is identical regardless of whether the call comes from the dashboard, the API, or an integration.
Can't find what you're looking for? Email support or send us a message.
