feat: mail service

authsession/api/public-openapi.yaml

@@ -36,7 +36,15 @@ paths:
         Accepts one client e-mail address and starts the public challenge flow.
         The outward result remains success-shaped even when the underlying
         policy suppresses mail delivery for anti-enumeration purposes.
+
+        The JSON body stays unchanged. Gateway may additionally forward the
+        optional public `Accept-Language` header so auth can derive the
+        auth-mail locale and the create-only preferred-language candidate used
+        later during first-user creation. Missing or unsupported values fall
+        back to `en`.
       security: []
+      parameters:
+        - $ref: "#/components/parameters/AcceptLanguage"
       requestBody:
         required: true
         content:
@@ -111,6 +119,18 @@ paths:
         "503":
           $ref: "#/components/responses/ServiceUnavailableError"
 components:
+  parameters:
+    AcceptLanguage:
+      name: Accept-Language
+      in: header
+      required: false
+      description: |
+        Optional RFC 9110 `Accept-Language` header forwarded by gateway so
+        auth can derive the auth-mail locale and create-only
+        preferred-language candidate. The first supported BCP 47 tag wins;
+        unsupported or missing values fall back to `en`.
+      schema:
+        type: string
   schemas:
     SendEmailCodeRequest:
       type: object