Archive contacts in bulk
Archives every contact that ONE selector names, each exactly as
DELETE /v1/contacts/{email} would: the contact leaves every List and
Segment and stops receiving mail, its visitor id stops resolving, and
the record is kept (an archive, not an erasure).
Send exactly one of:
emails— up to 5 000 addresses;external_ids— up to 5 000 of your external ids;list— a static List, by id or key: its current members;segment— a Segment, by id or key: its members as of this request. A contact that enters the Segment afterwards is not archived;ownership: "probable_copy"— every probable copy in the contact ownership report (seeownershiponGET /v1/contacts), with no cap. Available only to workspaces on SendOps-owned contacts; any other gets422 ownership_report_unavailable.
Dry run first. With dry_run: true the selector is resolved and
the answer is 200 {dry_run: true, matched}; nothing is archived and
no job is recorded.
matched counts the contacts the selector names that exist in this
workspace, including ones already archived (only emails and
external_ids can name those). Addresses or ids with no contact are
not counted. At most 100 live contacts are archived inline and the
answer is 200 with the final counts; more are queued and the answer
is 202 with the job to poll on
GET /v1/contacts/bulk-archive/{job_id}.
Archiving frees plan capacity, so no plan limit applies. Counts against this key's ordinary rate limit, once per request.
Supports the Idempotency-Key header: a duplicate key within 24 h
replays the original response and archives nothing more.
Request body
Content type: application/json
emails array<string<email>> optional Constraints: 0–5000 items
external_ids array<string> optional Constraints: 0–5000 items
list string optional A static List's id or key.
segment string optional A Segment's id or key. Its membership is read once, at request time.
ownership string enum optional Every probable copy in the contact ownership report.
One of: probable_copy
dry_run boolean optional Resolve the selector and answer matched only.
Default: false
Responses
Errors follow the RFC 7807 problem format — see the error reference.
dry_run boolean required Always true.
matched integer required How many contacts the selector names.
job_id string<uuid> required state string enum required One of: pending, running, completed, failed
matched integer required Contacts the selector named, including any already archived.
archived integer required Archived by this job.
already_archived integer required Archived before this job reached them.
failed integer required Could not be archived; the job carries on past them.
code: invalid_scope), or it is bound to the test environment and this operation is irreversible (code: test_environment_forbidden). Branch on code: the first is fixed by granting the scope, the second only by using a live credential. See the "Live and test credentials" section of the API description. application/problem+json validation_failed Problem. When the refusal is about a
reference — a segment key, template slug, topic or attribute name the
organization does not have — it additionally carries validation_code,
field, line/column, missing, candidates and next_step, so a
client can correct the call without a second round of guessing. See
ValidationProblem.
application/problem+json code is internal_error. The
request_id field can be quoted to SendOps support to investigate.
application/problem+json