Phase 28 (Step 3): gateway translators for user.games.mail.*

Adds the gateway-side translation layer that maps the eight new
ConnectRPC mail commands onto backend's
`/api/v1/user/games/{game_id}/mail/*` REST endpoints.

- `gateway/internal/backendclient/mail_commands.go` defines
  `ExecuteMailCommand` and one helper per command (inbox, sent,
  message.get, send, broadcast, admin, read, delete). Each helper
  decodes the FlatBuffers request envelope, issues the REST call
  via the existing `*RESTClient.do`, decodes the JSON body, and
  re-encodes a typed FlatBuffers response. Recipient identifiers
  travel through unchanged so the new `recipient_race_name`
  shortcut introduced in Step 1 reaches backend untouched.
- `routes.go` exposes a `MailRoutes` constructor and a matching
  `mailCommandClient` implementing `downstream.Client`.
- `cmd/gateway/main.go` registers the new routes alongside the
  existing user / lobby / game-engine routes.
- `mail_commands_test.go` covers the inbox, send-by-race-name, and
  read-state paths end-to-end against an `httptest.Server`,
  asserting request shapes (path, body, X-User-ID) and the
  decoded FlatBuffers response.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

gateway/internal/backendclient/mail_commands.go

@@ -0,0 +1,567 @@
+package backendclient
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"galaxy/gateway/internal/downstream"
+	diplomailmodel "galaxy/model/diplomail"
+	commonfbs "galaxy/schema/fbs/common"
+	fbs "galaxy/schema/fbs/diplomail"
+
+	flatbuffers "github.com/google/flatbuffers/go"
+	"github.com/google/uuid"
+)
+
+// ExecuteMailCommand routes one authenticated `user.games.mail.*`
+// command into the matching `/api/v1/user/games/{game_id}/mail/...`
+// backend REST endpoint. Each command decodes a FlatBuffers request
+// payload, issues the REST call, decodes the JSON response, and
+// re-encodes the result as a typed FlatBuffers envelope.
+func (c *RESTClient) ExecuteMailCommand(ctx context.Context, command downstream.AuthenticatedCommand) (downstream.UnaryResult, error) {
+	if c == nil || c.httpClient == nil {
+		return downstream.UnaryResult{}, errors.New("backendclient: execute mail command: nil client")
+	}
+	if ctx == nil {
+		return downstream.UnaryResult{}, errors.New("backendclient: execute mail command: nil context")
+	}
+	if err := ctx.Err(); err != nil {
+		return downstream.UnaryResult{}, err
+	}
+	if strings.TrimSpace(command.UserID) == "" {
+		return downstream.UnaryResult{}, errors.New("backendclient: execute mail command: user_id must not be empty")
+	}
+
+	switch command.MessageType {
+	case diplomailmodel.MessageTypeUserGamesMailInbox:
+		return c.executeMailInbox(ctx, command.UserID, command.PayloadBytes)
+	case diplomailmodel.MessageTypeUserGamesMailSent:
+		return c.executeMailSent(ctx, command.UserID, command.PayloadBytes)
+	case diplomailmodel.MessageTypeUserGamesMailMessageGet:
+		return c.executeMailMessageGet(ctx, command.UserID, command.PayloadBytes)
+	case diplomailmodel.MessageTypeUserGamesMailSend:
+		return c.executeMailSend(ctx, command.UserID, command.PayloadBytes)
+	case diplomailmodel.MessageTypeUserGamesMailBroadcast:
+		return c.executeMailBroadcast(ctx, command.UserID, command.PayloadBytes)
+	case diplomailmodel.MessageTypeUserGamesMailAdmin:
+		return c.executeMailAdmin(ctx, command.UserID, command.PayloadBytes)
+	case diplomailmodel.MessageTypeUserGamesMailRead:
+		return c.executeMailRead(ctx, command.UserID, command.PayloadBytes)
+	case diplomailmodel.MessageTypeUserGamesMailDelete:
+		return c.executeMailDelete(ctx, command.UserID, command.PayloadBytes)
+	default:
+		return downstream.UnaryResult{}, fmt.Errorf("backendclient: execute mail command: unsupported message type %q", command.MessageType)
+	}
+}
+
+// mailMessageJSON mirrors the backend's `UserMailMessageDetail` wire
+// shape from `backend/openapi.yaml`. Pointer fields are nullable in
+// the OpenAPI spec; the encoder treats empty strings as "absent".
+type mailMessageJSON struct {
+	MessageID         string  `json:"message_id"`
+	GameID            string  `json:"game_id"`
+	GameName          string  `json:"game_name,omitempty"`
+	Kind              string  `json:"kind"`
+	SenderKind        string  `json:"sender_kind"`
+	SenderUserID      *string `json:"sender_user_id,omitempty"`
+	SenderUsername    *string `json:"sender_username,omitempty"`
+	SenderRaceName    *string `json:"sender_race_name,omitempty"`
+	Subject           string  `json:"subject,omitempty"`
+	Body              string  `json:"body"`
+	BodyLang          string  `json:"body_lang"`
+	BroadcastScope    string  `json:"broadcast_scope"`
+	CreatedAt         string  `json:"created_at"`
+	RecipientUserID   string  `json:"recipient_user_id"`
+	RecipientUserName string  `json:"recipient_user_name,omitempty"`
+	RecipientRaceName *string `json:"recipient_race_name,omitempty"`
+	ReadAt            *string `json:"read_at,omitempty"`
+	DeletedAt         *string `json:"deleted_at,omitempty"`
+	TranslatedSubject *string `json:"translated_subject,omitempty"`
+	TranslatedBody    *string `json:"translated_body,omitempty"`
+	TranslationLang   *string `json:"translation_lang,omitempty"`
+	Translator        *string `json:"translator,omitempty"`
+}
+
+// mailRecipientStateJSON mirrors `UserMailRecipientState`.
+type mailRecipientStateJSON struct {
+	MessageID string  `json:"message_id"`
+	ReadAt    *string `json:"read_at,omitempty"`
+	DeletedAt *string `json:"deleted_at,omitempty"`
+}
+
+// mailBroadcastReceiptJSON mirrors `UserMailBroadcastReceipt`.
+type mailBroadcastReceiptJSON struct {
+	MessageID      string `json:"message_id"`
+	GameID         string `json:"game_id"`
+	GameName       string `json:"game_name,omitempty"`
+	Kind           string `json:"kind"`
+	SenderKind     string `json:"sender_kind"`
+	Subject        string `json:"subject,omitempty"`
+	Body           string `json:"body"`
+	BodyLang       string `json:"body_lang"`
+	BroadcastScope string `json:"broadcast_scope"`
+	CreatedAt      string `json:"created_at"`
+	RecipientCount int    `json:"recipient_count"`
+}
+
+type mailInboxJSON struct {
+	Items []mailMessageJSON `json:"items"`
+}
+
+func (c *RESTClient) executeMailInbox(ctx context.Context, userID string, payload []byte) (downstream.UnaryResult, error) {
+	if len(payload) == 0 {
+		return downstream.UnaryResult{}, errors.New("execute user.games.mail.inbox: payload is empty")
+	}
+	flat := fbs.GetRootAsInboxRequest(payload, 0)
+	gameID := readUUID(flat.GameId(nil))
+	if gameID == uuid.Nil {
+		return downstream.UnaryResult{}, errors.New("execute user.games.mail.inbox: game_id is missing")
+	}
+	target := c.baseURL + "/api/v1/user/games/" + url.PathEscape(gameID.String()) + "/mail/inbox"
+	respBody, status, err := c.do(ctx, http.MethodGet, target, userID, nil)
+	if err != nil {
+		return downstream.UnaryResult{}, fmt.Errorf("execute user.games.mail.inbox: %w", err)
+	}
+	if status < 200 || status >= 300 {
+		return projectMailErrorResponse(status, respBody)
+	}
+	var resp mailInboxJSON
+	if err := json.Unmarshal(respBody, &resp); err != nil {
+		return downstream.UnaryResult{}, fmt.Errorf("decode mail inbox response: %w", err)
+	}
+	out := encodeMailMessageList(resp.Items, fbs.InboxResponseStart, fbs.InboxResponseAddItems, fbs.InboxResponseEnd, fbs.FinishInboxResponseBuffer)
+	return downstream.UnaryResult{ResultCode: userCommandResultCodeOK, PayloadBytes: out}, nil
+}
+
+func (c *RESTClient) executeMailSent(ctx context.Context, userID string, payload []byte) (downstream.UnaryResult, error) {
+	if len(payload) == 0 {
+		return downstream.UnaryResult{}, errors.New("execute user.games.mail.sent: payload is empty")
+	}
+	flat := fbs.GetRootAsSentRequest(payload, 0)
+	gameID := readUUID(flat.GameId(nil))
+	if gameID == uuid.Nil {
+		return downstream.UnaryResult{}, errors.New("execute user.games.mail.sent: game_id is missing")
+	}
+	target := c.baseURL + "/api/v1/user/games/" + url.PathEscape(gameID.String()) + "/mail/sent"
+	respBody, status, err := c.do(ctx, http.MethodGet, target, userID, nil)
+	if err != nil {
+		return downstream.UnaryResult{}, fmt.Errorf("execute user.games.mail.sent: %w", err)
+	}
+	if status < 200 || status >= 300 {
+		return projectMailErrorResponse(status, respBody)
+	}
+	var resp mailInboxJSON
+	if err := json.Unmarshal(respBody, &resp); err != nil {
+		return downstream.UnaryResult{}, fmt.Errorf("decode mail sent response: %w", err)
+	}
+	out := encodeMailMessageList(resp.Items, fbs.SentResponseStart, fbs.SentResponseAddItems, fbs.SentResponseEnd, fbs.FinishSentResponseBuffer)
+	return downstream.UnaryResult{ResultCode: userCommandResultCodeOK, PayloadBytes: out}, nil
+}
+
+func (c *RESTClient) executeMailMessageGet(ctx context.Context, userID string, payload []byte) (downstream.UnaryResult, error) {
+	if len(payload) == 0 {
+		return downstream.UnaryResult{}, errors.New("execute user.games.mail.message.get: payload is empty")
+	}
+	flat := fbs.GetRootAsMessageGetRequest(payload, 0)
+	gameID := readUUID(flat.GameId(nil))
+	messageID := readUUID(flat.MessageId(nil))
+	if gameID == uuid.Nil || messageID == uuid.Nil {
+		return downstream.UnaryResult{}, errors.New("execute user.games.mail.message.get: game_id and message_id are required")
+	}
+	target := c.baseURL + "/api/v1/user/games/" + url.PathEscape(gameID.String()) + "/mail/messages/" + url.PathEscape(messageID.String())
+	respBody, status, err := c.do(ctx, http.MethodGet, target, userID, nil)
+	if err != nil {
+		return downstream.UnaryResult{}, fmt.Errorf("execute user.games.mail.message.get: %w", err)
+	}
+	if status < 200 || status >= 300 {
+		return projectMailErrorResponse(status, respBody)
+	}
+	var msg mailMessageJSON
+	if err := json.Unmarshal(respBody, &msg); err != nil {
+		return downstream.UnaryResult{}, fmt.Errorf("decode mail message response: %w", err)
+	}
+	builder := flatbuffers.NewBuilder(512)
+	msgOff := encodeMailMessage(builder, &msg)
+	fbs.MessageGetResponseStart(builder)
+	fbs.MessageGetResponseAddMessage(builder, msgOff)
+	root := fbs.MessageGetResponseEnd(builder)
+	fbs.FinishMessageGetResponseBuffer(builder, root)
+	return downstream.UnaryResult{ResultCode: userCommandResultCodeOK, PayloadBytes: builder.FinishedBytes()}, nil
+}
+
+func (c *RESTClient) executeMailSend(ctx context.Context, userID string, payload []byte) (downstream.UnaryResult, error) {
+	if len(payload) == 0 {
+		return downstream.UnaryResult{}, errors.New("execute user.games.mail.send: payload is empty")
+	}
+	flat := fbs.GetRootAsSendRequest(payload, 0)
+	gameID := readUUID(flat.GameId(nil))
+	if gameID == uuid.Nil {
+		return downstream.UnaryResult{}, errors.New("execute user.games.mail.send: game_id is missing")
+	}
+	body := struct {
+		RecipientUserID   string `json:"recipient_user_id,omitempty"`
+		RecipientRaceName string `json:"recipient_race_name,omitempty"`
+		Subject           string `json:"subject,omitempty"`
+		Body              string `json:"body"`
+	}{
+		RecipientUserID:   string(flat.RecipientUserId()),
+		RecipientRaceName: string(flat.RecipientRaceName()),
+		Subject:           string(flat.Subject()),
+		Body:              string(flat.Body()),
+	}
+	target := c.baseURL + "/api/v1/user/games/" + url.PathEscape(gameID.String()) + "/mail/messages"
+	respBody, status, err := c.do(ctx, http.MethodPost, target, userID, body)
+	if err != nil {
+		return downstream.UnaryResult{}, fmt.Errorf("execute user.games.mail.send: %w", err)
+	}
+	if status < 200 || status >= 300 {
+		return projectMailErrorResponse(status, respBody)
+	}
+	var msg mailMessageJSON
+	if err := json.Unmarshal(respBody, &msg); err != nil {
+		return downstream.UnaryResult{}, fmt.Errorf("decode mail send response: %w", err)
+	}
+	builder := flatbuffers.NewBuilder(512)
+	msgOff := encodeMailMessage(builder, &msg)
+	fbs.SendResponseStart(builder)
+	fbs.SendResponseAddMessage(builder, msgOff)
+	root := fbs.SendResponseEnd(builder)
+	fbs.FinishSendResponseBuffer(builder, root)
+	return downstream.UnaryResult{ResultCode: userCommandResultCodeOK, PayloadBytes: builder.FinishedBytes()}, nil
+}
+
+func (c *RESTClient) executeMailBroadcast(ctx context.Context, userID string, payload []byte) (downstream.UnaryResult, error) {
+	if len(payload) == 0 {
+		return downstream.UnaryResult{}, errors.New("execute user.games.mail.broadcast: payload is empty")
+	}
+	flat := fbs.GetRootAsBroadcastRequest(payload, 0)
+	gameID := readUUID(flat.GameId(nil))
+	if gameID == uuid.Nil {
+		return downstream.UnaryResult{}, errors.New("execute user.games.mail.broadcast: game_id is missing")
+	}
+	body := struct {
+		Subject string `json:"subject,omitempty"`
+		Body    string `json:"body"`
+	}{
+		Subject: string(flat.Subject()),
+		Body:    string(flat.Body()),
+	}
+	target := c.baseURL + "/api/v1/user/games/" + url.PathEscape(gameID.String()) + "/mail/broadcast"
+	respBody, status, err := c.do(ctx, http.MethodPost, target, userID, body)
+	if err != nil {
+		return downstream.UnaryResult{}, fmt.Errorf("execute user.games.mail.broadcast: %w", err)
+	}
+	if status < 200 || status >= 300 {
+		return projectMailErrorResponse(status, respBody)
+	}
+	var receipt mailBroadcastReceiptJSON
+	if err := json.Unmarshal(respBody, &receipt); err != nil {
+		return downstream.UnaryResult{}, fmt.Errorf("decode mail broadcast response: %w", err)
+	}
+	builder := flatbuffers.NewBuilder(256)
+	recOff := encodeMailBroadcastReceipt(builder, &receipt)
+	fbs.BroadcastResponseStart(builder)
+	fbs.BroadcastResponseAddReceipt(builder, recOff)
+	root := fbs.BroadcastResponseEnd(builder)
+	fbs.FinishBroadcastResponseBuffer(builder, root)
+	return downstream.UnaryResult{ResultCode: userCommandResultCodeOK, PayloadBytes: builder.FinishedBytes()}, nil
+}
+
+func (c *RESTClient) executeMailAdmin(ctx context.Context, userID string, payload []byte) (downstream.UnaryResult, error) {
+	if len(payload) == 0 {
+		return downstream.UnaryResult{}, errors.New("execute user.games.mail.admin: payload is empty")
+	}
+	flat := fbs.GetRootAsAdminRequest(payload, 0)
+	gameID := readUUID(flat.GameId(nil))
+	if gameID == uuid.Nil {
+		return downstream.UnaryResult{}, errors.New("execute user.games.mail.admin: game_id is missing")
+	}
+	target := string(flat.Target())
+	body := struct {
+		Target            string `json:"target"`
+		RecipientUserID   string `json:"recipient_user_id,omitempty"`
+		RecipientRaceName string `json:"recipient_race_name,omitempty"`
+		Recipients        string `json:"recipients,omitempty"`
+		Subject           string `json:"subject,omitempty"`
+		Body              string `json:"body"`
+	}{
+		Target:            target,
+		RecipientUserID:   string(flat.RecipientUserId()),
+		RecipientRaceName: string(flat.RecipientRaceName()),
+		Recipients:        string(flat.Recipients()),
+		Subject:           string(flat.Subject()),
+		Body:              string(flat.Body()),
+	}
+	url := c.baseURL + "/api/v1/user/games/" + url.PathEscape(gameID.String()) + "/mail/admin"
+	respBody, status, err := c.do(ctx, http.MethodPost, url, userID, body)
+	if err != nil {
+		return downstream.UnaryResult{}, fmt.Errorf("execute user.games.mail.admin: %w", err)
+	}
+	if status < 200 || status >= 300 {
+		return projectMailErrorResponse(status, respBody)
+	}
+	builder := flatbuffers.NewBuilder(512)
+	if target == "all" {
+		var receipt mailBroadcastReceiptJSON
+		if err := json.Unmarshal(respBody, &receipt); err != nil {
+			return downstream.UnaryResult{}, fmt.Errorf("decode mail admin broadcast response: %w", err)
+		}
+		recOff := encodeMailBroadcastReceipt(builder, &receipt)
+		fbs.AdminResponseStart(builder)
+		fbs.AdminResponseAddReceipt(builder, recOff)
+		root := fbs.AdminResponseEnd(builder)
+		fbs.FinishAdminResponseBuffer(builder, root)
+	} else {
+		var msg mailMessageJSON
+		if err := json.Unmarshal(respBody, &msg); err != nil {
+			return downstream.UnaryResult{}, fmt.Errorf("decode mail admin send response: %w", err)
+		}
+		msgOff := encodeMailMessage(builder, &msg)
+		fbs.AdminResponseStart(builder)
+		fbs.AdminResponseAddMessage(builder, msgOff)
+		root := fbs.AdminResponseEnd(builder)
+		fbs.FinishAdminResponseBuffer(builder, root)
+	}
+	return downstream.UnaryResult{ResultCode: userCommandResultCodeOK, PayloadBytes: builder.FinishedBytes()}, nil
+}
+
+func (c *RESTClient) executeMailRead(ctx context.Context, userID string, payload []byte) (downstream.UnaryResult, error) {
+	if len(payload) == 0 {
+		return downstream.UnaryResult{}, errors.New("execute user.games.mail.read: payload is empty")
+	}
+	flat := fbs.GetRootAsReadRequest(payload, 0)
+	gameID := readUUID(flat.GameId(nil))
+	messageID := readUUID(flat.MessageId(nil))
+	if gameID == uuid.Nil || messageID == uuid.Nil {
+		return downstream.UnaryResult{}, errors.New("execute user.games.mail.read: game_id and message_id are required")
+	}
+	target := c.baseURL + "/api/v1/user/games/" + url.PathEscape(gameID.String()) + "/mail/messages/" + url.PathEscape(messageID.String()) + "/read"
+	respBody, status, err := c.do(ctx, http.MethodPost, target, userID, struct{}{})
+	if err != nil {
+		return downstream.UnaryResult{}, fmt.Errorf("execute user.games.mail.read: %w", err)
+	}
+	if status < 200 || status >= 300 {
+		return projectMailErrorResponse(status, respBody)
+	}
+	return encodeRecipientStateResponse(respBody, fbs.ReadResponseStart, fbs.ReadResponseAddState, fbs.ReadResponseEnd, fbs.FinishReadResponseBuffer)
+}
+
+func (c *RESTClient) executeMailDelete(ctx context.Context, userID string, payload []byte) (downstream.UnaryResult, error) {
+	if len(payload) == 0 {
+		return downstream.UnaryResult{}, errors.New("execute user.games.mail.delete: payload is empty")
+	}
+	flat := fbs.GetRootAsDeleteRequest(payload, 0)
+	gameID := readUUID(flat.GameId(nil))
+	messageID := readUUID(flat.MessageId(nil))
+	if gameID == uuid.Nil || messageID == uuid.Nil {
+		return downstream.UnaryResult{}, errors.New("execute user.games.mail.delete: game_id and message_id are required")
+	}
+	target := c.baseURL + "/api/v1/user/games/" + url.PathEscape(gameID.String()) + "/mail/messages/" + url.PathEscape(messageID.String())
+	respBody, status, err := c.do(ctx, http.MethodDelete, target, userID, nil)
+	if err != nil {
+		return downstream.UnaryResult{}, fmt.Errorf("execute user.games.mail.delete: %w", err)
+	}
+	if status < 200 || status >= 300 {
+		return projectMailErrorResponse(status, respBody)
+	}
+	return encodeRecipientStateResponse(respBody, fbs.DeleteResponseStart, fbs.DeleteResponseAddState, fbs.DeleteResponseEnd, fbs.FinishDeleteResponseBuffer)
+}
+
+// encodeRecipientStateResponse decodes the JSON recipient-state body
+// and emits the corresponding FlatBuffers Read/Delete envelope. The
+// caller supplies the trio of envelope start / add-state / end / finish
+// functions so this helper covers both endpoints with the same shape.
+func encodeRecipientStateResponse(respBody []byte,
+	startFn func(*flatbuffers.Builder),
+	addStateFn func(*flatbuffers.Builder, flatbuffers.UOffsetT),
+	endFn func(*flatbuffers.Builder) flatbuffers.UOffsetT,
+	finishFn func(*flatbuffers.Builder, flatbuffers.UOffsetT),
+) (downstream.UnaryResult, error) {
+	var state mailRecipientStateJSON
+	if err := json.Unmarshal(respBody, &state); err != nil {
+		return downstream.UnaryResult{}, fmt.Errorf("decode mail recipient state: %w", err)
+	}
+	builder := flatbuffers.NewBuilder(128)
+	stateOff := encodeMailRecipientState(builder, &state)
+	startFn(builder)
+	addStateFn(builder, stateOff)
+	root := endFn(builder)
+	finishFn(builder, root)
+	return downstream.UnaryResult{ResultCode: userCommandResultCodeOK, PayloadBytes: builder.FinishedBytes()}, nil
+}
+
+// encodeMailMessageList is a shared helper that encodes a slice of
+// mailMessageJSON items into either an InboxResponse or a
+// SentResponse FlatBuffers envelope. The two envelopes have the same
+// shape (just a `items` vector of MailMessage) so the trio of
+// constructor functions parameterises the helper.
+func encodeMailMessageList(items []mailMessageJSON,
+	startFn func(*flatbuffers.Builder),
+	addItemsFn func(*flatbuffers.Builder, flatbuffers.UOffsetT),
+	endFn func(*flatbuffers.Builder) flatbuffers.UOffsetT,
+	finishFn func(*flatbuffers.Builder, flatbuffers.UOffsetT),
+) []byte {
+	builder := flatbuffers.NewBuilder(1024)
+	offsets := make([]flatbuffers.UOffsetT, 0, len(items))
+	for i := range items {
+		offsets = append(offsets, encodeMailMessage(builder, &items[i]))
+	}
+	// FlatBuffers vectors are built in reverse: prepend each offset.
+	builder.StartVector(4, len(offsets), 4)
+	for i := len(offsets) - 1; i >= 0; i-- {
+		builder.PrependUOffsetT(offsets[i])
+	}
+	itemsVec := builder.EndVector(len(offsets))
+	startFn(builder)
+	addItemsFn(builder, itemsVec)
+	root := endFn(builder)
+	finishFn(builder, root)
+	return builder.FinishedBytes()
+}
+
+// encodeMailMessage builds a MailMessage table inside builder. Returns
+// the offset of the finished table. Strings are interned through the
+// builder; missing JSON fields (nil pointers, empty strings) yield
+// empty FB strings which the readers treat as absent.
+func encodeMailMessage(builder *flatbuffers.Builder, m *mailMessageJSON) flatbuffers.UOffsetT {
+	messageIDOff := builder.CreateString(m.MessageID)
+	gameIDOff := builder.CreateString(m.GameID)
+	gameNameOff := builder.CreateString(m.GameName)
+	kindOff := builder.CreateString(m.Kind)
+	senderKindOff := builder.CreateString(m.SenderKind)
+	senderUserIDOff := builder.CreateString(stringPtrValue(m.SenderUserID))
+	senderUsernameOff := builder.CreateString(stringPtrValue(m.SenderUsername))
+	senderRaceNameOff := builder.CreateString(stringPtrValue(m.SenderRaceName))
+	subjectOff := builder.CreateString(m.Subject)
+	bodyOff := builder.CreateString(m.Body)
+	bodyLangOff := builder.CreateString(m.BodyLang)
+	broadcastScopeOff := builder.CreateString(m.BroadcastScope)
+	recipientUserIDOff := builder.CreateString(m.RecipientUserID)
+	recipientUserNameOff := builder.CreateString(m.RecipientUserName)
+	recipientRaceNameOff := builder.CreateString(stringPtrValue(m.RecipientRaceName))
+	translatedSubjectOff := builder.CreateString(stringPtrValue(m.TranslatedSubject))
+	translatedBodyOff := builder.CreateString(stringPtrValue(m.TranslatedBody))
+	translationLangOff := builder.CreateString(stringPtrValue(m.TranslationLang))
+	translatorOff := builder.CreateString(stringPtrValue(m.Translator))
+
+	fbs.MailMessageStart(builder)
+	fbs.MailMessageAddMessageId(builder, messageIDOff)
+	fbs.MailMessageAddGameId(builder, gameIDOff)
+	fbs.MailMessageAddGameName(builder, gameNameOff)
+	fbs.MailMessageAddKind(builder, kindOff)
+	fbs.MailMessageAddSenderKind(builder, senderKindOff)
+	fbs.MailMessageAddSenderUserId(builder, senderUserIDOff)
+	fbs.MailMessageAddSenderUsername(builder, senderUsernameOff)
+	fbs.MailMessageAddSenderRaceName(builder, senderRaceNameOff)
+	fbs.MailMessageAddSubject(builder, subjectOff)
+	fbs.MailMessageAddBody(builder, bodyOff)
+	fbs.MailMessageAddBodyLang(builder, bodyLangOff)
+	fbs.MailMessageAddBroadcastScope(builder, broadcastScopeOff)
+	fbs.MailMessageAddCreatedAtMs(builder, parseRFC3339Millis(m.CreatedAt))
+	fbs.MailMessageAddRecipientUserId(builder, recipientUserIDOff)
+	fbs.MailMessageAddRecipientUserName(builder, recipientUserNameOff)
+	fbs.MailMessageAddRecipientRaceName(builder, recipientRaceNameOff)
+	fbs.MailMessageAddReadAtMs(builder, parseRFC3339Millis(stringPtrValue(m.ReadAt)))
+	fbs.MailMessageAddDeletedAtMs(builder, parseRFC3339Millis(stringPtrValue(m.DeletedAt)))
+	fbs.MailMessageAddTranslatedSubject(builder, translatedSubjectOff)
+	fbs.MailMessageAddTranslatedBody(builder, translatedBodyOff)
+	fbs.MailMessageAddTranslationLang(builder, translationLangOff)
+	fbs.MailMessageAddTranslator(builder, translatorOff)
+	return fbs.MailMessageEnd(builder)
+}
+
+// encodeMailRecipientState builds a MailRecipientState table.
+func encodeMailRecipientState(builder *flatbuffers.Builder, s *mailRecipientStateJSON) flatbuffers.UOffsetT {
+	messageIDOff := builder.CreateString(s.MessageID)
+	fbs.MailRecipientStateStart(builder)
+	fbs.MailRecipientStateAddMessageId(builder, messageIDOff)
+	fbs.MailRecipientStateAddReadAtMs(builder, parseRFC3339Millis(stringPtrValue(s.ReadAt)))
+	fbs.MailRecipientStateAddDeletedAtMs(builder, parseRFC3339Millis(stringPtrValue(s.DeletedAt)))
+	return fbs.MailRecipientStateEnd(builder)
+}
+
+// encodeMailBroadcastReceipt builds a MailBroadcastReceipt table.
+func encodeMailBroadcastReceipt(builder *flatbuffers.Builder, r *mailBroadcastReceiptJSON) flatbuffers.UOffsetT {
+	messageIDOff := builder.CreateString(r.MessageID)
+	gameIDOff := builder.CreateString(r.GameID)
+	gameNameOff := builder.CreateString(r.GameName)
+	kindOff := builder.CreateString(r.Kind)
+	senderKindOff := builder.CreateString(r.SenderKind)
+	subjectOff := builder.CreateString(r.Subject)
+	bodyOff := builder.CreateString(r.Body)
+	bodyLangOff := builder.CreateString(r.BodyLang)
+	broadcastScopeOff := builder.CreateString(r.BroadcastScope)
+	fbs.MailBroadcastReceiptStart(builder)
+	fbs.MailBroadcastReceiptAddMessageId(builder, messageIDOff)
+	fbs.MailBroadcastReceiptAddGameId(builder, gameIDOff)
+	fbs.MailBroadcastReceiptAddGameName(builder, gameNameOff)
+	fbs.MailBroadcastReceiptAddKind(builder, kindOff)
+	fbs.MailBroadcastReceiptAddSenderKind(builder, senderKindOff)
+	fbs.MailBroadcastReceiptAddSubject(builder, subjectOff)
+	fbs.MailBroadcastReceiptAddBody(builder, bodyOff)
+	fbs.MailBroadcastReceiptAddBodyLang(builder, bodyLangOff)
+	fbs.MailBroadcastReceiptAddBroadcastScope(builder, broadcastScopeOff)
+	fbs.MailBroadcastReceiptAddCreatedAtMs(builder, parseRFC3339Millis(r.CreatedAt))
+	fbs.MailBroadcastReceiptAddRecipientCount(builder, int32(r.RecipientCount))
+	return fbs.MailBroadcastReceiptEnd(builder)
+}
+
+// projectMailErrorResponse maps a non-2xx response into a UnaryResult
+// carrying the backend error envelope, reusing the shared user-mail
+// error-projection. 503 is bubbled as ErrDownstreamUnavailable.
+func projectMailErrorResponse(statusCode int, payload []byte) (downstream.UnaryResult, error) {
+	if statusCode == http.StatusServiceUnavailable {
+		return downstream.UnaryResult{}, downstream.ErrDownstreamUnavailable
+	}
+	if statusCode >= 400 && statusCode <= 599 {
+		return projectUserBackendError(statusCode, payload)
+	}
+	return downstream.UnaryResult{}, fmt.Errorf("unexpected HTTP status %d", statusCode)
+}
+
+// readUUID converts the common.UUID struct (or its absence) into a
+// google/uuid.UUID. Returns uuid.Nil when the input is nil.
+func readUUID(u *commonfbs.UUID) uuid.UUID {
+	if u == nil {
+		return uuid.Nil
+	}
+	var out uuid.UUID
+	hi := u.Hi()
+	lo := u.Lo()
+	for i := 0; i < 8; i++ {
+		out[i] = byte(hi >> (56 - 8*i))
+		out[i+8] = byte(lo >> (56 - 8*i))
+	}
+	return out
+}
+
+// stringPtrValue returns "" for nil and the dereferenced value
+// otherwise. Used to flatten nullable JSON strings into the
+// always-present FlatBuffers string slot.
+func stringPtrValue(p *string) string {
+	if p == nil {
+		return ""
+	}
+	return *p
+}
+
+// parseRFC3339Millis parses an RFC 3339 timestamp string (the format
+// the backend mail handler emits) into Unix milliseconds. Returns 0
+// when the input is empty or unparseable, matching the "absent"
+// convention for the *_at_ms wire fields.
+func parseRFC3339Millis(s string) int64 {
+	if s == "" {
+		return 0
+	}
+	t, err := time.Parse(time.RFC3339Nano, s)
+	if err != nil {
+		return 0
+	}
+	return t.UnixMilli()
+}