---
title: "Schedule email validation"
method: POST
path: "/v3/email-validations/schedule"
tags: ["Email Validations"]
---

# Schedule email validation

`POST /v3/email-validations/schedule`

<small>_Requires the `contacts:operate` scope (or a broader one that includes it)._</small>

Schedules an asynchronous email-validation job for the supplied contact IDs. Returns `202 Accepted` with a `Location` header pointing at `/v3/background-jobs/{jobId}` — poll that endpoint for status and the eventual result.

The eligibility filter (team scope + `RequiresValidation` status) and the credits cap applied here mirror the `/estimate` semantics. Set `acceptPartial = true` to schedule whatever credits allow when the team's balance is below the eligible count.

## Request body

- object — Request body shared by both `/estimate` and `/schedule`. Specifies the contacts to validate and an optional partial-credit acceptance flag.
  - `contactIds` integer[], required — Contact IDs to validate. Must be non-empty, contain at most 10000 items, and every value must be a positive integer.
  - `acceptPartial` boolean, nullable — When `true`, the schedule call proceeds with `min(eligibleCount, creditsAvailable)` contacts even if available credits are below the eligible count. When `false` (default), insufficient credits become a `NotEnoughCredits` blocker on `/estimate` and a `400` on `/schedule`.

## Response `202`

Job scheduled successfully

- object — Acknowledgement returned by `/v3/email-validations/schedule`. The `jobId` corresponds to a background job — poll `/v3/background-jobs/{jobId}` for status and result.
  - `jobId` string, uuid — Background-job identifier — use with `/v3/background-jobs/{jobId}` to poll status
  - `scheduledCount` integer — Number of contacts scheduled for validation (capped by available credits when `acceptPartial = true`)
  - `creditsReserved` integer — Credits held against the team's quota for this job. Released for any contacts whose validation does not succeed.

## Other responses

- `400` — Validation failure on the request body, or a business rule rejection (no eligible contacts, insufficient credits with `acceptPartial = false`, etc.).
- `401` — Unauthorized. The response body is empty; check the `WWW-Authenticate` header for the expected scheme.
- `403` — Email validation is forbidden — feature disabled, missing addon, or the request includes contacts the user does not have scope to validate.
- `409` — Another email-validation job is already running for this user
- `429` — Too Many Requests
- `503` — Background-jobs service is temporarily unavailable

---

[API](https://skmtc.net/reply/apis/reply-api.md) · [All operations](https://skmtc.net/reply/apis/reply-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/reply/reply-api/revisions/1c3d32eaf95e/schema)