From f12c907fc1c72521540e34a4703f6e9ed607667a Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Mon, 18 Nov 2019 10:35:17 -0500 Subject: [PATCH] SMTP credentials/sending changes (#108) * Add `verbose` arg to `smtp_send()` * Remove certain args from `creds_anonymous()` * Remove unused `sender_name` option * Remove docs for removed `password` arg This also corrects a nearby spelling error. --- R/create_credentials.R | 14 ++------------ R/creds_helpers.R | 19 ++++--------------- R/smtp_send.R | 9 +++++++-- man/create_smtp_creds_file.Rd | 5 +---- man/create_smtp_creds_key.Rd | 5 +---- man/credential_helpers.Rd | 17 +++++------------ man/smtp_send.Rd | 7 ++++++- tests/testthat/test-credentials.R | 7 ++----- 8 files changed, 28 insertions(+), 55 deletions(-) diff --git a/R/create_credentials.R b/R/create_credentials.R index 7397dc33..b9074b0a 100644 --- a/R/create_credentials.R +++ b/R/create_credentials.R @@ -16,8 +16,6 @@ #' and `port` parameters are the address and port for the SMTP server; #' `use_ssl` is an option as to whether to use SSL: supply a `TRUE` or `FALSE` #' value. -#' @param sender_name An option to specify a sender name. This isn't always -#' visible to the recipient, however, as some SMTP servers will suppress this. #' #' @examples #' # Create a credentials file to make it @@ -37,8 +35,7 @@ create_smtp_creds_file <- function(file, provider = NULL, host = NULL, port = NULL, - use_ssl = NULL, - sender_name = NULL) { + use_ssl = NULL) { # nocov start @@ -50,7 +47,6 @@ create_smtp_creds_file <- function(file, create_credentials_list( provider = provider, user = user, - sender_name = sender_name, host = host, port = port, use_ssl = use_ssl @@ -105,8 +101,7 @@ create_smtp_creds_key <- function(id, provider = NULL, host = NULL, port = NULL, - use_ssl = NULL, - sender_name = NULL) { + use_ssl = NULL) { # nocov start @@ -130,7 +125,6 @@ create_smtp_creds_key <- function(id, create_credentials_list( provider = provider, user = user, - sender_name = sender_name, host = host, port = port, use_ssl = use_ssl @@ -167,7 +161,6 @@ create_smtp_creds_key <- function(id, create_credentials_list <- function(provider, user, password = getPass::getPass("Enter the SMTP server password: "), - sender_name, host, port, use_ssl) { @@ -176,7 +169,6 @@ create_credentials_list <- function(provider, user = user, password = password, provider = provider, - sender_name = sender_name, host = host, port = port, use_ssl = use_ssl @@ -189,7 +181,6 @@ create_credentials_list <- function(provider, creds_internal <- function(user = NULL, password = NULL, provider = NULL, - sender_name = NULL, host = NULL, port = NULL, use_ssl = NULL) { @@ -217,7 +208,6 @@ creds_internal <- function(user = NULL, # Generate the credentials list list( version = schema_version, - sender_name = sender_name, host = host, port = port, use_ssl = use_ssl, diff --git a/R/creds_helpers.R b/R/creds_helpers.R index 40ba5206..57ae5379 100644 --- a/R/creds_helpers.R +++ b/R/creds_helpers.R @@ -9,7 +9,7 @@ #' The [creds()] credential helper allows for manual specification of SMTP #' configuration and authentication. #' -#' The [creds_anonymous()] credential helper is similiar to [creds()] but +#' The [creds_anonymous()] credential helper is similar to [creds()] but #' provides convenient defaults for authenticating anonymously with an SMTP #' server. #' @@ -23,15 +23,10 @@ #' #' @param user The username for the email account. Typically, this is the email #' address associated with the account. -#' @param password This argument is available in the [creds_anonymous()] and -#' isn't typically used unless an 'anonymous' password requires a specific -#' value (e.g., "anonymous" as the password itself). #' @param provider An optional email provider shortname for autocompleting STMP #' configuration details (the `host`, `port`, `use_ssl` options). Options #' currently include `gmail`, `outlook`, and `office365`. If nothing is #' provided then values for `host`, `port`, and `use_ssl` are expected. -#' @param sender_name An option to specify a sender name. This isn't always -#' visible to the recipient, however, as some SMTP servers will suppress this. #' @param host,port,use_ssl Configuration info for the SMTP server. The `host` #' and `port` parameters are the address and port for the SMTP server; #' `use_ssl` is an option as to whether to use SSL: supply a `TRUE` or `FALSE` @@ -54,7 +49,6 @@ NULL #' @export creds <- function(user = NULL, provider = NULL, - sender_name = NULL, host = NULL, port = NULL, use_ssl = TRUE) { @@ -64,7 +58,6 @@ creds <- function(user = NULL, create_credentials_list( provider = provider, user = user, - sender_name = sender_name, host = host, port = port, use_ssl = use_ssl @@ -76,20 +69,16 @@ creds <- function(user = NULL, #' @rdname credential_helpers #' @export -creds_anonymous <- function(user = "anonymous", - password = NULL, - provider = NULL, - sender_name = NULL, +creds_anonymous <- function(provider = NULL, host = NULL, port = NULL, use_ssl = TRUE) { creds_list <- creds_internal( - user = user, - password = password, + user = NULL, + password = NULL, provider = provider, - sender_name = sender_name, host = host, port = port, use_ssl = use_ssl diff --git a/R/smtp_send.R b/R/smtp_send.R index e571d38c..71cfe67a 100644 --- a/R/smtp_send.R +++ b/R/smtp_send.R @@ -47,6 +47,10 @@ #' @param creds_file An option to specify a credentials file. As this argument #' is deprecated, please consider using `credentials = creds_file()` #' instead. +#' @param 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. #' #' @examples #' # Before sending out an email through @@ -126,7 +130,8 @@ smtp_send <- function(email, cc = NULL, bcc = NULL, credentials = NULL, - creds_file = "deprecated") { + creds_file = "deprecated", + verbose = FALSE) { # Verify that the `message` object # is of the class `email_message` @@ -208,7 +213,7 @@ smtp_send <- function(email, message = email_qp, smtp_server = paste0(credentials$host, ":", credentials$port), use_ssl = credentials$use_ssl, - verbose = FALSE, + verbose = verbose, username = credentials$user, password = credentials$password ) diff --git a/man/create_smtp_creds_file.Rd b/man/create_smtp_creds_file.Rd index 03536b04..95b83ad2 100644 --- a/man/create_smtp_creds_file.Rd +++ b/man/create_smtp_creds_file.Rd @@ -5,7 +5,7 @@ \title{Store SMTP credentials in a file} \usage{ create_smtp_creds_file(file, user = NULL, provider = NULL, - host = NULL, port = NULL, use_ssl = NULL, sender_name = NULL) + host = NULL, port = NULL, use_ssl = NULL) } \arguments{ \item{file}{The output filename for the credentials file.} @@ -22,9 +22,6 @@ provided then values for \code{host}, \code{port}, and \code{use_ssl} are expect and \code{port} parameters are the address and port for the SMTP server; \code{use_ssl} is an option as to whether to use SSL: supply a \code{TRUE} or \code{FALSE} value.} - -\item{sender_name}{An option to specify a sender name. This isn't always -visible to the recipient, however, as some SMTP servers will suppress this.} } \description{ We can create a file with SMTP configuration and access credentials for the diff --git a/man/create_smtp_creds_key.Rd b/man/create_smtp_creds_key.Rd index 2ac86589..8c7f7a39 100644 --- a/man/create_smtp_creds_key.Rd +++ b/man/create_smtp_creds_key.Rd @@ -5,7 +5,7 @@ \title{Store SMTP credentials in the system's key-value store} \usage{ create_smtp_creds_key(id, user = NULL, provider = NULL, host = NULL, - port = NULL, use_ssl = NULL, sender_name = NULL) + port = NULL, use_ssl = NULL) } \arguments{ \item{id}{An identifying label for the keyname. The full key name is @@ -33,9 +33,6 @@ value.} and \code{port} parameters are the address and port for the SMTP server; \code{use_ssl} is an option as to whether to use SSL: supply a \code{TRUE} or \code{FALSE} value.} - -\item{sender_name}{An option to specify a sender name. This isn't always -visible to the recipient, however, as some SMTP servers will suppress this.} } \description{ We can set SMTP access credentials in the system-wide key-value store for the diff --git a/man/credential_helpers.Rd b/man/credential_helpers.Rd index 1702fa07..2a693100 100644 --- a/man/credential_helpers.Rd +++ b/man/credential_helpers.Rd @@ -8,11 +8,11 @@ \alias{creds_file} \title{Helpers for supplying SMTP credentials} \usage{ -creds(user = NULL, provider = NULL, sender_name = NULL, - host = NULL, port = NULL, use_ssl = TRUE) +creds(user = NULL, provider = NULL, host = NULL, port = NULL, + use_ssl = TRUE) -creds_anonymous(user = "anonymous", password = NULL, provider = NULL, - sender_name = NULL, host = NULL, port = NULL, use_ssl = TRUE) +creds_anonymous(provider = NULL, host = NULL, port = NULL, + use_ssl = TRUE) creds_key(id) @@ -27,18 +27,11 @@ configuration details (the \code{host}, \code{port}, \code{use_ssl} options). Op currently include \code{gmail}, \code{outlook}, and \code{office365}. If nothing is provided then values for \code{host}, \code{port}, and \code{use_ssl} are expected.} -\item{sender_name}{An option to specify a sender name. This isn't always -visible to the recipient, however, as some SMTP servers will suppress this.} - \item{host, port, use_ssl}{Configuration info for the SMTP server. The \code{host} and \code{port} parameters are the address and port for the SMTP server; \code{use_ssl} is an option as to whether to use SSL: supply a \code{TRUE} or \code{FALSE} value.} -\item{password}{This argument is available in the \code{\link[=creds_anonymous]{creds_anonymous()}} and -isn't typically used unless an 'anonymous' password requires a specific -value (e.g., "anonymous" as the password itself).} - \item{id}{When using the \code{\link[=creds_key]{creds_key()}} credential helper, the ID value of the key (in the system key-value store) needs to be given here. This was explicitly provided when using the \code{\link[=create_smtp_creds_key]{create_smtp_creds_key()}} function (with @@ -65,7 +58,7 @@ functions are to be used expressly with the \code{credentials} argument of The \code{\link[=creds]{creds()}} credential helper allows for manual specification of SMTP configuration and authentication. -The \code{\link[=creds_anonymous]{creds_anonymous()}} credential helper is similiar to \code{\link[=creds]{creds()}} but +The \code{\link[=creds_anonymous]{creds_anonymous()}} credential helper is similar to \code{\link[=creds]{creds()}} but provides convenient defaults for authenticating anonymously with an SMTP server. diff --git a/man/smtp_send.Rd b/man/smtp_send.Rd index c8f06c04..42cda775 100644 --- a/man/smtp_send.Rd +++ b/man/smtp_send.Rd @@ -5,7 +5,7 @@ \title{Send an email message through SMTP} \usage{ smtp_send(email, to, from, subject = NULL, cc = NULL, bcc = NULL, - credentials = NULL, creds_file = "deprecated") + credentials = NULL, creds_file = "deprecated", verbose = FALSE) } \arguments{ \item{email}{The email message object, as created by the \code{\link[=compose_email]{compose_email()}} @@ -48,6 +48,11 @@ Such a file is created using the \code{\link[=create_smtp_creds_file]{create_smt \item{creds_file}{An option to specify a credentials file. As this argument is deprecated, please consider using \code{credentials = creds_file()} instead.} + +\item{verbose}{Should verbose output from the internal curl \code{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.} } \description{ Send an email message to one or more recipients via an SMTP server. The email diff --git a/tests/testthat/test-credentials.R b/tests/testthat/test-credentials.R index a83d5ce9..7176826c 100644 --- a/tests/testthat/test-credentials.R +++ b/tests/testthat/test-credentials.R @@ -8,7 +8,6 @@ test_that("utility functions for credentials work properly", { provider = NULL, user = "testuser@example.com", password = "testpass", - sender_name = "testsender", host = "smtp.example.com", port = 465, use_ssl = TRUE @@ -21,7 +20,7 @@ test_that("utility functions for credentials work properly", { credentials_list_1 %>% names() %>% expect_equal( - c("version", "sender_name", "host", "port", "use_ssl", "user", "password") + c("version", "host", "port", "use_ssl", "user", "password") ) # Expect a specific value for `credentials_list_1$version` @@ -34,7 +33,6 @@ test_that("utility functions for credentials work properly", { provider = "gmail", user = "testuser@example.com", password = "testpass", - sender_name = "testsender", host = NULL, port = NULL, use_ssl = NULL @@ -44,7 +42,7 @@ test_that("utility functions for credentials work properly", { credentials_list_2 %>% names() %>% expect_equal( - c("version", "sender_name", "host", "port", "use_ssl", "user", "password") + c("version", "host", "port", "use_ssl", "user", "password") ) # Expect that the `host`, `port`, and `use_ssl` elements @@ -60,7 +58,6 @@ test_that("utility functions for credentials work properly", { provider = NULL, user = "testuser@example.com", password = "testpass", - sender_name = "testsender", host = NULL, port = NULL, use_ssl = NULL