Skip to contents

[Experimental]

Merges columns from a data frame into a markdown document using the glue::glue_data() function. The markdown can contain a yaml header for subject and cc line.

Note that only 'gmail' is supported at the moment, via gmailr::gm_send_message.

Before using mail_merge(), you must be authenticated to the gmail service. Use gmailr::gm_auth() to authenticate prior to starting the mail merge.

Usage

mail_merge(
  data,
  message,
  to_col = "email",
  send = c("preview", "draft", "immediately"),
  confirm = FALSE,
  sleep_preview = 1,
  sleep_send = 0.1
)

Arguments

data

A data frame or tibble with all the columns that should be glued into the message. Substitution is performed using glue::glue_data()`

message

A list with components yaml and body. You can use mm_read_message() or mm_read_message_googledoc() to construct a message in this format.

to_col

The name of the column in data that contains the email address to send the message to.

send

A character string, one of:

  • "preview" : displays message in viewer without sending mail

  • "draft : writes message into "drafts" folder on gmail

  • "immediately" : sends email

confirm

If TRUE sends email without additional confirmation. If FALSE asks for confirmation before sending.

sleep_preview

If send == "preview" the number of seconds to sleep between each preview. See also preview_mailmerge

sleep_send

If send == "immediately" the number of seconds to sleep between each email send (to prevent gmail API 500 errors).

Value

Returns a list for every message, consisting of:

  • msg: The message in mime format

  • id: The gmailr response id

  • type: preview, draft or sent

  • success: TRUE if the message was sent successfully

Examples

## ---- input-data --------------------------------------------------------

dat <-  data.frame(
  email      = c("friend@example.com", "foe@example.com"),
  first_name = c("friend", "foe"),
  thing      = c("something good", "something bad"),
  stringsAsFactors = FALSE
)

## ---- markdown-message --------------------------------------------------

msg <- '
---
subject: "**Hello, {first_name}**"
---

Hi, **{first_name}**

I am writing to tell you about **{thing}**.

{if (first_name == "friend") "Regards" else ""}


Me
'


## ---- mail-merge --------------------------------------------------------

dat %>% 
  mail_merge(msg)
#> Sent preview to viewer

if (interactive()) {
  dat %>%
    mail_merge(msg) %>%
    print()
}

## ---- display shiny gadget ----------------------------------------------

if (interactive()) {
  dat %>%
    mail_merge(msg) %>%
    preview_mailmerge()
}