smtp_send {blastula}R Documentation

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

email

The email message object, as created by the compose_email() function. The object's class is email_message.

to

A vector of email addresses serving as primary recipients for the message. For secondary recipients, use the cc and bcc arguments. A named character vector can be used to specify the recipient names along with the their email address (e.g., c("Jane Doe" = "jane_doe@example.com")).

from

The email address of the sender. Often this needs to be the same email address that is associated with the account actually sending the message. As with to, cc, and bcc, we can either supply a single email address or use a named character vector with the sender name and email address (e.g., c("John Doe" = "john_doe@example.com")).

subject

The subject of the message, which is usually a brief summary of the topic of the message. If not provided, an empty string will be used (which is handled differently by email clients).

cc, bcc

A vector of email addresses for sending the message as a carbon copy or blind carbon copy. The CC list pertains to recipients that are to receive a copy of a message that is addressed primarily to others. The CC listing of recipients is visible to all other recipients of the message. The BCC list differs in that those recipients will be concealed from all other recipients (including those on the BCC list). A named character vector can be used to specify the recipient names along with the their email address (e.g., c("Joe Public" = "joe_public@example.com")).

credentials

One of three credential helper functions must be used here: (1) creds(), (2) creds_key(), or (3) creds_file(). The first, creds(), allows for a manual specification of SMTP configuration and credentials within that helper function. This is the most secure method for supplying credentials as they aren't written to disk. The creds_key() function is used if credentials are stored in the system-wide key-value store, through use of the create_smtp_creds_key() function. The creds_file() helper function relies on a credentials file stored on disk. Such a file is created using the create_smtp_creds_file() function.

creds_file

An option to specify a credentials file. As this argument is deprecated, please consider using ⁠credentials = creds_file(<file>)⁠ instead.

verbose

Should verbose output from the internal curl send_mail() call be printed? While the username and password will likely be echoed during the exchange, such information is encoded and won't be stored on the user's system.

login_options

A string representation of login options allowed by CURLOPT_LOGIN_OPTIONS.

...

Extra arguments passed to curl::send_mail()

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")
#   )
[Package blastula version 0.3.5 Index]