The email_blast() function is useful for sending an email message that explains the result of a pointblank validation. It is powered by the blastula and glue packages. This function should be invoked as part of the end_fns argument of create_agent(). It's also possible to invoke email_blast() as part of the fns argument of the action_levels() function (i.e., to send multiple email messages at the granularity of different validation steps exceeding failure thresholds).

To better get a handle on emailing with email_blast(), the analogous email_create() function can be used with a pointblank agent object or an x-list obtained from using the get_agent_x_list() function.

email_blast(
  x,
  to,
  from,
  credentials = NULL,
  msg_subject = NULL,
  msg_header = NULL,
  msg_body = stock_msg_body(),
  msg_footer = stock_msg_footer(),
  send_condition = ~TRUE %in% x$notify
)

Arguments

x

A reference to the x-list object prepared internally by the agent. This version of the x-list is the same as that generated via get_agent_x_list(<agent>) except this version is internally generated and hence only available in an internal evaluation context.

to, from

The email addresses for the recipients and of the sender.

credentials

A credentials list object that is produced by either of the blastula::creds(), blastula::creds_anonymous(), blastula::creds_key(), or blastula::creds_file() functions. Please refer to the blastula documentation for information on how to use these functions.

msg_subject

The subject line of the email message.

msg_header, msg_body, msg_footer

Content for the header, body, and footer components of the HTML email message.

send_condition

An expression that should evaluate to a logical vector of length 1. If evaluated as TRUE then the email will be sent, if FALSE then that won't happen. The expression can use x-list variables (e.g., x$notify, x$type, etc.) and all of those variables can be explored using the get_agent_x_list() function. The default expression is ~TRUE %in% x$notify, which results in TRUE if there are any TRUE values in the x$notify logical vector (i.e., any validation step results in a 'notify' condition).

YAML

A pointblank agent can be written to YAML with yaml_write() and the resulting YAML can be used to regenerate an agent (with yaml_read_agent()) or interrogate the target table (via yaml_agent_interrogate()). Here is an example of how the use of email_blast() inside the end_fns argument of create_agent() is expressed in R code and in the corresponding YAML representation.

# R statement
create_agent(
  read_fn = ~ small_table,
  tbl_name = "small_table",
  label = "An example.",
  actions = al,
  end_fns = list(
    ~ email_blast(
      x,
      to = "joe_public@example.com",
      from = "pb_notif@example.com",
      msg_subject = "Table Validation",
      credentials = blastula::creds_key(
        id = "smtp2go"
      ),
    )
  )
) %>%
  col_vals_gt(vars(a), 1) %>%
  col_vals_lt(vars(a), 7) 

# YAML representation
type: agent
read_fn: ~small_table
tbl_name: small_table
label: An example.
lang: en
locale: en
actions:
  warn_count: 1.0
  notify_count: 2.0
end_fns: ~email_blast(x, to = "joe_public@example.com", 
  from = "pb_notif@example.com", msg_subject = "Table Validation",
  credentials = blastula::creds_key(id = "smtp2go"),
  )
embed_report: true
steps:
  - col_vals_gt:
    columns: vars(a)
    value: 1.0
  - col_vals_lt:
    columns: vars(a)
    value: 7.0

Function ID

4-1

See also

Examples

# Create an `action_levels()` list # with absolute values for the # `warn`, and `notify` states (with # thresholds of 1 and 2 'fail' units) al <- action_levels( warn_at = 1, notify_at = 2 ) if (interactive()) { # Validate that values in column # `a` from `small_tbl` are always > 1 # and that they are always < 7; first, # apply the `actions_levels()` # directive to `actions` and set up # an `email_blast()` as one of the # `end_fns` (by default, the email # will be sent if there is a single # 'notify' state across all # validation steps) agent <- create_agent( read_fn = ~ small_table, tbl_name = "small_table", label = "An example.", actions = al, end_fns = list( ~ email_blast( x, to = "joe_public@example.com", from = "pb_notif@example.com", msg_subject = "Table Validation", credentials = blastula::creds_key( id = "smtp2go" ), ) ) ) %>% col_vals_gt(vars(a), value = 1) %>% col_vals_lt(vars(a), value = 7) %>% interrogate() } # The above example was intentionally # not run because email credentials # aren't available and the `to` # and `from` email addresses are # nonexistent # To get a blastula email object # instead of eagerly sending the # message, we can use the # `email_create()` function email_object <- create_agent( read_fn = ~ small_table, tbl_name = "small_table", label = "An example.", actions = al ) %>% col_vals_gt(vars(a), value = 5) %>% col_vals_lt(vars(a), value = 7) %>% interrogate() %>% email_create()
#> Warning: The `.dots` argument of `group_by()` is deprecated as of dplyr 1.0.0.