contacts

Delete a contact by external id

DELETE /v1/contacts/by-external-id/{external_id}

Auth required api.contacts.manage

Archives the contact carrying this external_id, whatever address it currently holds — the delete counterpart to the upsert above, so a contact can be retired on the same key it was created with.

Prefer this over DELETE /v1/contacts/{email} if you sync on external id. A contact's email can change (the PUT above changes it), and once it has, a delete keyed on the address you remember either misses the contact you meant to retire or archives a different contact that has since taken that address over. Neither is visible to you, because the by-email delete is idempotent and answers 204 in both cases.

Archives rather than hard-deletes, and emits exit transitions for every static List the contact belonged to, exactly as the by-email delete does.

Idempotent: 204 whether the contact was archived by this call, was already archived, or was never there. Supports the Idempotency-Key header.

Path parameters

external_id string required

The caller's stable identifier for this contact. Opaque, unique per org.

Responses

Errors follow the RFC 7807 problem format — see the error reference.

204 Contact deleted (or was already absent)

401 Missing, malformed, or unknown API key application/problem+json

403 Either the credential lacks the required scope (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

422 Query parameter or path value failed validation application/problem+json

429 Per-org rate limit exceeded application/problem+json

500 Unexpected server-side failure. The code is internal_error. The request_id field can be quoted to SendOps support to investigate. application/problem+json

503 An upstream dependency — the AWS SES account connected to this org — refused, throttled, or did not answer in time. The code is upstream_unavailable; the status is 503 when the call failed and 504 when it exceeded our deadline. Retryable. Always accompanied by Retry-After. On a 504 the outcome is genuinely unknown (the write may have reached SES), so retries of a non-idempotent call should carry an Idempotency-Key. The detail string is deliberately generic: the underlying AWS error describes the customer's own account and is recorded in SendOps logs against the request_id, not returned here. application/problem+json

504 An upstream dependency — the AWS SES account connected to this org — refused, throttled, or did not answer in time. The code is upstream_unavailable; the status is 503 when the call failed and 504 when it exceeded our deadline. Retryable. Always accompanied by Retry-After. On a 504 the outcome is genuinely unknown (the write may have reached SES), so retries of a non-idempotent call should carry an Idempotency-Key. The detail string is deliberately generic: the underlying AWS error describes the customer's own account and is recorded in SendOps logs against the request_id, not returned here. application/problem+json