Ilia Denisov
726 lines
20 KiB
YAML
726 lines
20 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Galaxy Mail Service Internal REST API
|
|
version: v1
|
|
description: |
|
|
This specification documents the trusted internal REST contract of
|
|
`galaxy/mail`.
|
|
|
|
The current document freezes:
|
|
- the dedicated auth-delivery route used by `Auth / Session Service`;
|
|
- the trusted operator read and resend routes used for delivery audit and
|
|
recovery.
|
|
|
|
Contract rules:
|
|
- the internal surface lives under `/api/v1/internal`;
|
|
- request and response bodies are JSON only;
|
|
- auth-delivery intake requires the `Idempotency-Key` header;
|
|
- request bodies use strict JSON decoding with unknown-field rejection;
|
|
- trailing JSON input is rejected;
|
|
- success outcomes are limited to `sent` and `suppressed` on the auth
|
|
route;
|
|
- mismatched replays on the same `Idempotency-Key` return `409 conflict`;
|
|
- operator listing order is `created_at_ms DESC`, then `delivery_id DESC`;
|
|
- operator list cursors are opaque base64url encodings of
|
|
`created_at_ms:delivery_id`;
|
|
- `sent` means durable acceptance into the mail-delivery pipeline rather
|
|
than immediate SMTP completion;
|
|
- auth callers must not automatically retry transport or upstream
|
|
failures;
|
|
- `Auth / Session Service` sends the created `challenge_id` as the raw
|
|
`Idempotency-Key` header value.
|
|
servers:
|
|
- url: http://localhost:8080
|
|
description: Default local internal listener for Mail Service.
|
|
tags:
|
|
- name: AuthIntegration
|
|
description: Trusted auth-facing mail-delivery intake frozen for `Auth / Session Service`.
|
|
- name: OperatorIntegration
|
|
description: Trusted operator-facing delivery reads and resend controls.
|
|
paths:
|
|
/api/v1/internal/login-code-deliveries:
|
|
post:
|
|
tags:
|
|
- AuthIntegration
|
|
operationId: acceptLoginCodeDelivery
|
|
summary: Accept one auth login-code delivery request
|
|
description: |
|
|
Validates one trusted auth login-code delivery request and accepts it
|
|
durably into the internal mail-delivery pipeline or intentionally
|
|
suppresses outward delivery while keeping the auth flow success-shaped.
|
|
parameters:
|
|
- $ref: "#/components/parameters/IdempotencyKey"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/LoginCodeDeliveryRequest"
|
|
responses:
|
|
"200":
|
|
description: Stable auth-delivery acceptance outcome.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/LoginCodeDeliveryResponse"
|
|
"400":
|
|
$ref: "#/components/responses/InvalidRequestError"
|
|
"409":
|
|
$ref: "#/components/responses/ConflictError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
"503":
|
|
$ref: "#/components/responses/ServiceUnavailableError"
|
|
/api/v1/internal/deliveries:
|
|
get:
|
|
tags:
|
|
- OperatorIntegration
|
|
operationId: listDeliveries
|
|
summary: List durable deliveries for trusted operators
|
|
description: |
|
|
Returns one deterministic page of brief delivery summaries ordered by
|
|
`created_at_ms DESC`, then `delivery_id DESC`.
|
|
parameters:
|
|
- $ref: "#/components/parameters/RecipientFilter"
|
|
- $ref: "#/components/parameters/StatusFilter"
|
|
- $ref: "#/components/parameters/SourceFilter"
|
|
- $ref: "#/components/parameters/TemplateIDFilter"
|
|
- $ref: "#/components/parameters/IdempotencyKeyFilter"
|
|
- $ref: "#/components/parameters/FromCreatedAtMSFilter"
|
|
- $ref: "#/components/parameters/ToCreatedAtMSFilter"
|
|
- $ref: "#/components/parameters/ListLimit"
|
|
- $ref: "#/components/parameters/ListCursor"
|
|
responses:
|
|
"200":
|
|
description: One deterministic page of delivery summaries.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/DeliveryListResponse"
|
|
"400":
|
|
$ref: "#/components/responses/InvalidRequestError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
"503":
|
|
$ref: "#/components/responses/ServiceUnavailableError"
|
|
/api/v1/internal/deliveries/{delivery_id}:
|
|
get:
|
|
tags:
|
|
- OperatorIntegration
|
|
operationId: getDelivery
|
|
summary: Get one durable delivery for trusted operators
|
|
parameters:
|
|
- $ref: "#/components/parameters/DeliveryIDPath"
|
|
responses:
|
|
"200":
|
|
description: One full delivery view with the optional dead-letter entry.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/DeliveryDetailResponse"
|
|
"400":
|
|
$ref: "#/components/responses/InvalidRequestError"
|
|
"404":
|
|
$ref: "#/components/responses/DeliveryNotFoundError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
"503":
|
|
$ref: "#/components/responses/ServiceUnavailableError"
|
|
/api/v1/internal/deliveries/{delivery_id}/attempts:
|
|
get:
|
|
tags:
|
|
- OperatorIntegration
|
|
operationId: listDeliveryAttempts
|
|
summary: Get the attempt history of one durable delivery
|
|
parameters:
|
|
- $ref: "#/components/parameters/DeliveryIDPath"
|
|
responses:
|
|
"200":
|
|
description: The ordered attempt history of one durable delivery.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/DeliveryAttemptsResponse"
|
|
"400":
|
|
$ref: "#/components/responses/InvalidRequestError"
|
|
"404":
|
|
$ref: "#/components/responses/DeliveryNotFoundError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
"503":
|
|
$ref: "#/components/responses/ServiceUnavailableError"
|
|
/api/v1/internal/deliveries/{delivery_id}/resend:
|
|
post:
|
|
tags:
|
|
- OperatorIntegration
|
|
operationId: resendDelivery
|
|
summary: Clone one terminal delivery for resend
|
|
parameters:
|
|
- $ref: "#/components/parameters/DeliveryIDPath"
|
|
responses:
|
|
"200":
|
|
description: The clone delivery was created successfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/DeliveryResendResponse"
|
|
"400":
|
|
$ref: "#/components/responses/InvalidRequestError"
|
|
"404":
|
|
$ref: "#/components/responses/DeliveryNotFoundError"
|
|
"409":
|
|
$ref: "#/components/responses/ResendNotAllowedError"
|
|
"500":
|
|
$ref: "#/components/responses/InternalError"
|
|
"503":
|
|
$ref: "#/components/responses/ServiceUnavailableError"
|
|
components:
|
|
parameters:
|
|
IdempotencyKey:
|
|
name: Idempotency-Key
|
|
in: header
|
|
required: true
|
|
description: |
|
|
Caller-owned stable deduplication key. `Auth / Session Service` uses
|
|
the created `challenge_id` as the raw header value.
|
|
schema:
|
|
type: string
|
|
DeliveryIDPath:
|
|
name: delivery_id
|
|
in: path
|
|
required: true
|
|
description: Mail Service delivery identifier.
|
|
schema:
|
|
type: string
|
|
RecipientFilter:
|
|
name: recipient
|
|
in: query
|
|
required: false
|
|
description: Effective-recipient filter covering `to`, `cc`, and `bcc`.
|
|
schema:
|
|
type: string
|
|
StatusFilter:
|
|
name: status
|
|
in: query
|
|
required: false
|
|
description: Delivery lifecycle status filter.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- queued
|
|
- rendered
|
|
- sending
|
|
- sent
|
|
- suppressed
|
|
- failed
|
|
- dead_letter
|
|
SourceFilter:
|
|
name: source
|
|
in: query
|
|
required: false
|
|
description: Delivery source filter.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- authsession
|
|
- notification
|
|
- operator_resend
|
|
TemplateIDFilter:
|
|
name: template_id
|
|
in: query
|
|
required: false
|
|
description: Template family filter.
|
|
schema:
|
|
type: string
|
|
IdempotencyKeyFilter:
|
|
name: idempotency_key
|
|
in: query
|
|
required: false
|
|
description: |
|
|
Idempotency-key filter. When `source` is omitted, Mail Service matches
|
|
the key across all frozen sources.
|
|
schema:
|
|
type: string
|
|
FromCreatedAtMSFilter:
|
|
name: from_created_at_ms
|
|
in: query
|
|
required: false
|
|
description: Inclusive lower bound for `created_at_ms`.
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
ToCreatedAtMSFilter:
|
|
name: to_created_at_ms
|
|
in: query
|
|
required: false
|
|
description: Inclusive upper bound for `created_at_ms`.
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
ListLimit:
|
|
name: limit
|
|
in: query
|
|
required: false
|
|
description: |
|
|
Maximum number of returned deliveries. The frozen default is `50` and
|
|
the maximum is `200`.
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 200
|
|
ListCursor:
|
|
name: cursor
|
|
in: query
|
|
required: false
|
|
description: |
|
|
Opaque continuation cursor encoded as base64url of
|
|
`created_at_ms:delivery_id`.
|
|
schema:
|
|
type: string
|
|
schemas:
|
|
LoginCodeDeliveryRequest:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- email
|
|
- code
|
|
- locale
|
|
properties:
|
|
email:
|
|
type: string
|
|
description: Normalized destination e-mail address.
|
|
code:
|
|
type: string
|
|
description: Exact login code generated by `Auth / Session Service`.
|
|
locale:
|
|
type: string
|
|
description: Canonical BCP 47 language tag already resolved upstream.
|
|
LoginCodeDeliveryResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- outcome
|
|
properties:
|
|
outcome:
|
|
type: string
|
|
description: Stable coarse outcome of the auth-delivery acceptance.
|
|
enum:
|
|
- sent
|
|
- suppressed
|
|
DeliverySummaryResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- delivery_id
|
|
- source
|
|
- payload_mode
|
|
- to
|
|
- cc
|
|
- bcc
|
|
- reply_to
|
|
- locale_fallback_used
|
|
- idempotency_key
|
|
- status
|
|
- attempt_count
|
|
- created_at_ms
|
|
- updated_at_ms
|
|
properties:
|
|
delivery_id:
|
|
type: string
|
|
resend_parent_delivery_id:
|
|
type: string
|
|
source:
|
|
type: string
|
|
enum:
|
|
- authsession
|
|
- notification
|
|
- operator_resend
|
|
payload_mode:
|
|
type: string
|
|
enum:
|
|
- rendered
|
|
- template
|
|
template_id:
|
|
type: string
|
|
to:
|
|
type: array
|
|
items:
|
|
type: string
|
|
cc:
|
|
type: array
|
|
items:
|
|
type: string
|
|
bcc:
|
|
type: array
|
|
items:
|
|
type: string
|
|
reply_to:
|
|
type: array
|
|
items:
|
|
type: string
|
|
locale:
|
|
type: string
|
|
locale_fallback_used:
|
|
type: boolean
|
|
idempotency_key:
|
|
type: string
|
|
status:
|
|
type: string
|
|
enum:
|
|
- queued
|
|
- rendered
|
|
- sending
|
|
- sent
|
|
- suppressed
|
|
- failed
|
|
- dead_letter
|
|
attempt_count:
|
|
type: integer
|
|
last_attempt_status:
|
|
type: string
|
|
enum:
|
|
- scheduled
|
|
- in_progress
|
|
- render_failed
|
|
- provider_accepted
|
|
- provider_rejected
|
|
- transport_failed
|
|
- timed_out
|
|
provider_summary:
|
|
type: string
|
|
created_at_ms:
|
|
type: integer
|
|
format: int64
|
|
updated_at_ms:
|
|
type: integer
|
|
format: int64
|
|
sent_at_ms:
|
|
type: integer
|
|
format: int64
|
|
suppressed_at_ms:
|
|
type: integer
|
|
format: int64
|
|
failed_at_ms:
|
|
type: integer
|
|
format: int64
|
|
dead_lettered_at_ms:
|
|
type: integer
|
|
format: int64
|
|
DeliveryListResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- items
|
|
properties:
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/DeliverySummaryResponse"
|
|
next_cursor:
|
|
type: string
|
|
AttachmentResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- filename
|
|
- content_type
|
|
- size_bytes
|
|
properties:
|
|
filename:
|
|
type: string
|
|
content_type:
|
|
type: string
|
|
size_bytes:
|
|
type: integer
|
|
format: int64
|
|
DeadLetterResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- delivery_id
|
|
- final_attempt_no
|
|
- failure_classification
|
|
- created_at_ms
|
|
properties:
|
|
delivery_id:
|
|
type: string
|
|
final_attempt_no:
|
|
type: integer
|
|
failure_classification:
|
|
type: string
|
|
provider_summary:
|
|
type: string
|
|
created_at_ms:
|
|
type: integer
|
|
format: int64
|
|
recovery_hint:
|
|
type: string
|
|
DeliveryDetailResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- delivery_id
|
|
- source
|
|
- payload_mode
|
|
- to
|
|
- cc
|
|
- bcc
|
|
- reply_to
|
|
- attachments
|
|
- locale_fallback_used
|
|
- idempotency_key
|
|
- status
|
|
- attempt_count
|
|
- created_at_ms
|
|
- updated_at_ms
|
|
properties:
|
|
delivery_id:
|
|
type: string
|
|
resend_parent_delivery_id:
|
|
type: string
|
|
source:
|
|
type: string
|
|
enum:
|
|
- authsession
|
|
- notification
|
|
- operator_resend
|
|
payload_mode:
|
|
type: string
|
|
enum:
|
|
- rendered
|
|
- template
|
|
template_id:
|
|
type: string
|
|
template_variables:
|
|
type: object
|
|
additionalProperties: true
|
|
to:
|
|
type: array
|
|
items:
|
|
type: string
|
|
cc:
|
|
type: array
|
|
items:
|
|
type: string
|
|
bcc:
|
|
type: array
|
|
items:
|
|
type: string
|
|
reply_to:
|
|
type: array
|
|
items:
|
|
type: string
|
|
subject:
|
|
type: string
|
|
text_body:
|
|
type: string
|
|
html_body:
|
|
type: string
|
|
attachments:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/AttachmentResponse"
|
|
locale:
|
|
type: string
|
|
locale_fallback_used:
|
|
type: boolean
|
|
idempotency_key:
|
|
type: string
|
|
status:
|
|
type: string
|
|
enum:
|
|
- queued
|
|
- rendered
|
|
- sending
|
|
- sent
|
|
- suppressed
|
|
- failed
|
|
- dead_letter
|
|
attempt_count:
|
|
type: integer
|
|
last_attempt_status:
|
|
type: string
|
|
enum:
|
|
- scheduled
|
|
- in_progress
|
|
- render_failed
|
|
- provider_accepted
|
|
- provider_rejected
|
|
- transport_failed
|
|
- timed_out
|
|
provider_summary:
|
|
type: string
|
|
created_at_ms:
|
|
type: integer
|
|
format: int64
|
|
updated_at_ms:
|
|
type: integer
|
|
format: int64
|
|
sent_at_ms:
|
|
type: integer
|
|
format: int64
|
|
suppressed_at_ms:
|
|
type: integer
|
|
format: int64
|
|
failed_at_ms:
|
|
type: integer
|
|
format: int64
|
|
dead_lettered_at_ms:
|
|
type: integer
|
|
format: int64
|
|
dead_letter:
|
|
$ref: "#/components/schemas/DeadLetterResponse"
|
|
AttemptResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- delivery_id
|
|
- attempt_no
|
|
- scheduled_for_ms
|
|
- status
|
|
properties:
|
|
delivery_id:
|
|
type: string
|
|
attempt_no:
|
|
type: integer
|
|
scheduled_for_ms:
|
|
type: integer
|
|
format: int64
|
|
started_at_ms:
|
|
type: integer
|
|
format: int64
|
|
finished_at_ms:
|
|
type: integer
|
|
format: int64
|
|
status:
|
|
type: string
|
|
enum:
|
|
- scheduled
|
|
- in_progress
|
|
- render_failed
|
|
- provider_accepted
|
|
- provider_rejected
|
|
- transport_failed
|
|
- timed_out
|
|
provider_classification:
|
|
type: string
|
|
provider_summary:
|
|
type: string
|
|
DeliveryAttemptsResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- items
|
|
properties:
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/AttemptResponse"
|
|
DeliveryResendResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- delivery_id
|
|
properties:
|
|
delivery_id:
|
|
type: string
|
|
ErrorResponse:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- error
|
|
properties:
|
|
error:
|
|
$ref: "#/components/schemas/ErrorBody"
|
|
ErrorBody:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- code
|
|
- message
|
|
properties:
|
|
code:
|
|
type: string
|
|
description: Stable internal API error code.
|
|
message:
|
|
type: string
|
|
description: Human-readable trusted error message.
|
|
responses:
|
|
InvalidRequestError:
|
|
description: Request validation failed.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
examples:
|
|
missingHeader:
|
|
value:
|
|
error:
|
|
code: invalid_request
|
|
message: Idempotency-Key header must not be empty
|
|
invalidCursor:
|
|
value:
|
|
error:
|
|
code: invalid_request
|
|
message: cursor is invalid
|
|
ConflictError:
|
|
description: The current idempotency scope belongs to a different normalized request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
examples:
|
|
conflict:
|
|
value:
|
|
error:
|
|
code: conflict
|
|
message: request conflicts with current state
|
|
DeliveryNotFoundError:
|
|
description: The requested delivery does not exist.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
examples:
|
|
missingDelivery:
|
|
value:
|
|
error:
|
|
code: delivery_not_found
|
|
message: delivery not found
|
|
ResendNotAllowedError:
|
|
description: The requested delivery is not in a terminal resend-eligible state.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
examples:
|
|
resendNotAllowed:
|
|
value:
|
|
error:
|
|
code: resend_not_allowed
|
|
message: delivery status does not allow resend
|
|
InternalError:
|
|
description: Internal application invariant failed.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
examples:
|
|
internal:
|
|
value:
|
|
error:
|
|
code: internal_error
|
|
message: internal server error
|
|
ServiceUnavailableError:
|
|
description: Durable acceptance or trusted delivery inspection could not be completed.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
examples:
|
|
unavailable:
|
|
value:
|
|
error:
|
|
code: service_unavailable
|
|
message: service is unavailable
|