docs(email): SMTP setup, the three postures, and the upgrade note
The operator-facing half of engagement Phase 1. README's stack table and security section, plus both .env.example files, all pointed at the removed Connect Gmail flow. The env comments now name the three supported postures rather than one provider — a relay as the recommendation, smtp.gmail.com:587 with an app password as the shortest migration, an unauthenticated local MTA as the third — and point at docs/website/UPGRADE_NOTES.md for the deployment this actually happens to. The OpenAPI spec is regenerated: two routes gone, three annotations rewritten, and the dashboard's new warnings[] documented. Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -1029,6 +1029,25 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"warnings": {
|
||||
"type": "array",
|
||||
"description": "Operator warnings needing action; empty when there is nothing to say",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "string",
|
||||
"example": "EMAIL_TRANSPORT_MIGRATION"
|
||||
},
|
||||
"message": {
|
||||
"type": "string"
|
||||
},
|
||||
"href": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"recent_activity": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
@@ -1205,11 +1224,11 @@
|
||||
"tags": [
|
||||
"Admin · Email"
|
||||
],
|
||||
"summary": "Get email delivery config + status (admin only)",
|
||||
"description": "",
|
||||
"summary": "Get email delivery config, status and the transport catalog (admin only)",
|
||||
"description": "Credentials are write-only: secret fields are never returned, only a per-field `secretsSet` flag. `transports` carries each registered transport's declared credential fields, which is what the admin form renders.",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Config (refresh token stripped) + status",
|
||||
"description": "Config (secrets stripped) + status + transport catalog",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
@@ -1257,7 +1276,7 @@
|
||||
"Admin · Email"
|
||||
],
|
||||
"summary": "Update email delivery config (admin only)",
|
||||
"description": "Set the From display name and enabled toggle. Enabling requires a connected Gmail account.",
|
||||
"description": "Set the transport, sender identity, credentials and enabled toggle. `credential` is a patch against the stored blob — a secret field submitted empty keeps its stored value. Enabling requires complete credentials and a sender address.",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Updated config",
|
||||
@@ -1271,7 +1290,7 @@
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Cannot enable before connecting a mailbox",
|
||||
"description": "Unknown transport, or cannot enable without complete credentials and a sender address",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
@@ -1318,9 +1337,25 @@
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"transport": {
|
||||
"type": "string",
|
||||
"example": "smtp"
|
||||
},
|
||||
"senderEmail": {
|
||||
"type": "string",
|
||||
"format": "email"
|
||||
},
|
||||
"senderName": {
|
||||
"type": "string"
|
||||
},
|
||||
"replyTo": {
|
||||
"type": "string",
|
||||
"format": "email"
|
||||
},
|
||||
"credential": {
|
||||
"type": "object",
|
||||
"additionalProperties": true
|
||||
},
|
||||
"enabled": {
|
||||
"type": "boolean"
|
||||
}
|
||||
@@ -1331,128 +1366,16 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/admin/email/connect/callback": {
|
||||
"get": {
|
||||
"tags": [
|
||||
"Admin · Email"
|
||||
],
|
||||
"summary": "OAuth2 callback — stores the refresh token, redirects to Settings",
|
||||
"description": "",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "code",
|
||||
"in": "query",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "state",
|
||||
"in": "query",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "error",
|
||||
"in": "query",
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"302": {
|
||||
"description": "Redirect back to /admin/settings"
|
||||
}
|
||||
},
|
||||
"security": [
|
||||
{
|
||||
"cookieAuth": []
|
||||
},
|
||||
{
|
||||
"bearerAuth": []
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"/api/v1/admin/email/connect/start": {
|
||||
"get": {
|
||||
"tags": [
|
||||
"Admin · Email"
|
||||
],
|
||||
"summary": "Begin the Gmail OAuth2 connect flow (admin only)",
|
||||
"description": "Returns { url } to redirect the browser to Google. Reuses the google SSO OAuth client.",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Authorization URL",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"url": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Google OAuth client not configured",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/Error"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "Not authenticated",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/Error"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"403": {
|
||||
"description": "Admin role required",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/Error"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error"
|
||||
}
|
||||
},
|
||||
"security": [
|
||||
{
|
||||
"cookieAuth": []
|
||||
},
|
||||
{
|
||||
"bearerAuth": []
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"/api/v1/admin/email/disconnect": {
|
||||
"post": {
|
||||
"tags": [
|
||||
"Admin · Email"
|
||||
],
|
||||
"summary": "Disconnect Gmail and disable email (admin only)",
|
||||
"summary": "Clear the stored credentials and disable email (admin only)",
|
||||
"description": "",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Disconnected config",
|
||||
"description": "Cleared config",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
@@ -1502,7 +1425,7 @@
|
||||
"Admin · Email"
|
||||
],
|
||||
"summary": "Send a test email (admin only)",
|
||||
"description": "",
|
||||
"description": "The real verification of the configuration — host, port, TLS mode, credentials, and whether the relay accepts the configured sender. Failures return a specific diagnostic.",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Sent",
|
||||
|
||||
Reference in New Issue
Block a user