Beheerroutes zonder /admin-segment op contact-messages (lijst met spam apart en ongelezen-teller zonder spam, detail, status, verwijderen, opnieuw versturen met eigen limiet) en contact-settings voor de CMS-schakelaar, allemaal AdminOnly. Het formulier is alleen open als de hostvlag EN de CMS-schakelaar (standaard uit) aan staan; de hostvlag wordt eerst gecontroleerd zodat de database niet wordt aangeraakt. Bij uitgeschakelde host antwoorden de beheerroutes 404. OpenAPI-document bijgewerkt. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
6.9 KiB
CMS-U4 contact-admin-api: code summary
IMPORTANT: the contact form is OFF by default, on two layers
- Host switch
Contact:Enabled(appsettings/environment of the host), defaultfalse. Release condition: only switch on after the per-client rate limiting from the ASF branch is on the base branch (see the CMS-U3 rebase checklist). - CMS switch (data, this unit):
PUT /api/v1/contact-settings{ "enabled": true }, default off (no row = off). Bryan has to switch the form on himself, in the "Berichten" screen (CMS-U6) or through the API, before the public routes work. The form is open only when BOTH are on; otherwiseGET /contact-messages/tokenandPOST /contact-messagesanswer404with an empty body and the website shows its mailto fallback. A change of the CMS switch takes effect at once in the process that handled the change (other instances within 5 seconds).
Routes (all AdminOnly: Owner or Administrator; anonymous = 401, role User = 403)
Same resource names as the public routes, no /admin segment. All sit behind the availability gate (no [PublicSiteEndpoint]): for visitors they answer 503 while the CMS is off/in maintenance; a verified administrator always gets through (by design, so the CMS can be switched back on).
While the host switch is off every management route answers 404 with an empty body (the contact tables do not exist then). The UI must read 404 on GET /contact-settings as "not available on this host" and hide the menu entry. The CMS switch never closes the management routes.
JSON shapes (camelCase; enums are lower-camel strings)
status: new | read | archived | spam | converted; mailStatus: pending | sent | failed | notApplicable.
GET /api/v1/contact-messages?status=&page=1&pageSize=25 -> 200
{
"items": [
{ "id": "3f2c...-guid", "receivedAt": "2026-11-09T12:00:00+00:00", "name": "Jan Jansen",
"email": "jan@example.nl", "subject": "website", "status": "new", "mailStatus": "pending" }
],
"page": 1, "pageSize": 25, "totalCount": 1, "unreadCount": 1
}
status (optional, one value new|read|archived|spam, case-insensitive): without it the list shows new, read and archived — spam is never in the default list; status=spam shows spam apart. Newest first. page >= 1, pageSize 1-100. unreadCount = number of new messages, never counting spam, independent of the filter. The list has no message text.
GET /api/v1/contact-messages/{id} -> 200
{
"id": "3f2c...", "receivedAt": "2026-11-09T12:00:00+00:00", "name": "Jan Jansen", "email": "jan@example.nl",
"subject": "website", "message": "Ik wil graag een offerte.", "status": "new", "mailStatus": "pending",
"mailAttempts": 0, "mailError": null, "retentionUntil": "2027-11-09T12:00:00+00:00"
}
404 unknown id.
PATCH /api/v1/contact-messages/{id} body { "status": "new" | "read" | "archived" } -> 200 with the detail shape above. Setting one of these on a spam message means "not spam": it then follows the normal retention (retentionUntil = now + Contact:RetentionMonths) and appears in the default list; its mailStatus stays notApplicable until resent. Anything else (spam, converted, unknown, missing, unreadable body) -> 400. 404 unknown id.
DELETE /api/v1/contact-messages/{id} -> 204 (hard delete, erasure request); 404 unknown id.
POST /api/v1/contact-messages/{id}/resend (rate limit contact-resend, default 5 per 600 s) -> 200
{ "mailStatus": "pending", "mailAttempts": 0, "mailed": false }
mailed=true only when a mail was really sent. Until the mail unit (CMS-U5) there is no mail sender, so the answer is mailed:false and nothing changes. A spam message -> 409 (problem+json; "mark it as not spam first"). 404 unknown id. 429 with Retry-After after the limit.
GET /api/v1/contact-settings -> 200
{ "enabled": false, "hostEnabled": true }
enabled = the CMS switch (default false); hostEnabled = the host switch, read-only, so the UI can explain why the form is closed.
PUT /api/v1/contact-settings body { "enabled": true | false } -> 200, same shape as GET. Anything that is not a JSON boolean (missing, null, string, number, unreadable body) -> 400.
Error shape (400, application/problem+json)
{ "type": "about:blank", "title": "Validation failed", "status": 400, "errors": { "status": ["invalid"] } }
Field names used: status (PATCH), enabled (PUT settings), page, pageSize, status (list query). Code is always invalid.
Design notes
- Separate controllers for the management side (
ContactMessagesAdminController,ContactSettingsController) next to the publicContactMessagesController; routes cannot clash ({id:guid}). - Gate:
CompositeContactFormGate= host flag first, thenCmsFlagContactFormGate(singleton row in tableContactSettings, migrationAddContactSettings, 5-second in-process cache invalidated on every change). The publicContactRouteFilterwas not touched. With the host flag off the database is not touched at all. - Statuses and mail statuses are stored as strings; the list uses one flag per status in its query because a parameterized collection loses the value-converter mapping in the SQL translation (found by the pipeline test).
- Nothing personal is logged by the admin services (ids and outcomes only; tested).
- Management routes appear in
openapi/slpsoftware.v1.json(regenerated).
Verification (real output)
Build 0 errors. Contact.Tests 223 passed (unit + pipeline), Core 205, Availability 95, Offerings 86, Identity 37, Master 57, Api.Tests 4, against a temporary MariaDB (removed afterwards). Explicit tests requested by SLS:
- Route table: exactly the seven management routes exist; every one is under class-level
AdminOnly, none is[AllowAnonymous], none is[PublicSiteEndpoint], no route containsadmin; the only[PublicSiteEndpoint]actions in the whole module areGetTokenandSubmit; the Availability route-table test (everything exceptGetOfferings,GetToken,Submitis blocked by a closed gate) covers the new routes without change. PUT /contact-settingsby a non-admin ->403and nothing changes; by a regular user also for every other management route; anonymous ->401on all of them.- Invalid body (
"yes",1,null,{},not json, empty) ->400witherrors.enabled=["invalid"](and only that field). - Real host: switch default off and reported with
hostEnabled; PUT opens/closes the public routes at once while the management routes keep working; the changing user is recorded; full message flow (list without spam,status=spam, detail, status change, spam refused for resend, un-spam, delete); bad list queries ->400; resend429withRetry-After; host switch off -> management routes404(empty), anonymous still401; CMS disabled (availability) -> visitors503on the management routes, an administrator still200.