Type:	Package
Version:	0.3.6
Title:	Easily Send HTML Email Messages
Description:	Compose and send out responsive HTML email messages that render perfectly across a range of email clients and device sizes. Helper functions let the user insert embedded images, web link buttons, and 'ggplot2' plot objects into the message body. Messages can be sent through an 'SMTP' server, through the 'Posit Connect' service, or through the 'Mailgun' API service https://www.mailgun.com/.
License:	MIT + file LICENSE
URL:	https://github.com/rstudio/blastula, https://pkgs.rstudio.com/blastula/
BugReports:	https://github.com/rstudio/blastula/issues
Depends:	R (≥ 3.6)
Imports:	base64enc (≥ 0.1-3), commonmark (≥ 1.7), curl (≥ 5.2), digest, dplyr (≥ 1.1.0), fs (≥ 1.3.1), getPass (≥ 0.2-2), here (≥ 1.0.0), htmltools (≥ 0.5.7), httr (≥ 1.4.0), jsonlite (≥ 1.8.0), magrittr (≥ 1.5), mime (≥ 0.6), rlang (≥ 1.0), rmarkdown, stringr (≥ 1.4.0), uuid (≥ 0.1-2)
Suggests:	covr, ggplot2, glue, testthat (≥ 3.0.0), keyring, knitr, xml2, openxlsx, withr
SystemRequirements:	pandoc (>= 1.12.3) - http://pandoc.org
Encoding:	UTF-8
RoxygenNote:	7.3.2
Config/testthat/edition:	3
Language:	en-US
NeedsCompilation:	no
Packaged:	2025-04-02 22:21:00 UTC; riannone
Author:	Richard Iannone [aut, cre], Joe Cheng [aut], Jeroen Ooms [ctb], Ted Goas [cph] (cerberus-meta.html), Posit Software, PBC [cph, fnd]
Maintainer:	Richard Iannone <rich@posit.co>
Repository:	CRAN
Date/Publication:	2025-04-03 08:10:07 UTC

The magrittr pipe

Description

The blastula package uses the pipe function, ⁠\%>\%⁠, to turn function composition into a series of imperative statements.

Add a file attachment to an email message

Description

This gives us a simple interface for attaching a file to the email object. When it comes time to send the email through smtp_send(), all attachments (specified by individual calls to add_attachment()) will be faithfully transmitted along with the message.

Usage

add_attachment(
  email,
  file,
  content_type = mime::guess_type(file),
  filename = basename(file)
)

Arguments

Details

There are options available to specify the attachment's MIME type, its disposition, and customize the attachment's recipient-facing filename.

Create an HTML fragment for a CTA button

Description

Create the HTML fragment for a call to action button. This can be used as part of the email body but, since this HTML, it must be contained within md(). There are options to specify the button text, the URL, and the button's alignment.

Usage

add_cta_button(url, text, align = "center")

Arguments

Value

A character object with an HTML fragment that can be placed inside the message body wherever the CTA button should appear.

Examples

# Create the button as an HTML fragment
cta_button <-
  add_cta_button(
    url = "http://www.website.net",
    text = "Press This Button"
  )

# Include the button in the email
# message body by using it as part of
# a vector inside of `md()`
email <-
  compose_email(
    body = md(
      c(
  "Pressing the button will take
  you to an example website",
  cta_button
      )
    )
  )

if (interactive()) email

Create an HTML fragment for an embedded ggplot image

Description

Add an ggplot plot inside the body of the email with this helper function.

Usage

add_ggplot(
  plot_object,
  width = 5,
  height = 5,
  alt = NULL,
  align = c("center", "left", "right", "inline"),
  float = c("none", "left", "right")
)

Arguments

Value

An HTML fragment that can be placed inside the message body wherever the plot image should appear.

Examples

library(ggplot2)

# Create a ggplot plot
plot <-
  ggplot(
    data = mtcars,
    aes(x = disp, y = hp,
        color = wt, size = mpg)) +
  geom_point()

# Create an HTML fragment that
# contains an the ggplot as an
# embedded plot
plot_html <-
  add_ggplot(plot_object = plot)

# Include the plot in the email
# message body by simply referencing
# the `plot_html` object
email <-
  compose_email(
    body = md(
      c(
"Hello!

Here is a plot that will change
the way you look at cars forever.\n",
plot_html,
"Let me know what you think
about it!"
      )
    )
  )

if (interactive()) email

Create an HTML fragment for an embedded image

Description

Add a local image inside the body of the email with this helper function.

Usage

add_image(
  file,
  alt = "",
  width = 520,
  align = c("center", "left", "right", "inline"),
  float = c("none", "left", "right")
)

Arguments

Value

A character object with an HTML fragment that can be placed inside the message body wherever the image should appear.

Examples

# Create an HTML fragment that
# contains an image
img_file_path <-
  system.file(
    "example_files",
    "test_image.png",
    package = "blastula"
  )

img_file_html <-
  add_image(file = img_file_path)

# Include the image in the email
# message body by simply referencing
# the `img_file_html` object
email <-
  compose_email(
    body = md(
      c(
"Hello,

Here is an image:\n",
img_file_html
      )
    )
  )

if (interactive()) email

Deploy a local image to Imgur and create an image tag

Description

Getting images into email message bodies (and expecting them to appear for the recipient) can be a harrowing experience. External images (i.e., available at public URLs) work exceedingly well and most email clients will faithfully display these images. With the imgur_image() function, we can take a local image file or a ggplot2 plot object and send it to the Imgur service, and finally receive an image (⁠<img>⁠) tag that can be directly inserted into an email message using compose_email().

Usage

add_imgur_image(
  image,
  client_id = NULL,
  alt = NULL,
  width = 520,
  align = c("center", "left", "right", "inline"),
  float = c("none", "left", "right")
)

Arguments

Details

To take advantage of this, we need to first have an account with Imgur and then obtain a Client-ID key for the Imgur API. This can be easily done by going to ⁠https://api.imgur.com/oauth2/addclient⁠ and registering an application. Be sure to select the OAuth 2 authorization type without a callback URL.

Value

An HTML fragment that can be placed inside the message body wherever the image should appear.

Create a string with a more readable date/time

Description

Add a nicely-formatted date/time string inside the body of the email with this helper function. We can provide a POSIXct date-time object or use the current date/time/tz (based on the user's locale information at the time of the function call). There are options to specify whether the date, time, and time zone parts are to be included.

Usage

add_readable_time(time = NULL, use_date = TRUE, use_time = TRUE, use_tz = TRUE)

Arguments

Value

A character object that can be placed inside any message component message wherever the function is called.

Examples

# Generate a date and time value using a specified date/time value
add_readable_time(
  time = ISOdatetime(
    year = 2022,
    month = 3,
    day = 15,
    hour = 8,
    min = 30,
    sec = 0,
    tz = "GMT"
   ),
  use_tz = FALSE
)

Specify the components of an article

Description

The article() function is used exclusively within block_articles(), and having one, two, or three calls will arrange the articles in a row (or as a column of articles at lower screen widths).

Usage

article(image = NULL, title = NULL, content = NULL, link = NULL)

Arguments

Examples

# We can define an article with a link
# to an image, title text, some content,
# and a link to relevant content
article <-
  article(
    image = "https://i.imgur.com/dxSXzGb.jpg",
    title = "Hong Kong",
    content =
      "Once home to fishermen and farmers, \\
      modern Hong Kong is a teeming, \\
      commercially-vibrant metropolis where \\
      Chinese and Western influences fuse.",
    link = "http://www.discoverhongkong.com"
  )

if (interactive()) article

Associate an email when publishing an R Markdown document to Posit Connect

Description

This function is used to customize emails sent by Posit Connect in conjunction with publishing an R Markdown document. It associates a custom email message with the main R Markdown document, which Connect can send to selected recipients. The main input is a rendered email message, which can be produced by either the render_email() or render_connect_email() function.

Usage

attach_connect_email(
  email = NULL,
  subject = NULL,
  attachments = NULL,
  attach_output = FALSE,
  text = NULL,
  preview = TRUE
)

Arguments

Details

Since this function needs to be invoked within an R Markdown document, the chunk option echo=FALSE is useful here (so that viewers of the rendered document don't have to unnecessarily read code related to email inclusion). While the output is invisible, any errors related to rendering will be visible to the author.

The R Markdown blastula_email output format

Description

The R Markdown blastula_email output format

Usage

blastula_email(
  content_width = "1000px",
  toc = FALSE,
  toc_depth = 3,
  toc_float = FALSE,
  number_sections = FALSE,
  section_divs = TRUE,
  fig_width = 5.35,
  fig_height = 5,
  fig_retina = 2,
  fig_caption = TRUE,
  dev = "png",
  smart = TRUE,
  self_contained = TRUE,
  template = "blastula",
  includes = NULL,
  keep_md = FALSE,
  md_extensions = NULL,
  connect_footer = FALSE,
  ...
)

Arguments

Default template for compose_email()

Description

A template function that is suitable for using as the template argument of compose_email(). Template functions should generally not be called directly. When implementing your own template function, you must include parameters for html_body, html_header, html_footer, and title; you may also optionally add your own parameters, which callers to compose_email() can provide through the ... argument.

Usage

blastula_template(
  html_body,
  html_header,
  html_footer,
  title,
  content_width = "1000px",
  font_family = "Helvetica, sans-serif"
)

Arguments

Value

A string containing a complete HTML document.

A block of one, two, or three articles with a multicolumn layout

Description

With block_articles(), we can create a single- or multi-column layout of articles. The articles are responsive to the screen width, so side-by-side articles will collapse and any of the optional images will resize accordingly. The function can accept one to three article() calls, each with varying amounts of text and imagery. Like all ⁠block_*()⁠ functions, block_articles() must be placed inside of blocks() and the resultant blocks object can be provided to the body, header, or footer arguments of compose_email().

Usage

block_articles(...)

Arguments

Examples

# Create a block of three, side-by-side
# articles with three `article()`
# calls inside of `block_articles()`,
# itself placed in `blocks()`
email <-
  compose_email(
    body =
      blocks(
        block_articles(
          article(
            image = "https://i.imgur.com/XMU8yJa.jpg",
            title = "Taiwan",
            content =
              "It is a thriving mosaic of tradition,
              culture, and high-tech development,
              merging Eastern and Western influences."
          ),
          article(
            image = "https://i.imgur.com/aYOm3Tk.jpg",
            title = "Japan",
            content =
              "Japan is an archipelago consisting
              of 6,852 islands along East Asia's
              Pacific Coast."
          ),
          article(
             image = "https://i.imgur.com/ekjFVOL.jpg",
             title = "Singapore",
             content =
               "Singapore is an island city-state
               in Southeast Asia. It's lies at the
               southern tip of the Malay Peninsula."
          )
        )
      )
    )

if (interactive()) email

A block of social sharing icons with links

Description

With block_social_links(), we can create a block of social sharing links and links to websites, email, or RSS feeds. The function can accept as many social_link() calls as seen fit to email. Like all ⁠block_*()⁠ functions, block_social_links() must be placed inside of blocks() and the resultant blocks object can be provided to the body, header, or footer arguments of compose_email().

Usage

block_social_links(...)

Arguments

Examples

# Create an email message with some
# articles in the `body`; in the footer,
# add some social sharing icons linking
# to web content using `block_social_links()`
email <-
  compose_email(
    body =
      blocks(
        block_title("Exciting Travel Destinations"),
        block_articles(
          article(
            image = "https://i.imgur.com/dxSXzGb.jpg",
            title = "Hong Kong",
            content =
              "Once home to fishermen and farmers,
              modern Hong Kong is a teeming,
              commercially-vibrant metropolis where
              Chinese and Western influences fuse."
          ),
          article(
            image = "https://i.imgur.com/bJzVIrG.jpg",
            title = "Australia",
            content =
              "Australia ranks as one of the best
              places to live in the world by all
              indices of income, human development,
              healthcare, and civil rights."
          )
        )
      ),
    footer =
      blocks(
        block_text("Thanks for reading! Find us here:"),
        block_social_links(
          social_link(
            service = "pinterest",
            link = "https://www.pinterest.ca/TravelLeisure/",
            variant = "color"
          ),
          social_link(
            service = "tripadvisor",
            link = "https://www.tripadvisor.ca/TravelersChoice",
            variant = "color"
          )
        )
      )
  )

if (interactive()) email

A spacer block

Description

With block_spacer() we can more easily define an area of whitespace in a block-based layout. This function is meant to be easily combined with other ⁠block_*()⁠ functions. Like all ⁠block_*()⁠ functions, block_spacer() must be placed inside of blocks() and the resultant blocks object can be provided to the body, header, or footer arguments of compose_email().

Usage

block_spacer()

Examples

# Create a block of two, side-by-side
# articles with two `article()` calls
# inside of `block_articles()`, itself
# placed in `blocks()`; include some
# introductory text and place extra
# space around that text (with
# `block_spacer()`)
email <-
  compose_email(
    body =
      blocks(
        block_spacer(),
        block_text(
          "These are two of the cities I visited this year.
          I liked them a lot, so, I'll visit them again!"),
        block_spacer(),
        block_articles(
          article(
            image = "https://i.imgur.com/dig0HQ2.jpg",
            title = "Los Angeles",
            content =
              "I want to live in Los Angeles.
              Not the one in Los Angeles.
              No, not the one in South California.
              They got one in South Patagonia."
          ),
          article(
            image = "https://i.imgur.com/RUvqHV8.jpg",
            title = "New York",
            content =
              "Start spreading the news.
              I'm leaving today.
              I want to be a part of it.
              New York, New York."
          )
        )
      )
    )

if (interactive()) email

A block of text

Description

With block_text() we can define a text area and this can be easily combined with other ⁠block_*()⁠ functions. The text will take the entire width of the block and will resize according to screen width. Like all ⁠block_*()⁠ functions, block_text() must be placed inside of blocks() and the resultant blocks object can be provided to the body, header, or footer arguments of compose_email().

Usage

block_text(text, align = c("left", "center", "right", "justify"))

Arguments

Examples

# Create a block of two, side-by-side
# articles with two `article()` calls
# inside of `block_articles()`, itself
# placed in `blocks()`; also, include some
# text at the top with `block_text()`
email <-
  compose_email(
    body =
      blocks(
        block_text(
          "These are two of the cities I visited this year.
          I liked them a lot, so, I'll visit them again!"),
        block_articles(
          article(
            image = "https://i.imgur.com/dig0HQ2.jpg",
            title = "Los Angeles",
            content =
              "I want to live in Los Angeles.
              Not the one in Los Angeles.
              No, not the one in South California.
              They got one in South Patagonia."
          ),
          article(
            image = "https://i.imgur.com/RUvqHV8.jpg",
            title = "New York",
            content =
              "Start spreading the news.
              I'm leaving today.
              I want to be a part of it.
              New York, New York."
          )
        )
      )
    )

if (interactive()) email

A block with large title text

Description

With block_title() we can define a title text area and this can be easily combined with other ⁠block_*()⁠ functions. The title will take the entire width of the block and will resize according to screen width. Like all ⁠block_*()⁠ functions, block_title() must be placed inside of blocks() and the resultant blocks object can be provided to the body, header, or footer arguments of compose_email().

Usage

block_title(title)

Arguments

Examples

# Create a block of two, side-by-side
# articles with two `article()` calls
# inside of `block_articles()`, itself
# placed in `blocks()`; also, include a
# title at the top with `block_title()`
email <-
  compose_email(
    body =
      blocks(
        block_title("Two Cities I Visited Recently"),
        block_articles(
          article(
            image = "https://i.imgur.com/dig0HQ2.jpg",
            title = "Los Angeles",
            content =
              "I want to live in Los Angeles.
              Not the one in Los Angeles.
              No, not the one in South California.
              They got one in South Patagonia."
          ),
          article(
            image = "https://i.imgur.com/RUvqHV8.jpg",
            title = "New York",
            content =
              "Start spreading the news.
              I'm leaving today.
              I want to be a part of it.
              New York, New York."
          )
        )
      )
    )

if (interactive()) email

An enclosure for all HTML block functions

Description

To contain all of the block-based HTML ⁠block_*()⁠ calls, we should use the blocks() function. We can pass the resulting blocks object to either of the body, header, and footer arguments of compose_email().

Usage

blocks(...)

Arguments

Examples

# This is an example of how a
# title and text looks in each of
# the three content areas
email <-
  compose_email(
    header =
      blocks(
        block_title("This is a Title in the **Header**"),
        block_text("This is text in the **Header**.")
      ),
    body =
      blocks(
        block_title("This is a Title in the **Body**"),
        block_text("This is text in the **Body**.")
      ),
    footer =
      blocks(
        block_title("This is a Title in the **Footer**"),
        block_text("This is text in the **Footer**.")
      )
  )

if (interactive()) email

Create the email message body

Description

The compose_email() function allows us to easily create an email message. We can incorporate character vectors into the message body, the header, or the footer.

Usage

compose_email(
  body = NULL,
  header = NULL,
  footer = NULL,
  title = NULL,
  ...,
  template = blastula_template
)

Arguments

Value

An email_message object.

Examples

# Create a simple email message using
# Markdown-formatted text in the `body`
# and `footer` sections with the `md()`
# text helper function
email <-
  compose_email(
    body = md(
"
## Hello!

This is an email message that was generated by the blastula package.

We can use **Markdown** formatting with the `md()` function.

Cheers,

The blastula team
"),
  footer = md(
"
sent via the [blastula](https://rstudio.github.io/blastula) R package
")
)

# The email message can always be
# previewed by calling the object
if (interactive()) email

Store SMTP credentials in a file

Description

We can create a file with SMTP configuration and access credentials for the purpose of more easily sending email messages through smtp_send(). With this file produced, the credentials helper creds_file() can be used in the credentials argument of smtp_send().

Usage

create_smtp_creds_file(
  file,
  user = NULL,
  provider = NULL,
  host = NULL,
  port = NULL,
  use_ssl = NULL
)

Arguments

Examples

# Create a credentials file to make it
# much easier to send email out through
# Gmail with `smtp_send()`; name the
# file "gmail_creds"

# create_smtp_creds_file(
#   file = "gmail_creds",
#   user = "user_name@gmail.com",
#   provider = "gmail"
# )

Store SMTP credentials in the system's key-value store

Description

We can set SMTP access credentials in the system-wide key-value store for the purpose of more easily sending email messages through smtp_send(). With this key added, the credentials helper creds_key() can be used in the credentials argument of smtp_send() (the id value is used to unambiguously refer to each key).

Usage

create_smtp_creds_key(
  id,
  user = NULL,
  provider = NULL,
  host = NULL,
  port = NULL,
  use_ssl = NULL,
  overwrite = FALSE
)

Arguments

Details

Support for setting keys through create_smtp_creds_key() is provided through the keyring package. This function cannot be used without that package being available on the system. We can use install.packages("keyring") to install keyring.

Examples

# Store SMTP credentials using the
# system's secure key-value store to
# make it much easier to send email
# out through Gmail with `smtp_send()`;
# provide the `id` of "gmail_creds"

# create_smtp_creds_key(
#   id = "gmail_creds",
#   provider = "gmail",
#   user = "user_name@gmail.com",
#   )

Helpers for supplying SMTP credentials

Description

These helper functions, the credential helpers, are used to supply SMTP configuration and authorization information for the smtp_send() function. The creds_file(), creds_anonymous(), creds_key(), and creds() functions are to be used expressly with the credentials argument of smtp_send().

Usage

creds(user = NULL, provider = NULL, host = NULL, port = NULL, use_ssl = TRUE)

creds_anonymous(provider = NULL, host = NULL, port = NULL, use_ssl = TRUE)

creds_envvar(
  user = NULL,
  pass_envvar = "SMTP_PASSWORD",
  provider = NULL,
  host = NULL,
  port = NULL,
  use_ssl = TRUE
)

creds_key(id)

creds_file(file)

Arguments

Details

The creds() credential helper allows for manual specification of SMTP configuration and authentication.

The creds_anonymous() credential helper is similar to creds() but provides convenient defaults for authenticating anonymously with an SMTP server.

The creds_key() credential helper gets credentials stored in the system-wide key-value store. We can set that key and the credentials data using the create_smtp_creds_key() function.

The creds_file() credential helper is used to obtain credentials from a file stored on disk. We can create that file using the create_smtp_creds_file() function.

The creds_envvar() credential helper reads the password from the SMTP_PASSWORD environment variable (or an environment variable name that you specify). If using environment variables for other parameters, call Sys.getenv() manually (e.g. user = Sys.getenv("SMTP_USER")).

Value

A credentials list object.

Delete all blastula credential keys

Description

The delete_all_credential_keys() function deletes all blastula credential keys, giving you a clean slate. Should specific keys need to be deleted, the delete_credential_key() could be used (one call per credential key to delete). Before using delete_all_credential_keys(), it may be useful to see which keys are available in the key-value store. For that, use the view_credential_keys() function.

Usage

delete_all_credential_keys()

Details

Support for using the delete_all_credential_keys() function (and for doing any credential key management) is provided through the keyring package. This function cannot be used without that package being available on the system. We can use install.packages("keyring") to install keyring.

Examples

# Delete all blastula credential keys
# in the system's key-value store

# delete_all_credential_keys()

Delete a single blastula credential key

Description

It may be important to delete a credential key and the delete_credential_key() function makes this possible. To understand which keys are available in the key-value store (and to get their id values), use the view_credential_keys() function.

Usage

delete_credential_key(id)

Arguments

Details

Support for using the delete_credential_key() function (and for doing any credential key management) is provided through the keyring package. This function cannot be used without that package being available on the system. We can use install.packages("keyring") to install keyring.

Examples

# Delete the credential key with
# the `id` value of "outlook"

# delete_credential_key("outlook")

Get the HTML content of an email message

Description

Get the HTML content string from an email_message object as a single-length character vector.

Usage

get_html_str(message)

Arguments

Value

A character object containing the email message's HTML content.

Interpret input text as Markdown-formatted text

Description

Interpret input text as Markdown-formatted text

Usage

md(text)

Arguments

Value

A character object that is tagged for a Markdown-to-HTML transformation.

A rendered HTML object.

Prepare example files for Posit Connect emailing with R Markdown

Description

A set of example files relevant to emailing with R Markdown in RStudio Connect can be spawned in a specified location. There is a set of three files that work together to provide a full report, an emailable version of that report, and a file attachment; these files are:

Usage

prepare_rsc_example_files(path = NULL)

Arguments

Details

• "connect-example-main.Rmd": The main R Markdown document. Contains a report template culminating in a final R code chunk that has calls to render_connect_email() and attach_connect_email().

• "connect-example-email.Rmd": An R Markdown document that contains the email message. It is associated with the main R Markdown document by incorporating some of its content (i.e., by reusing chunk names and extending assigned values). It uses the blastula::blastula_email output type in the YAML front matter.

• "austin_home_sales.csv": A CSV file that will be included as an attachment by way of the attachments argument in the attach_connect_email() function call within the main R Markdown document.

The main report and associated email can be published by opening "connect-example-main.Rmd" and pressing the Publish button at the top-right of the Editor pane (please ensure beforehand that you are set up work with Posit Connect). If asked "What do you want to publish?", choose the first option where only the "connect-example-main" document is published. All three files should be checked in the final dialog box, press the Publish button to publish to Posit Connect.

There is also the single "connect-example-text-only.Rmd" file that, when published, serves as a mechanism to send a text-only email. The content of the email is specified directly in the single attach_connect_email() function call and all other text in the R Markdown file is disregarded.

Prepare a email test message object

Description

Create an email test message object, which is helpful for sending a test message with the smtp_send() function.

Usage

prepare_test_message(incl_ggplot = FALSE, incl_image = FALSE)

Arguments

Value

An email_message object.

Examples

# Create a credentials file to send
# a test message via Gmail's SMTP
# (this file is named "gmail_secret")

# create_smtp_creds_file(
#   file = "gmail_secret",
#   user = "sender@email.com",
#   provider = "gmail"
# )

# Send oneself a test message to
# test these new SMTP settings and
# to ensure that the message appears
# correctly in the email client

# prepare_test_message() %>%
#   smtp_send(
#     from = "sender@email.com",
#     to = "sender@email.com",
#     subject = "Test Message",
#     credentials = creds_file(
#       file = "gmail_secret"
#       )
#     )

Print the email object to the Viewer

Description

This function will provide a preview of the email message.

Usage

## S3 method for class 'blastula_message'
print(x, ...)

Arguments

R Markdown render functions for the blastula_email output format

Description

The render_email() and render_connect_email() functions both allow for rendering an an email message. We can supply an R Markdown document (.Rmd) with the output specified as output: blastula::blastula_email. While the render_email() and render_connect_email() functions have similar arguments, the render_connect_email() is preferred when publishing to the Posit Connect service. It allows for the inclusion of a predefined footer that contains useful links for email recipients.

Usage

render_email(
  input,
  envir = parent.frame(),
  quiet = TRUE,
  output_options = list(),
  render_options = list()
)

render_connect_email(
  input,
  connect_footer = TRUE,
  envir = parent.frame(),
  quiet = TRUE,
  output_options = list(),
  render_options = list()
)

Arguments

Send an email message through the Mailgun API

Description

Send an email message via the Mailgun API. This requires an account with Mailgun.

Usage

send_by_mailgun(message, subject = NULL, from, recipients, url, api_key)

Arguments

Examples

# Create a simple email message using
# Markdown formatting

# email <-
#   compose_email(
#   body = "
#   Hello!
#
#   ## This a section heading
#
#   We can use Markdown formatting \
#   to **embolden** text or to add \
#   *emphasis*. This is exciting, \
#   right?
#
#   Cheers")

# Generate a vector of recipients

# recipient_list <-
#   c("person_1@site.net",
#     "person_2@site.net")

# Send it to multiple people through
# the Mailgun API

# email %>%
#   send_by_mailgun(
#     subject = "Sent through Mailgun",
#     from = "The Sender <sender@send.org>",
#     recipients = recipient_list,
#     url = "<..mailgun_sending_domain..>",
#     api = "<..mailgun_api_key..>")

Send an email message through SMTP

Description

Send an email message to one or more recipients via an SMTP server. The email message required as input to smtp_send() has to be created by using the compose_email() function. The email_message object can be previewed by printing the object, where the HTML preview will show how the message should appear in recipients' email clients. File attachments can be added to the email object by using the add_attachment() function (one call per attachment) prior to sending through this function.

Usage

smtp_send(
  email,
  to,
  from,
  subject = NULL,
  cc = NULL,
  bcc = NULL,
  credentials = NULL,
  creds_file = "deprecated",
  verbose = FALSE,
  login_options = NULL,
  ...
)

Arguments

Details

We can avoid re-entering SMTP configuration and credentials information by retrieving this information either from disk (with the file generated by use of the create_smtp_creds_file() function), or, from the system's key-value store (with the key set by the create_smtp_creds_key() function).

Examples

# Before sending out an email through
# SMTP, we need an `email_message`
# object; for the purpose of a simple
# example, we can use the function
# `prepare_test_message()` to create
# a test version of an email (although
# we'd normally use `compose_email()`)
email <- prepare_test_message()

# The `email` message can be sent
# through the `smtp_send()` function
# so long as we supply the appropriate
# credentials; The following three
# examples provide scenarios for both
# the creation of credentials and their
# retrieval within the `credentials`
# argument of `smtp_send()`

# (1) Providing the credentials info
# directly via the `creds()` helper
# (the most secure means of supplying
# credentials information)

# email %>%
#   smtp_send(
#     from = "sender@email.com",
#     to = "recipient@email.com",
#     credentials = creds(
#       provider = "gmail",
#       user = "sender@email.com")
#   )

# (2) Using a credentials key (with
# the `create_smtp_creds_key()` and
# `creds_key()` functions)

# create_smtp_creds_key(
#  id = "gmail",
#  user = "sender@email.com",
#  provider = "gmail"
#  )

# email %>%
#   smtp_send(
#     from = "sender@email.com",
#     to = "recipient@email.com",
#     credentials = creds_key(
#       "gmail"
#       )
#   )

# (3) Using a credentials file (with
# the `create_smtp_creds_file()` and
# `creds_file()` functions)

# create_smtp_creds_file(
#  file = "gmail_secret",
#  user = "sender@email.com",
#  provider = "gmail"
#  )

# email %>%
#   smtp_send(
#     from = "sender@email.com",
#     to = "recipient@email.com",
#     credentials = creds_file(
#       "gmail_secret")
#   )

Specify the components of a social link

Description

The social_link() function is used exclusively within block_social_links() with as many calls as the number of social sharing icons/links required. By providing a supported service name, a hosted icon image can be used. A link must be provided; it will be part of social sharing icon. All icons are rounded, transparent, and consist of a single color, or level of gray.

Usage

social_link(service, link, variant = NULL, alt = NULL)

Arguments

Details

The following social sharing services have hosted icons available:

• Twitter - Micro-blogging internet service.

• GitHub - Web-based hosting service for software development projects using Git.

• Facebook - Global online social networking service.

• Instagram - Online photo-sharing and social networking service.

• LinkedIn - Social networking service for people in professional occupations.

• YouTube - Video-sharing service owned by Google.

• Vimeo - An ad-free open video platform.

• Behance - A site for self-promotion of design projects.

• Dribbble - Online community for showcasing user-made artwork.

• Pinterest - Photo-sharing and publishing website for discovering interesting things.

• 500px - Online platform for photographers to gain global exposure.

• Yelp - Local-search service powered by crowd-sourced reviews.

• TripAdvisor - Travel and restaurant website with reviews and accommodation bookings.

• WordPress - Blogging platform and content management system.

• Blogger - A blog-publishing service hosted by Google.

• Tumblr - Micro-blogging and social networking website.

• Deezer - Web-based music streaming service.

• SoundCloud - A music sharing website and publishing tool for music distribution.

• Meetup - A service used to organize online groups that host in-person events.

• Etsy - An e-commerce website focused on handmade or vintage items and supplies.

• Reddit - A social news aggregation, web content rating, and discussion website.

• Stack Overflow - Question and answer site for professional and enthusiast programmers.

• Youku - A video hosting service for user-made and professionally produced videos.

• Sina Weibo - Micro-blogging website and one of the biggest social media platforms in China.

• QQ - Instant messaging software service developed by Tencent.

• Douban - A Chinese social networking service with a reputation for high-quality content.

Examples

# Create an email message with some
# articles in the `body`; in the footer,
# add some social sharing icons linking
# to web content
email <-
  compose_email(
    body =
      blocks(
        block_title("Exciting Travel Destinations"),
        block_articles(
          article(
            image = "https://i.imgur.com/dxSXzGb.jpg",
            title = "Hong Kong",
            content =
              "Once home to fishermen and farmers,
              modern Hong Kong is a teeming,
              commercially-vibrant metropolis where
              Chinese and Western influences fuse."
          ),
          article(
            image = "https://i.imgur.com/bJzVIrG.jpg",
            title = "Australia",
            content =
              "Australia ranks as one of the best
              places to live in the world by all
              indices of income, human development,
              healthcare, and civil rights."
          )
        )
      ),
    footer =
      blocks(
        block_text("Thanks for reading! Find us here:"),
        block_social_links(
          social_link(
            service = "pinterest",
            link = "https://www.pinterest.ca/TravelLeisure/",
            variant = "color"
          ),
          social_link(
            service = "tripadvisor",
            link = "https://www.tripadvisor.ca/TravelersChoice",
            variant = "color"
          )
        )
      )
  )

if (interactive()) email

Suppress any scheduled emailing in Posit Connect

Description

This function is useful for suppressing the scheduled emailing of a published R Markdown document. It can be invoked anywhere in the R Markdown document and is useful in a conditional statement, where the result of the condition determines whether or not email suppression should occur.

Usage

suppress_scheduled_email(suppress = TRUE)

Arguments

Details

Since this function needs to be invoked within an R Markdown document, the chunk option echo=FALSE is useful here (so that viewers of the rendered document don't have to unnecessarily read code related to email suppression). While the output is invisible, any errors related to the use of this function will be visible to the author.

View all available blastula credential keys

Description

To understand which keys have been set using the create_smtp_creds_key() function (and how they are identified), we can use the view_credential_keys() function. What's provided is a tibble with three columns: id, key_name, and username.

Usage

view_credential_keys()

Details

Support for using the view_credential_keys() function (and for doing any credential key management) is provided through the keyring package. This function cannot be used without that package being available on the system. We can use install.packages("keyring") to install keyring.

Examples

# View the available SMTP credentials
# that are in the system's secure
# key-value store; the `id` values
# in the returned tibble provide what's
# necessary to send email through
# `smtp_send()` and the `creds_key()`
# credential helper function

# view_credential_keys()