Skip to content

Dupe'd Migrant: Unified Product Emails API

Unified Product Emails API

Problem: Our product/platform emails are not working for us, or for our customers.

Our emails don't match between products/experiences

There are so many different ways we send email to our customers. All 7-but-soon-to-be-10 of them are bad. Some of them don't even work reliably. Who wants to be separately managing customer transactional emails in all of our different projects?

Let's build one API and make it consistent and professional so that everyone can use it, and we can always reach the customers we need to.

Wait, SEVEN different email generators? What are the emails? Where do they live now? Prove it! (expand for more)
  1. GovDelivery: https://admin.govdelivery.com/abe/templates
    • Newsletters
    • Incidental customer updates
  2. pages-core and pages-mailer: https://github.com/cloud-gov/pages-core/tree/main/api/services/mailer/templates and https://github.com/cloud-gov/pages-mailer/
    • Pages sandbox expires in 7 days
    • Internal error/alert in queues (operators only)
    • Pages cloud IDP invite
    • Pages agency IDP invite
  3. cg-uaa-extras: https://github.com/cloud-gov/cg-uaa-extras/blob/main/uaaextras/templates/email/body.html
    • Cloud IDP invite
    • Reset password
  4. uaa-bot: https://github.com/cloud-gov/uaa-bot/tree/main/uaa_bot/templates
    • Account expiration in 10 days
    • Account expiration in 1 day
    • Account expired
  5. cg-sandbox: https://github.com/cloud-gov/cg-sandbox/blob/main/templates/purge.tmpl
    • Cloud.gov platform sandbox expires in x days
  6. buildpack-notify:
  7. PayloadCMS
  8. Soon to be Console/cg-ui, to let folks know about billing things
  9. Also soon to be GitLab/Workshop
  10. Somewhat less soonly, Notify.gov's product/account emails?

There are other emails I can't tell if are in use, like:

The billing and usage service needs emails for it to really work

If we don't build this, we will continue to have mismatched emails, and we still won't have a way to send any emails from the Console about billing, usage, limits, service disruptions, etc. Building a billing/usage service without an accompanying alert service (like when you're approaching your plan limit) makes the billing service largely invisible, and all but guarantees people won't realize they're approaching a limit until they're over.

This is foundational for eventually handling all customer comms

Getting this API in place also means that soon (next quarter?) we can replace GovDelivery for customer-facing comms. This is important because right now, we share our subscriber lists across TTS, so if someone hit "unsubscribe from all" because of someone else's noisy emails anywhere in TTS, they're permanently deny-listed across the whole account, and we can never send them an email again.

Right now, we don't own any of our customer comms channels

Until this exists, we have no way to contact all of our current customers consistently and reliably. Not for account alerts, not for service announcements, not for billing usage, nothing.

Appetite

How much time we want to spend and how that constrains the solution

  • [We have appetite for 6? weeks]

Solution: an emails microservice

We already have the front-end email builder part that can generate consistent HTML emails from templates and components: https://github.com/cloud-gov/emails; the need is not more people to build HTML tables.

We'll design a simple API/microservice for Cloud.gov's interfaces and managed apps that will send email through SES when we tell it which email to send, give it an email address and possibly a few mail merge type fields like a specific link or app/instance/org name. (or whatever Notify does that's like this)

Short term, this replaces the existing disparate email situationships across our repos listed above.

What new transactional emails we want this to handle/replace... for Workshop, or PayloadCMS, or billing/usage info... let's discuss and shape (will depend on appetite).

As for whether this immediately replaces our need for GovDelivery -- no, but it's a step towards that future.

Rabbit Holes

Help me answer these to reduce risk or understand scope:

  • I have literally no idea how hard this is to execute within the BOSH and other repos. It's something we've almost always let our tools handle. How hard is this?? How much does Notify already do for us if we plug it in and give it the juice?
  • How do all these different systems talk to the new email API? Can we get buy in from the other teams for the integration points?

No-Gos

  • This is not a WYSIWYG email builder. This is not necessarily even an HTML email composer. We don't need to use the React email generator linked above to make the emails during the workflows -- we can just have the templates prebuilt, waiting to be sent, by API.
  • It's not a GovDelivery/MailChimp-type replacement. Yet.
  • This does not schedule emails -- they'll be sent as soon as the API is prepared to (given any SES rate limiting or throttling necessary). It's up to the app using the API to ask for the email to be sent when it's needed.
  • This does not need to manage subscriber/account/org/user lists -- the email recipient (and name, org, app, etc) is a concern of the app/project that talks to this API, not this API's responsibility to manage. So, whatever logic and jobs you've been using to decide who-gets-what-email keeps happening.
  • This does not need to handle unsubscribes, because transactional emails are not part of CAN-SPAM and don't need to be (and shouldn't be) unsubscribed from.
  • This does not yet need to handle multiple 'from' or reply-to addresses; just one will do.
  • For now, this does not need to handle both rich text and plaintext; just send the rich text one. This API won't know whether the user would prefer one or the other anyways, and has no mechanism for 'remembering' such a selection.
  • This does not need to send custom emails, one-off emails, or deeply configurable emails.
  • There's no need for a UI of any kind; this is a backend mechanism to offload/centralize sending pre-formatted HTML emails about things we can anticipate happening regularly.
Edited by Zach Rollyson