Enqueue an erasure job

Endpoint

POST https://api.dairo.app/v1/erasure-jobs

Enqueues a durable, irreversible erasure job and returns 202 with the new job's jobId, kind, status, and createdAt. Set type to subject to erase your own messages in the active project whose from, to, cc or bcc address is the data subject's subjectHandle email (with their attachments, raw MIME, event and send-ledger content, and threads left empty) — other members' records and other projects are not touched — or to inbox to purge everything in one inboxId (the inbox must belong to your active organization, or the call returns 404); any other type is a 400. subjectHandle is trimmed and lowercased and must be a plain email address (no display name), and inboxId must be a valid inbox UUID. Supply a caller-chosen idempotencyKey (255 characters or fewer) so a retried request returns the same job instead of enqueuing a duplicate; a key already used for a different subject or inbox is a 409. Processing is asynchronous — poll GET /v1/erasure-jobs/{jobId} for the signed deletion certificate, or subscribe to the compliance.erasure.completed webhook event. Erasure permanently destroys data, so it requires the compliance:write scope and a key whose creator is an organization owner or admin; a key restricted to specific inboxes cannot erase a subject (403) and can purge only its own inboxes.

Scope: compliance:write. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL

curl -X POST "https://api.dairo.app/v1/erasure-jobs" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "subject"
  }'

Headers

Name	Type	Required	Description
`Idempotency-Key`	string	no	Optional idempotency key for safe retries of side-effecting operations. (max length 128)

Body

Required, application/json: EraseRequest.

Field	Type	Required	Description
`type`	`"subject"`, `"inbox"`	yes	subject: erase the messages you own in this project whose from, to, cc or bcc address is subjectHandle (the operation description lists what the job does not reach). inbox: purge every message in inboxId.
`subjectHandle`	string (email)	no	Required for type subject: the data subject's plain email address.
`inboxId`	string (uuid)	no	Required for type inbox: the inbox to purge.
`idempotencyKey`	string	no	Optional caller-supplied key; a retry with the same key returns the same job, a reuse for another target is a 409.

Response

202 Accepted. Body: application/json, ErasureJobAccepted.

Field	Type	Required
`jobId`	string (uuid)	yes
`kind`	`"erase_subject"`, `"purge_inbox"`	yes
`status`	`"pending"`, `"running"`, `"completed"`, `"failed"`	yes
`createdAt`	string (date-time)	yes

202

{
  "jobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "kind": "erase_subject",
  "status": "pending",
  "createdAt": "2026-10-19T09:30:00Z"
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.

Status	Meaning
`400`	The request is malformed or a value is invalid (`invalid_request`, `invalid_domain`, `idempotency_key_mismatch`).
`401`	The API key is missing or invalid.
`403`	The key lacks the scope this endpoint needs (`scope_missing`) or may not do this (`not_permitted`).
`404`	No such resource in this account (`resource_not_found`).
`422`	The request is well-formed but a field failed validation (`validation_failed`).
`429`	Rate limit, plan limit, budget or spend cap reached (`rate_limited`, `plan_limit_reached`, `budget_exceeded`, `spend_cap_reached`).
`500`	An unexpected error; retry with backoff, then contact support (`internal_error`).