feat: mail service

gateway/openapi.yaml

@@ -134,6 +134,11 @@ paths:
         that must later be confirmed through
         `POST /api/v1/public/auth/confirm-email-code`.
 
+        The JSON body stays unchanged. Callers may additionally supply the
+        standard `Accept-Language` header so the gateway can derive the
+        auth-mail locale and first-login preferred-language candidate. Missing
+        or unsupported values fall back to `en`.
+
         This route is unauthenticated and classified as `public_auth`.
         Public REST anti-abuse applies a per-IP bucket derived from
         `RemoteAddr` and an additional normalized identity bucket derived from
@@ -146,6 +151,8 @@ paths:
         gateway preserves that projected `4xx/5xx` status and serialized error
         envelope after normalizing blank or invalid fields.
       security: []
+      parameters:
+        - $ref: "#/components/parameters/AcceptLanguage"
       x-public-route-classification-note: |
         This route is always classified as `public_auth`.
       requestBody:
@@ -250,6 +257,18 @@ paths:
         default:
           $ref: "#/components/responses/ProjectedAuthServiceError"
 components:
+  parameters:
+    AcceptLanguage:
+      name: Accept-Language
+      in: header
+      required: false
+      description: |
+        Optional RFC 9110 `Accept-Language` header used by gateway to derive
+        the auth-mail locale and first-login preferred-language candidate.
+        The first supported BCP 47 tag wins; unsupported or missing values
+        fall back to `en`.
+      schema:
+        type: string
   schemas:
     HealthzResponse:
       type: object