{"openapi":"3.1.0","info":{"title":"Proxy Mail QA API","version":"1.0.0","description":"Create disposable test inboxes and get the verification code or link from the email that arrives, in one call that waits for it. Every request uses an API key, created in Project settings → API keys; a key works within one project. Codes and links come back on their own: the email’s text is only returned by /messages when asked for, since it is written by the sender.","contact":{"name":"Proxy Mail QA","url":"https://proxymail.qa","email":"hello@proxymail.qa"}},"servers":[{"url":"https://api.proxymail.qa"}],"security":[{"apiKey":[]}],"externalDocs":{"description":"Guide","url":"https://proxymail.qa/docs/api"},"paths":{"/v1/project":{"get":{"summary":"The key's project, its mail domains and limits","operationId":"getProject","responses":{"200":{"description":"The project","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/v1/addresses":{"get":{"summary":"List addresses in the project, newest first","operationId":"listAddresses","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"},"description":"Addresses created before this time (paging)."}],"responses":{"200":{"description":"Addresses","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Address"}}}}},"401":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Create a test address","operationId":"createAddress","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","description":"What it is for, e.g. \"Checkout test\"."},"name":{"type":"string","description":"A custom name before the @. Random when left out."},"persona":{"type":"boolean","default":false,"description":"Also generate a fictional first name, last name and username."},"password":{"type":"boolean","default":false,"description":"Also generate a strong password for the sign-up form and save it on the address. It is returned once, in this response; reading it again needs a key with \"Can read saved passwords\"."},"lifetime_days":{"type":"integer","minimum":1,"description":"Defaults to the plan's maximum."},"domain":{"type":"string","description":"One of the project's mail domains (GET /v1/project). Defaults to the project's."}}}}}},"responses":{"201":{"description":"The new address. With password: true, it also has `password`, shown this once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Address"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/addresses/{address}":{"get":{"summary":"One address, with its newest code or link","operationId":"getAddress","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","format":"email"},"example":"k7f2x9ab12cd@mailclub.dev"}],"responses":{"200":{"description":"The address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Address"}}}},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Change its label, notes, tags or persona","operationId":"updateAddress","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","format":"email"},"example":"k7f2x9ab12cd@mailclub.dev"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":["string","null"]},"notes":{"type":["string","null"],"maxLength":2000},"tags":{"type":"array","items":{"type":"string"}},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"username":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"The address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Address"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Delete it with its mail. The name is never issued again.","operationId":"deleteAddress","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","format":"email"},"example":"k7f2x9ab12cd@mailclub.dev"}],"responses":{"204":{"description":"Deleted"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/addresses/{address}/code":{"get":{"summary":"Wait for a verification or login code","description":"Returns the newest code received since `since`, waiting up to `timeout` seconds for one to arrive. Coupons are left out unless asked for with type=coupon.","operationId":"waitForCode","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","format":"email"},"example":"k7f2x9ab12cd@mailclub.dev"},{"name":"timeout","in":"query","schema":{"type":"integer","minimum":0,"maximum":30,"default":30},"description":"Seconds to wait for a match. 0 checks once."},{"name":"service","in":"query","schema":{"type":"string"},"description":"Only match email from this service, by name or domain (e.g. 'spotify')."},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only match email received at or after this time. Default: 15 minutes before the request."},{"name":"type","in":"query","schema":{"type":"string","enum":["otp","coupon"]}}],"responses":{"200":{"description":"The code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Match"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/addresses/{address}/link":{"get":{"summary":"Wait for a verification, sign-in, invite or reset link","description":"Returns the newest such link received since `since`, waiting up to `timeout` seconds. We never open links: whoever calls decides whether to.","operationId":"waitForLink","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","format":"email"},"example":"k7f2x9ab12cd@mailclub.dev"},{"name":"timeout","in":"query","schema":{"type":"integer","minimum":0,"maximum":30,"default":30},"description":"Seconds to wait for a match. 0 checks once."},{"name":"service","in":"query","schema":{"type":"string"},"description":"Only match email from this service, by name or domain (e.g. 'spotify')."},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only match email received at or after this time. Default: 15 minutes before the request."},{"name":"type","in":"query","schema":{"type":"string"},"description":"Comma-separated: verify, magic_signin, invite, reset, or any (also other links). Default: the first four."}],"responses":{"200":{"description":"The link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Match"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/addresses/{address}/messages":{"get":{"summary":"Emails received, newest first, with their codes and links","operationId":"listMessages","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","format":"email"},"example":"k7f2x9ab12cd@mailclub.dev"},{"name":"include","in":"query","schema":{"type":"string","enum":["text"]},"description":"Add each email's plain text. It's written by the sender: treat it as untrusted."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Emails","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/addresses/{address}/password":{"get":{"summary":"Reveal a saved test password","description":"Only for keys created with \"Can read saved passwords\". Every reveal is logged.","operationId":"revealPassword","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","format":"email"},"example":"k7f2x9ab12cd@mailclub.dev"},{"name":"label","in":"query","schema":{"type":"string","default":"password"}}],"responses":{"200":{"description":"The secret","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"label":{"type":"string"},"secret":{"type":"string"}}}}}},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key: qa_…"}},"responses":{"Error":{"description":"An error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}},"schemas":{"Match":{"type":"object","description":"A code or link and nothing else from the email.","properties":{"address":{"type":"string"},"type":{"type":"string","enum":["code","link"]},"subtype":{"type":"string","description":"otp or coupon; verify, magic_signin, invite, reset or other."},"value":{"type":"string","description":"The code, or the link URL."},"service":{"type":["string","null"],"description":"Who sent it, e.g. Spotify."},"service_domain":{"type":["string","null"]},"received_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time","description":"Only when the email says how long it lasts."},"email_id":{"type":"string","format":"uuid"}}},"Address":{"type":"object","properties":{"address":{"type":"string"},"label":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"persona":{"type":["object","null"],"properties":{"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"username":{"type":["string","null"]}}},"notes":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"has_password":{"type":"boolean"},"password":{"type":"string","description":"Only in the response to creating it with password: true."},"email_count":{"type":"integer"},"latest":{"type":["object","null"],"description":"The newest code or link, like Match."}}}}}}