How to Recover a Failed Email Import in Velveteen
Updated August 11, 2026
A failed email import does not have a retry action in Velveteen. First check whether the worker is still recoverable: a stale running lease is reclaimed automatically and resumes staged rows from its checkpoint. If the job is already failed, or rows reached the five-attempt limit, run a new CSV dry run with the source corrected and review it again.
Email import recovery depends on the job state. Use Reviewing email imports for the administrator dry-run and review steps, then use the path below when the execution worker reports a problem.
How do I tell whether an import will recover automatically?
A job with status running can be reclaimed only after its lease expires. The worker gives a claimed job a 30-minute lease and records its row and batch checkpoints. A later run can claim an expired job, append a lease_reclaimed audit action, and process the remaining staged rows.
Tip
What should I do when the job is failed?
- 1
Check the import state and counts
In Dashboard, Email administration, Imports, check the job status and its accepted, skipped, failed, and remaining counts. The operations view also shows the checkpoint row, checkpoint batch, and attempt count without exposing source filenames, row addresses, or import IDs. - 2
Review the source and failure boundary
Treat rows marked failed as unresolved. A row that exceeds the execution attempt limit is marked failed withimport_row_attempt_limit; a checkpoint failure is reported as a source or checkpoint problem rather than silently completing the job. - 3
Run a new dry run
Correct the documented CSV or its consent and suppression evidence, then choose Run dry run in the Imports page. Include suppression or bounce/complaint data and review affirmative-consent evidence only when that evidence was actually reviewed. - 4
Review the new staged job
Inspect the new valid, invalid, subscribed, pending, unsubscribed, and suppressed counts. Enter a review reason of at least three characters, then choose Approve or Cancel for the new job.
What does a failed import not do?
A dry run stages import data and an audit receipt; it does not create or update CRM contacts, consent events, subscriptions, or suppressions. Approval is a review checkpoint, not provider delivery. During execution, completed row work is checkpointed and row idempotency keys prevent the same new job and row action from being treated as a new action on a later worker attempt.
Heads up
Frequently asked questions
What happens if an import worker stops?+
A running job has a 30-minute lease. When that lease expires, a later worker can reclaim the job, record a lease_reclaimed audit action, and continue from the stored row and batch checkpoints.
Can I retry a job whose status is failed?+
No retry control is exposed for failed imports. The review API only approves or cancels jobs in awaiting_review or quarantined, and the execution worker selects approved or running jobs.
What does five attempts mean?+
Each staged row increments its attempt count when processed. After the fifth attempt, the next processing check marks that row failed with import_row_attempt_limit; the job can finish with failed rows.
Will a new dry run write the old import again?+
A new dry run stages the new source and does not write CRM contacts, consent events, subscriptions, or suppressions. Execution uses stable row idempotency keys for the new import job and row number.
Does recovery send email?+
No. Import approval and execution are separate from provider delivery, and the import worker does not trigger provider sending.
Related articles
Reviewing email imports
Run a staging-only CSV dry run, inspect its counts and consent mapping, then approve or cancel the reviewed import.
Email CRM
Manage the canonical contact record, consent evidence, audiences, source history, and privacy controls without mixing account or purchase status with marketing permission.