Skip to content

feat(email): add configurable email provider abstraction and summary email support - #264

Merged
jspada200 merged 10 commits into
AcademySoftwareFoundation:mainfrom
KrishnaAdityaSrivastava:feat/email-provider
Nov 18, 2026
Merged

jspada200 merged 10 commits into
AcademySoftwareFoundation:mainfrom
KrishnaAdityaSrivastava:feat/email-provider

Conversation

@KrishnaAdityaSrivastava

@KrishnaAdityaSrivastava KrishnaAdityaSrivastava commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

Summary

This PR introduces a configurable email provider abstraction following the existing provider pattern used throughout the backend.

Changes

  • Added a new EmailProviderBase abstraction with provider selection via configuration.
  • Added a provider factory (get_email_provider) to instantiate the configured email provider.
  • Implemented email providers for:
    • Noop
    • SMTP
    • Resend
    • SendGrid
  • Added provider interfaces for:
    • building MIME messages,
    • building summary email content,
    • sending emails.
  • Added a provider-independent EmailBuilder to generate email subject, plain text, and HTML content.
  • Added a new POST /playlists/{playlist_id}/send-summary-email endpoint for sending playlist summary emails.
  • Added request/response models and OpenAPI documentation for the new endpoint.
  • Added unit tests covering:
    • provider factory behavior,
    • email provider base interface,
    • email builder functionality.
  • Performed follow-up cleanup to reduce duplicated logic and improve maintainability.

Testing

  • I have tested these changes locally
  • I have run all relevant automated tests
  • I have verified this does not break existing workflows
  • For changes that can be tested in UI, I have included screenshots or gif animations of the changes.

How I Tested

Ran the email provider test suite locally:

docker compose exec api pytest tests/email_providers/test_email_provider_base.py -v

Verified:

  • Provider selection based on configuration.
  • Email provider factory returns the expected implementations.
  • Email builder generates the expected subject, plain text, and HTML content.
  • Summary email endpoint integrates correctly with the provider abstraction.
  • Existing automated tests continue to pass.

fixes #255

camerontarget14 and others added 4 commits October 31, 2026 21:37
favicon and social card fixes

---------

Signed-off-by: Cameron Target <camerontarget@gmail.com>
Signed-off-by: KrishnaAdityaSrivastava <krishnaadityasrivastava@gmail.com>
Signed-off-by: KrishnaAdityaSrivastava <krishnaadityasrivastava@gmail.com>
Signed-off-by: KrishnaAdityaSrivastava <krishnaadityasrivastava@gmail.com>
Signed-off-by: KrishnaAdityaSrivastava <krishnaadityasrivastava@gmail.com>
@jspada200

Copy link
Copy Markdown
Collaborator

Hi @KrishnaAdityaSrivastava thanks for taking this on. I do have a few concerns. The first is that you implemented for multiple services. Have you accually sent an email from each of these services? As a new contributor, we do want to ensure that PRs being pushed have been throughly tested.

The other concern that is the emails themselves are not designed. That being said, we can address this in the follow up PR as we gather more user stories.

For now, can you confirm that you have successfully send emails using these providers? We do not need multiple services to start. Just an SMTP example of sending the email is good to start.

@KrishnaAdityaSrivastava

Copy link
Copy Markdown
Contributor Author

Thanks for the review!

Yes, I’ve tested SMTP and Resend end-to-end locally, and both sent the summary email successfully.

For SendGrid, I’m getting a 401 from their API, so I haven’t been able to confirm it works end-to-end. I believe that’s an issue with my account/API key (my trial may have expired). I’m happy to remove it from this PR if you’d prefer to keep the scope to the providers that are verified, or keep it if you’d like to look at it. Let me know which you’d prefer.

I’m also about to push a refactor that cleans up the provider code.

On the email design, agreed. The templates are intentionally minimal for now, and I’ll iterate on them in a follow-up PR as user stories come in.

Signed-off-by: KrishnaAdityaSrivastava <krishnaadityasrivastava@gmail.com>
@jspada200

jspada200 commented Nov 5, 2026 •

Copy link
Copy Markdown
Collaborator

Few things missing:

  • Add docs for the new providers to the DNA docs. I think it is worth adding an example of how to setup the smtp provider with gmail. It was simple to setup.
  • Update the bootstrap script to allow for configuration of the email providers. You can follow the existing patterns as the prodtrack providers. For example initally asking for provider type and any keys to init the env.

Here were the setup instructions from cursor for smtp & gmail. Just needs to be addapted to the docs:

Google SMTP is wired up for the local API. Put your credentials in backend/docker-compose.local.yml on these three lines:

SMTP_USERNAME=YOUR_GMAIL_ADDRESS
SMTP_PASSWORD=YOUR_GMAIL_APP_PASSWORD
SMTP_FROM_EMAIL=YOUR_GMAIL_ADDRESS
Use the same Gmail address for SMTP_USERNAME and SMTP_FROM_EMAIL. SMTP_PASSWORD has to be a Google App Password (Account → Security → 2-Step Verification → App passwords), not your normal Gmail password. The server is already set to smtp.gmail.com on port 587 with STARTTLS, and EMAIL_PROVIDER is smtp.

That file is gitignored. The same placeholders are also in backend/example.docker-compose.local.yml so the template matches.

Signed-off-by: James Spadafora <spadjv@gmail.com>
@jspada200 jspada200 added enhancement New feature or request Backend Work Associated with the backend Current Prio A Current Priority labels Nov 5, 2026
@jspada200

Copy link
Copy Markdown
Collaborator

Hey @KrishnaAdityaSrivastava let me know if you need anything to wrap this up

Bring the branch current with main, and finish the email-provider review:
document noop, SMTP (including Gmail), Resend, and SendGrid, prompt for
them in bootstrap, and cover each provider with unit tests.

Signed-off-by: James Spadafora <spadjv@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@jspada200

Copy link
Copy Markdown
Collaborator

Updated the branch onto main and finished the remaining review notes.

  • Documented the email providers, including Gmail over SMTP, in dna-docs/deployment/email.mdx and DEPLOYMENT.md.
  • ./bootstrap.sh now asks for the email provider on first-time setup and from the settings menu, then writes the provider and its keys into backend/docker-compose.local.yml. Choices are noop, SMTP, Resend, and SendGrid.
  • Unit tests cover the factory, the summary builder, and each provider. Backend suite: 855 passed, 91.86% coverage.

@jspada200
jspada200 self-requested a review November 17, 2026 23:10
@jspada200
jspada200 merged commit ac6f610 into AcademySoftwareFoundation:main Nov 18, 2026
2 checks passed
@jspada200

Copy link
Copy Markdown
Collaborator

Thanks for your contribution!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Backend Work Associated with the backend Current Prio A Current Priority enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add email provider to send dailies summary email

3 participants