mirror of
https://github.com/zulip/zulip.git
synced 2025-11-10 17:07:07 +00:00
aa845e7f60
ScheduledJob was written for much more generality than it ended up being used for. Currently it is used by send_future_email, and nothing else. Tailoring the model to emails in particular will make it easier to do things like selectively clear emails when people unsubscribe from particular email types, or seamlessly handle using the same email on multiple realms.
50 lines
2.6 KiB
Markdown
50 lines
2.6 KiB
Markdown
# Email
|
|
|
|
This page has developer documentation on the Zulip email system. If you're
|
|
trying to configure your server to send email, you might be looking for our
|
|
guide to [sending outgoing email](prod-email.html). If you're trying to
|
|
configure an email integration to receive incoming email (e.g. so that users
|
|
can reply to missed message emails via email), you might be interested in
|
|
our instructions for
|
|
[setting up an email integration](https://zulipchat.com/integrations/#email).
|
|
|
|
On to the documentation. Zulip's email system is fairly straightforward,
|
|
with only a few things you need to know to get started.
|
|
|
|
* All email templates are in `templates/zerver/emails/`. Each email has three
|
|
template files: `<template_prefix>.subject`, `<template_prefix>.txt`, and
|
|
`<template_prefix>.html`. Email templates, along with all other templates
|
|
in the `templates/` directory, are Jinja2 templates.
|
|
* Most of the CSS and HTML layout for emails is in `email_base.html`. Note
|
|
that email has to ship with all of its CSS and HTML, so nothing in
|
|
`static/` is useful for an email. If you're adding new CSS or HTML for an
|
|
email, there's a decent chance it should go in `email_base.html`.
|
|
* All email is eventually sent by `zerver.lib.send_email.send_email`. There
|
|
are several other functions in `zerver.lib.send_email`, but all of them
|
|
eventually call the `send_email` function. The most interesting one is
|
|
`send_future_email`. The `ScheduledEmail` entries are eventually processed
|
|
by a cron job that runs `zerver/management/commands/deliver_email.py`.
|
|
* A good way to find a bunch of example email pathways is to `git grep` for
|
|
`zerver/emails` in the `zerver/` directory.
|
|
|
|
One slightly complicated decision you may have to make when adding an email
|
|
is figuring out how to schedule it. There are 3 ways to schedule email.
|
|
* Send it immediately, in the current Django process, e.g. by calling
|
|
`send_email` directly. An example of this is the `confirm_registration`
|
|
email.
|
|
* Add it to a queue. An example is the `invitation` email.
|
|
* Send it (approximately) at a specified time in the future, using
|
|
`send_future_email`. An example is the `followup_day2` email.
|
|
|
|
Email takes about a quarter second per email to process and send. Generally
|
|
speaking, if you're sending just one email, doing it in the current process
|
|
is fine. If you're sending emails in a loop, you probably want to send it
|
|
from a queue. Documentation on our queueing system is available
|
|
[here](queuing.html).
|
|
|
|
## Testing
|
|
|
|
All emails are printed to the console in the development environment. A
|
|
great way to see what most of our emails look like (with fixture data) is by
|
|
going to `emails/` in the browser.
|