Mark the address as unsubscribed

POST

/v1/addresses/{address}/unsubscribed

curl --request POST \
  --url https://api.proxymail.qa/v1/addresses/k7f2x9ab12cd%40mailclub.dev/unsubscribed \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Proxy-Mail-QA-Test: sign-up%20%E2%80%BA%20sends%20one%20code' \
  --data '{ "email_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "service": "example", "at": "2026-04-15T12:00:00Z", "grace": "example" }'

Records that the address unsubscribed from a sender, after the test did it (Proxy Mail QA never opens unsubscribe links). From then on, any marketing email from that sender fails after_unsubscribe, however long after. Name the sender with email_id or service (a name or a domain such as acme.com); with neither, the newest marketing email decides. at backdates it. Marking twice is harmless. In Labs: answers 403 until the key’s creator switches on Marketing and offer emails in Account settings → Labs.

Authorizations

• apiKey

Parameters

Path Parameters

address

required

string format: email

The test address, URL-encoded. A variant also works: capitals, or a +tag (k7f2x9ab12cd+o’brien@mailclub.dev). It acts on the plain address; waiting on a +tag variant, or listing its messages, only finds mail sent to that variant.

Example

k7f2x9ab12cd@mailclub.dev

Header Parameters

Proxy-Mail-QA-Run

string format: uuid

A run’s id (POST /v1/runs): adds what this call saw to the run. If it can’t be added (the run finished, or isn’t in this project), the call still works and the Proxy-Mail-QA-Run-Warning response header says why.

Proxy-Mail-QA-Test

string

<= 600 characters

With Proxy-Mail-QA-Run: the test this call belongs to, percent-encoded (encodeURIComponent), up to 200 characters once decoded. The run’s report shows it beside what the call saw.

Example

sign-up%20%E2%80%BA%20sends%20one%20code

Request Body

Media typeapplication/json

object

email_id

The email it unsubscribed from.

string format: uuid

service

The sender, as a service name or domain.

string

<= 253 characters

at

When it unsubscribed. Default: now.

string format: date-time

grace

A grace period, such as 2h or 1d (up to 30d; 0 for none): marketing within it after unsubscribing doesn’t count.

string

Example ^generated

{
  "email_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "service": "example",
  "at": "2026-04-15T12:00:00Z",
  "grace": "example"
}

Responses

200

The watch

Media typeapplication/json

object

id

string format: uuid

sender

The sender’s domain.

string

service

string | null

unsubscribed_at

string format: date-time

via

string

Allowed values: app extension agent api

grace_seconds

Marketing within this long after unsubscribing doesn’t count.

integer

watching

False once the address subscribed again.

boolean

ended_at

string | null format: date-time

after_unsubscribe

Marketing emails from the sender that came after unsubscribing and its grace period (and before subscribing again).

Array<object>

object

email_id

string format: uuid

received_at

string format: date-time

after_seconds

integer

Example

{
  "via": "app"
}

400

An error

Media typeapplication/json

object

error

string

message

string

Example ^generated

{
  "error": "example",
  "message": "example"
}

404

An error

Media typeapplication/json

object

error

string

message

string

Example ^generated

{
  "error": "example",
  "message": "example"
}