Record a coupon’s result at checkout

POST

/v1/addresses/{address}/coupon-result

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

After the test applied a coupon at checkout (on staging with test payments: Proxy Mail QA never checks out), records whether the app accepted it, refused it (rejected) or failed with an error, with its message. Every attempt is kept. Answers with them all and the coupon_result verdict: it fails a coupon accepted after its end date, accepted for an offer already given to another version of the address, or accepted twice when one_time; it warns on an error, or a refusal with no reason. With a run, a failed verdict fails it. 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^required

Media typeapplication/json

object

result

required

string

Allowed values: accepted rejected error

code

The coupon applied. Default: the newest coupon at the address.

string

<= 64 characters

email_id

The email the coupon came in.

string format: uuid

message

What the app said, such as “Code already used”.

string

<= 200 characters

one_time

The offer is one per person: a second acceptance fails.

boolean

discount_applied

What checkout took off, as shown.

string

<= 40 characters

at

When. Default: now.

string format: date-time

Responses

200

The coupon, its results and the verdict

Media typeapplication/json

object

code

string

email_id

string format: uuid

discount

string | null

valid_until

string | null format: date

results

Array<object>

object

result

string

Allowed values: accepted rejected error

message

string | null

discount_applied

string | null

one_time

boolean

at

string format: date-time

via

string

check

The coupon_result verdict.

object

check

string

Allowed value: coupon_result

status

string

Allowed values: pass fail warn skip

detail

string

Example

{
  "results": [
    {
      "result": "accepted"
    }
  ],
  "check": {
    "check": "coupon_result",
    "status": "pass"
  }
}

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"
}