Skip to content

Commit 0bbb0b4

Browse files
cwickhamcwickham
committed
Link to Posit Connect docs for email
1 parent b917267 commit 0bbb0b4

File tree

2 files changed

+2
-164
lines changed

2 files changed

+2
-164
lines changed

‎docs/blog/posts/2024-01-24-1.4-release/index.qmd

+1-3
Original file line numberDiff line numberDiff line change
@@ -172,9 +172,7 @@ Some other highlights include:
172172

173173
- [Easy Binder Configuration for Quarto Projects](/docs/projects/binder.qmd)---Support for generating files required to deploy a Quarto project to [Binder](mybinder.org){.external}.
174174

175-
- [Connect Email Generation](/docs/prerelease/1.4/email.qmd)[^email]---Extends the `html` output format so that HTML/text emails can be created and selectively delivered through Posit Connect.
176-
177-
[^email]: The [quarto.org](/docs/prerelease/1.4/email.qmd) highlight documentation will give you a good preview of the feature, but more complete docs are coming soon on [docs.posit.co/connect](https://docs.posit.co/connect/user/quarto/){.external}.
175+
- [Connect Email Generation](https://docs.posit.co/connect/user/quarto/#email-customization){.external}---Extends the `html` output format so that HTML/text emails can be created and selectively delivered through Posit Connect.
178176

179177
- [Publish to Posit Cloud](/docs/publishing/posit-cloud.qmd)---Adds `posit-cloud` as a venue for `quarto publish`.
180178

‎docs/prerelease/1.4/email.qmd

+1-161
Original file line numberDiff line numberDiff line change
@@ -8,165 +8,5 @@ title: "Connect Email Generation"
88

99
Quarto v1.4 adds an email generation feature that can be used for HTML documents published in [Posit Connect](https://posit.co/products/enterprise/connect/). This feature extends the HTML output format and enables users to generate HTML and/or text emails that can be selectively delivered when the document is rendered in Connect.
1010

11-
## Authoring a Connect Email
11+
Read full documentation of the feature on the [Posit Connect Documentation](https://docs.posit.co/connect/user/quarto/#email-customization){.external}.
1212

13-
A connect email is authored as part of an HTML document. A typical HTML document with an associated Connect email might look something like this:
14-
15-
```markdown
16-
---
17-
format: email
18-
---
19-
20-
The report content. Anything that is here is not part of the email message.
21-
22-
::: {.email}
23-
24-
::: {.subject}
25-
The subject line.
26-
:::
27-
28-
::: {.email-text}
29-
An optional text-only version of the email message..
30-
:::
31-
32-
The HTML email content. Here you can add code cells, produce images, and write accompanying text.
33-
This content is not seen when viewing the rendered document on Connect (it's only
34-
seen when sending an email from the Connect document page). Emails from Connect
35-
can be sent manually, and they can also be scheduled.
36-
37-
:::
38-
39-
Any additional report content not part of the email message.
40-
41-
```
42-
43-
The key things to note are:
44-
45-
* In the document YAML the format is set to email: `format: email`.
46-
47-
* The email content goes inside a fenced div (`:::`) with the class `.email`. The `.email` div can appear anywhere in the HTML document so long as it only appears once. Inside this `.email` div:
48-
49-
* The subject line goes inside a div with the class `.subject`. The `.subject` div is **required**, and should only contain text.
50-
51-
* A text-only version of the email goes inside a div with the class `.email-text`. The `email-text` div is **optional**, and will serve as a fallback should an email client not be able to display HTML email.
52-
53-
Any images generated in the email portion of the document (for example, static plots) will be embedded in the email message as Base64 images. This ensures the email content is be self-contained and doesn't need to be stored elsewhere and retrieved. By necessity, interactive or otherwise complex outputs cannot be used since they cannot be understood by email clients.
54-
55-
### Adding Attachments
56-
57-
If your reporting creates data files (like CSVs or Excel files), these can attached to the email message. You can do this by declaring the file names in `email-attachments` in the YAML header. Say, for instance, the files `"raw_data.csv"` and `"summary.csv"` were written to the working directory through a render of the document. You could make these available as email attachments like this:
58-
59-
```yaml
60-
---
61-
format: email
62-
email-attachments:
63-
- raw_data.csv
64-
- summary.csv
65-
---
66-
```
67-
68-
It doesn't matter where in the document those files were generated (e.g., inside or outside of the `.email` div), the key thing is that those files _were_ generated through a document render.
69-
70-
### Suppressing Scheduled Emails
71-
72-
Emails on Connect can be set to regularly send upon render. However, you may have conditions where you would like an email associated with the main document _not_ be sent upon rendering at the scheduled time --- this is known in Connect as suppressing a scheduled email.
73-
74-
You can control whether an email is sent, using a div with the `.email-scheduled` class. The contents of the `.email-scheduled` div should be `TRUE`, `True`, or `"yes"` (something _truthy_) if we want emails to be sent unimpeded. To suppress the sending of email on a Connect render, the contents of the `.email-scheduled` div should be `FALSE`, `False`, or `"no"` (which is _falsy_).
75-
76-
Here is an example where the associated email is _only_ sent when a certain condition is true. The example uses R but could equivalently be done with Python or any of the other computation engines available in Quarto.
77-
78-
````markdown
79-
---
80-
format: email
81-
---
82-
83-
```{{r}}
84-
#| echo: false
85-
86-
library(profitcalcs)
87-
88-
profit <- determine_profit()
89-
90-
if (profit < 0) {
91-
92-
# Send email since we have a reason for it
93-
94-
subject <- "We have a problem here"
95-
send_email <- TRUE
96-
97-
} else {
98-
99-
# Don't send email; everything is fine
100-
101-
subject <- "No email. This won't be sent"
102-
send_email <- FALSE
103-
}
104-
```
105-
106-
The email body follows.
107-
108-
::: {.email}
109-
110-
Our profit was `{r} profit` this quarter and we felt you should know.
111-
112-
::: {.subject}
113-
`{r} subject`
114-
:::
115-
116-
::: {.email-scheduled}
117-
`{r} send_email`
118-
:::
119-
120-
:::
121-
122-
````
123-
124-
The condition for sending or not, whether `profit < 0`, is computed in the first code cell. The main email div is set up with child divs to handle the email subject (`.subject`) and whether the email should be sent (`.email-scheduled`). Inline R code injects those divs with values stored in variables; since `send_email` will either be `TRUE` or `FALSE` the email will be sent (or not) depending on the value of `profit`.
125-
126-
## Previewing an Email
127-
128-
When you locally render a document with the `email` format, you'll get HTML output that excludes the `.email` div. For faster email development and iteration, you'll likely want to preview the email content itself.
129-
130-
To preview the email content, set `email-preview: true` in the document's YAML header:
131-
132-
```{.yaml filename="report.qmd"}
133-
---
134-
format: email
135-
email-preview: true
136-
---
137-
```
138-
139-
With this option set, when you render, e.g. with `quarto render report.qmd`, an HTML file `email-preview.html` will be produced in the `email-preview/` directory.
140-
141-
When viewing the HTML file, note that the footer of the email will be an abbreviated version of what is normally generated through a Connect render. Also, there won't be any indication that attachments are included as part of the email (though email clients do tend to present email attachments differently: either as an extended footer and alternately as indicated in the client's top UI for a message).
142-
143-
144-
## Deploying to Connect
145-
146-
Posit Connect has a two ways to deploy documents: documents are rendered locally, then sent to the Connect server; or document source code (along with any needed resources) is sent to the Connect server and rendered on the server. Quarto emails can only be rendered and sent when using the latter scheme.
147-
148-
::: {.panel-tabset}
149-
150-
### R
151-
152-
To do this in an R-based workflow, publish the .qmd document using the `quarto_publish_doc()` function from the `quarto` package. Here's an example of how this works:
153-
154-
```r
155-
library(quarto)
156-
157-
quarto_publish_doc(
158-
"r_report.qmd",
159-
name = "quarto-r-report-with-email",
160-
server = "<Connect server address>",
161-
account = "<username>",
162-
render = "server"
163-
)
164-
```
165-
166-
### Python
167-
168-
If using a Python-based workflow, all principles for formatting the document still apply. The method of deploying is a bit different: one should use the `rsconnect-python` library for deployment. It offers a CLI for deployment and many examples are available in the [project README](https://github.com/rstudio/rsconnect-python).
169-
170-
:::
171-
172-
Once the render on Connect succeeds, navigate to the report in your Connect instance. In the rendered view of the report, the email portion is not visible. Given you are the author of the report you can send yourself the email by clicking on the email icon on the top navigation bar and selecting the option to send the email to yourself. Should the email look satisfactory, you can use various Connect options for the given report to regularly send the email upon render (at a frequency of your choosing) to authorized individuals added to this document.

0 commit comments

Comments
 (0)