Participant and reporting endpoints
These routes live on the participant listener, outside the administrative /api/, /auth/, and /internal/ interfaces. They do not use an administrator API key. A campaign interaction instead requires the correct opaque recipient identifier, host-bound campaign origin, campaign state, and domain evidence.
Use the campaign-generated URLs. Do not reconstruct them from a numeric analysis recipient ID or send an administrator key to the public listener.
Routes and outcomes
Section titled “Routes and outcomes”| Request | Purpose | Successful response |
|---|---|---|
GET campaign path with ?rid={tracking-id} | Serve the restricted landing page and record a click observation | HTML, 200 |
GET /track?rid={tracking-id} or a campaign-prefixed /track path | Record an image-open observation | PNG, 200 |
GET /report?rid={tracking-id} or a campaign-prefixed /report path | Record a report observation | Empty, 204 |
| HEAD a recognized interaction path | Check availability without recording an interaction | Empty body, 200 |
GET with rid suffixed by %2B | Read transparency information without recording a normal interaction | JSON, 200 |
POST campaign path with rid and the closed submission JSON | Record an allowed submission/presence event | JSON acknowledgement, 200 |
GET or HEAD /robots.txt | Discourage crawler access | Disallow-all text, or empty HEAD body |
GET /.well-known/ruphish/{challenge} | Serve a current routing-verification proof | Plain text when the challenge/host matches |
GET or HEAD /static/{asset} | Serve an allowed file from the public asset snapshot | File response for a permitted host/path |
Report responses allow cross-origin callers. OPTIONS preflight advertises GET/HEAD; preflight success alone does not prove that a recipient or campaign exists. POST to tracking, reporting, or transparency requests is rejected with 405.
Transparency JSON contains server, contact_address, and send_date. The legacy compatibility marker is server: "gophish"; it is not a statement that the running executable is Go Gophish. A literal plus must be URL-encoded as %2B so query decoding preserves the intended suffix.
Submission body
Section titled “Submission body”The application collector uses Content-Type: application/json and only these fields:
{ "event_id": "0123456789abcdef0123456789abcdef", "password_present": false}The event ID is 32 hexadecimal characters and identifies one submission attempt across retries. Generate a new unpredictable ID for a new interaction; the fixed example is illustrative. The body limit is 512 bytes. Extra fields or invalid structure return 400; oversized bodies return 413; form-encoded or multipart bodies return 415.
An acknowledgement contains success: true and redirect (string or null). Reuse the same event identity after a lost acknowledgement. The campaign’s policy determines whether submission and password-presence observations are recorded; no policy permits entered values or their derivatives. Read participant data before changing a collector or page.
Availability and limits
Section titled “Availability and limits”Missing, disabled, unverified, wrong-host, completed, or otherwise unavailable interactions generally return 404 rather than disclosing another campaign. The public listener rejects duplicate rid parameters and oversized query input. Capacity or interaction limits can return 429, an unavailable persistence operation 503, and the request deadline 408.
Public requests have a ten-second application deadline and bounded concurrent admission. Errors do not authorize resending arbitrary form contents. A browser must keep native form submission blocked when the controlled collector cannot complete.
Preview identities are temporary, non-tracking inputs generated by the application; preview success does not establish campaign-domain eligibility or record real campaign outcomes. Public static assets and verification proofs are installation services, not a general upload or file-browsing API.