Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions DEPLOYMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -297,6 +297,33 @@ environment:

Set the frontend to match: `VITE_AUTH_PROVIDER=none` in the app `.env` (see `packages/app/.env.example`).

## Email

`POST /playlists/{playlist_id}/send-summary-email` sends a playlist summary through the provider named by `EMAIL_PROVIDER`. `./bootstrap.sh` asks for the provider on first-time setup and from the settings menu, then writes the values into `backend/docker-compose.local.yml`.

| Value | What it needs |
| --- | --- |
| `noop` | Nothing. The API logs the message and does not send it. This is the local default. |
| `smtp` | `SMTP_HOST`, `SMTP_PORT`, `SMTP_START_TLS`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_FROM_EMAIL`. |
| `resend` | `RESEND_API_KEY` and `RESEND_FROM_EMAIL` (a verified Resend sender). |
| `sendgrid` | `SENDGRID_API_KEY` and `SENDGRID_FROM_EMAIL` (a verified SendGrid sender). |

Gmail is SMTP at `smtp.gmail.com` on port `587` with STARTTLS. `SMTP_PASSWORD` is a Google App Password from Account → Security → 2-Step Verification → App passwords, not the normal Gmail password. `SMTP_FROM_EMAIL` must be the same address as `SMTP_USERNAME`. The full walkthrough is in [dna-docs/deployment/email.mdx](dna-docs/deployment/email.mdx).

```yaml
# docker-compose.local.yml – Gmail
environment:
- EMAIL_PROVIDER=smtp
- SMTP_HOST=smtp.gmail.com
- SMTP_PORT=587
- SMTP_START_TLS=true
- SMTP_USERNAME=YOUR_GMAIL_ADDRESS
- SMTP_PASSWORD=YOUR_GMAIL_APP_PASSWORD
- SMTP_FROM_EMAIL=YOUR_GMAIL_ADDRESS
```

The same placeholders are in `backend/example.docker-compose.local.yml`. `docker-compose.local.yml` is gitignored.

To test with Google auth locally:
1. Set `AUTH_PROVIDER=google` in docker-compose.local.yml
2. Add `GOOGLE_CLIENT_ID=your-client-id`
Expand Down Expand Up @@ -329,6 +356,17 @@ The following secrets must be configured in GitHub repository settings:
| `LLM_PROVIDER` | openai |
| `AUTH_PROVIDER` | `none` (noop) for local dev; `google` for production |
| `CORS_ALLOWED_ORIGINS` | Comma-separated list of allowed origins |
| `EMAIL_PROVIDER` | `noop` (local default), `smtp`, `resend`, or `sendgrid` |
| `SMTP_HOST` | SMTP server. `smtp.gmail.com` for Gmail |
| `SMTP_PORT` | SMTP port. `587` for Gmail |
| `SMTP_START_TLS` | `true` to upgrade the connection with STARTTLS |
| `SMTP_USERNAME` | SMTP username. The Gmail address when using Gmail |
| `SMTP_PASSWORD` | SMTP password. A Google App Password when using Gmail |
| `SMTP_FROM_EMAIL` | From address. Must match `SMTP_USERNAME` for Gmail |
| `RESEND_API_KEY` | Resend API key, when `EMAIL_PROVIDER=resend` |
| `RESEND_FROM_EMAIL` | Verified Resend sender |
| `SENDGRID_API_KEY` | SendGrid API key, when `EMAIL_PROVIDER=sendgrid` |
| `SENDGRID_FROM_EMAIL` | Verified SendGrid sender |

### Frontend (Build-time)

Expand Down
1 change: 1 addition & 0 deletions backend/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,7 @@ To configure ShotGrid and other local settings, create a local docker-compose ov
2. Edit `docker-compose.local.yml` and set at least:
- **ShotGrid:** To use ShotGrid, set `PRODTRACK_PROVIDER=shotgrid` (or leave unset) and set `SHOTGRID_URL`, `SHOTGRID_API_KEY`, and `SHOTGRID_SCRIPT_NAME`. To run without ShotGrid, set `PRODTRACK_PROVIDER=mock`; see [Mock production tracking](#mock-production-tracking).
- **Auth (local dev):** Keep `AUTH_PROVIDER=none` so the noop provider is used and you can sign in with any email. Change to `AUTH_PROVIDER=google` only if you need to test Google OAuth locally.
- **Email:** `EMAIL_PROVIDER=noop` logs playlist summary email and does not send it. To send mail, set `smtp`, `resend`, or `sendgrid` and the matching credentials. Gmail setup is in [Email](../dna-docs/deployment/email.mdx). `./bootstrap.sh` writes this into the local compose file.
- **LLM:** Choose an LLM provider and matching credentials. Examples:

```yaml
Expand Down
171 changes: 171 additions & 0 deletions backend/docs/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -2379,6 +2379,78 @@
"title": "SearchResult",
"type": "object"
},
"SendSummaryEmailRequest": {
"description": "Request model for sending a playlist summary email.",
"examples": [
{
"cc_email": "supervisor@studio.example",
"playlist_url": "https://example.com/playlist/45",
"to_email": "reviewer@studio.example"
}
],
"properties": {
"cc_email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional CC email address",
"title": "Cc Email"
},
"playlist_url": {
"description": "URL to the playlist",
"title": "Playlist Url",
"type": "string"
},
"to_email": {
"description": "Recipient email address",
"title": "To Email",
"type": "string"
}
},
"required": [
"to_email",
"playlist_url"
],
"title": "SendSummaryEmailRequest",
"type": "object"
},
"SendSummaryEmailResponse": {
"description": "Response model for sending a playlist summary email.",
"examples": [
{
"message_id": "msg_1234567890",
"sent_at": "2026-10-31T12:00:00Z",
"success": true
}
],
"properties": {
"message_id": {
"title": "Message Id",
"type": "string"
},
"sent_at": {
"format": "date-time",
"title": "Sent At",
"type": "string"
},
"success": {
"title": "Success",
"type": "boolean"
}
},
"required": [
"success",
"message_id",
"sent_at"
],
"title": "SendSummaryEmailResponse",
"type": "object"
},
"Session": {
"description": "DNA-owned review session (source of truth for in-review and transcription).",
"examples": [
Expand Down Expand Up @@ -5252,6 +5324,105 @@
]
}
},
"/playlists/{playlist_id}/send-summary-email": {
"post": {
"description": "Send a summary email for a playlist with all versions and draft notes.",
"operationId": "send_summary_email_playlists__playlist_id__send_summary_email_post",
"parameters": [
{
"description": "Playlist ID as issued by the production tracking provider. Opaque string; DNA passes it through without interpreting it.",
"in": "path",
"name": "playlist_id",
"required": true,
"schema": {
"title": "Playlist Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendSummaryEmailRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendSummaryEmailResponse"
}
}
},
"description": "Successful Response"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Rejected by the production tracking or transcription provider"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Missing or invalid bearer token"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Not found"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
},
"description": "Tracking system was updated but DNA bookkeeping failed; do not retry blindly"
}
},
"security": [
{
"HTTPBearer": []
}
],
"summary": "Send summary email for a playlist",
"tags": [
"Playlists"
]
}
},
"/playlists/{playlist_id}/versions": {
"get": {
"description": "Retrieve all versions in the specified playlist.",
Expand Down
20 changes: 20 additions & 0 deletions backend/example.docker-compose.local.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,15 @@
# Auth: AUTH_PROVIDER=none uses the noop provider (sign in with any email; no token validation).
# Prodtrack: Set PRODTRACK_PROVIDER=mock to use the read-only mock (no ShotGrid needed).
# To use real ShotGrid, set PRODTRACK_PROVIDER=shotgrid and SHOTGRID_URL, SHOTGRID_SCRIPT_NAME, SHOTGRID_API_KEY.
# Email:
# EMAIL_PROVIDER=noop logs the message and does not send it (local default).
# EMAIL_PROVIDER=smtp sends through SMTP. Gmail uses smtp.gmail.com:587 with
# STARTTLS. SMTP_PASSWORD is a Google App Password (Account → Security →
# 2-Step Verification → App passwords), and SMTP_FROM_EMAIL must match
# SMTP_USERNAME.
# EMAIL_PROVIDER=resend needs RESEND_API_KEY and RESEND_FROM_EMAIL.
# EMAIL_PROVIDER=sendgrid needs SENDGRID_API_KEY and SENDGRID_FROM_EMAIL.
# ./bootstrap.sh prompts for this. See dna-docs/deployment/email.mdx.
services:
api:
environment:
Expand All @@ -16,6 +25,17 @@ services:
- VEXA_API_URL=http://vexa:8056
- OPENAI_API_KEY=your-openai-api-key
- AUTH_PROVIDER=none
- EMAIL_PROVIDER=noop
- SMTP_HOST=smtp.gmail.com
- SMTP_PORT=587
- SMTP_START_TLS=true
- SMTP_USERNAME=YOUR_GMAIL_ADDRESS
- SMTP_PASSWORD=YOUR_GMAIL_APP_PASSWORD
- SMTP_FROM_EMAIL=YOUR_GMAIL_ADDRESS
- RESEND_API_KEY=your-resend-api-key
- RESEND_FROM_EMAIL=YOUR_FROM_ADDRESS
- SENDGRID_API_KEY=your-sendgrid-api-key
- SENDGRID_FROM_EMAIL=YOUR_FROM_ADDRESS
# Transcript publishing (V1, disabled by default). Set to "true" to
# expose POST /playlists/{id}/publish-transcript. See DEPLOYMENT.md
# for the ShotGrid site-setup checklist the custom entity depends on.
Expand Down
2 changes: 2 additions & 0 deletions backend/requirements.txt
Original file line number Diff line number Diff line change
Expand Up @@ -16,3 +16,5 @@ google-auth==2.0.0
requests==2.32.3
python-multipart==0.0.9
PyYAML==6.0.1
aiosmtplib>=3.0.0
sendgrid>=6.11.0
42 changes: 42 additions & 0 deletions backend/scripts/send-test-summary-email.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
#!/usr/bin/env bash
# Send one playlist summary email through POST /playlists/{playlist_id}/send-summary-email.
# The API uses whichever EMAIL_PROVIDER is configured. See dna-docs/deployment/email.mdx.

set -euo pipefail

API_BASE="${API_BASE:-http://localhost:8000}"
PLAYLIST_ID="${PLAYLIST_ID:-}"
TO_EMAIL="${TO_EMAIL:-}"
CC_EMAIL="${CC_EMAIL:-}"
PLAYLIST_URL="${PLAYLIST_URL:-http://localhost:5173}"
# AUTH_PROVIDER=none treats a Bearer value that contains @ as the sender email.
SENDER_EMAIL="${SENDER_EMAIL:-anonymous@localhost}"

if [[ -z "${PLAYLIST_ID}" || -z "${TO_EMAIL}" ]]; then
echo "Usage: PLAYLIST_ID=<shotgrid playlist id> TO_EMAIL=<recipient> $0" >&2
echo "Optional: CC_EMAIL, PLAYLIST_URL, SENDER_EMAIL, API_BASE" >&2
exit 1
fi

body="$(
PLAYLIST_URL="${PLAYLIST_URL}" TO_EMAIL="${TO_EMAIL}" CC_EMAIL="${CC_EMAIL}" python3 - <<'PY'
import json
import os

payload = {
"to_email": os.environ["TO_EMAIL"],
"playlist_url": os.environ["PLAYLIST_URL"],
}
cc = os.environ.get("CC_EMAIL") or ""
if cc:
payload["cc_email"] = cc
print(json.dumps(payload))
PY
)"

curl -sS -X POST \
"${API_BASE}/playlists/${PLAYLIST_ID}/send-summary-email" \
-H "Authorization: Bearer ${SENDER_EMAIL}" \
-H "Content-Type: application/json" \
-d "${body}"
echo
12 changes: 12 additions & 0 deletions backend/src/dna/email_providers/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
"""Email Providers package.

Provides email backend for sending emails.
"""

from dna.email_providers.email_builder import EmailBuilder
from dna.email_providers.email_provider_base import (
EmailProviderBase,
get_email_provider,
)

__all__ = ["EmailProviderBase", "get_email_provider", "EmailBuilder"]
Loading
Loading