### Example: Create Gmail Credentials File

Source: https://rstudio.github.io/blastula/reference/create_smtp_creds_file.html

This example demonstrates how to create a credentials file for sending email via Gmail using `smtp_send()`. It specifies the output filename, username, and provider.

```R
# 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"
# )



```

--------------------------------

### prepare_rsc_example_files()

Source: https://rstudio.github.io/blastula/reference/prepare_rsc_example_files.html

Spawns a set of example files for emailing R Markdown reports with RStudio Connect.

```APIDOC
## prepare_rsc_example_files()

### 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.

### Method
Function

### Endpoint
N/A (R function)

### Parameters
#### Path Parameters
- **path** (character) - Optional - The location to which the files (in a subdirectory named `"connect_examples"`) will be written. The path needs to exist but the aforementioned subdirectory is not required to be present.

### 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.

### Usage Notes
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.
```

--------------------------------

### Install keyring package

Source: https://rstudio.github.io/blastula/reference/delete_all_credential_keys.html

Installs the keyring package required for credential management.

```R
install.packages("keyring")
```

--------------------------------

### Example of deleting all credential keys

Source: https://rstudio.github.io/blastula/reference/delete_all_credential_keys.html

A commented example showing the usage of the delete_all_credential_keys function.

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

# delete_all_credential_keys()
```

--------------------------------

### Install Blastula

Source: https://rstudio.github.io/blastula/index.html

Installation commands for the CRAN and development versions of the package.

```R
install.packages("blastula")
```

```R
devtools::install_github("rstudio/blastula")
```

--------------------------------

### Send email via Mailgun API example

Source: https://rstudio.github.io/blastula/reference/send_by_mailgun.html

Example demonstrating how to compose an email and send it to multiple recipients using the Mailgun API.

```R
# 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 a test message via SMTP

Source: https://rstudio.github.io/blastula/reference/prepare_test_message.html

Example workflow for creating credentials and sending a test email using smtp_send.

```R
# 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"
#       )
#     )
```

--------------------------------

### Create an Article with Image, Title, Content, and Link

Source: https://rstudio.github.io/blastula/reference/article.html

Use this example to define an article with a linked image, a title, descriptive content, and a URL for further information. Ensure the `interactive()` check is used for conditional execution.

```R
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
```

--------------------------------

### Send Email with Direct Credentials

Source: https://rstudio.github.io/blastula/reference/smtp_send.html

This example demonstrates sending an email using `smtp_send()` by providing credentials directly via the `creds()` helper function. This is the most secure method for supplying credentials.

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

--------------------------------

### Example of deleting a credential key

Source: https://rstudio.github.io/blastula/reference/delete_credential_key.html

Demonstrates the syntax for deleting a key with a specific ID.

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

# delete_credential_key("outlook")
```

--------------------------------

### Prepare Test Email Message

Source: https://rstudio.github.io/blastula/reference/smtp_send.html

Before sending an email, an `email_message` object must be created. This example uses `prepare_test_message()` for a simple test case, but `compose_email()` is typically used for real messages.

```R
# 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()
```

--------------------------------

### Compose email with article blocks

Source: https://rstudio.github.io/blastula/reference/block_articles.html

Example of creating a three-column article layout within an email composition using the blocks and article functions.

```R
# 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
```

--------------------------------

### Include an image in an email message

Source: https://rstudio.github.io/blastula/reference/add_image.html

This example demonstrates how to use the `add_image` function to create an HTML image fragment and then include it in an email body using `compose_email` and `md`. The `img_file_path` is obtained using `system.file`.

```R
img_file_path <-
  system.file(
    "example_files",
    "test_image.png",
    package = "blastula"
  )

img_file_html <-
  add_image(file = img_file_path)

email <-
  compose_email(
    body = md(
      c(
"Hello,

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

if (interactive()) email
```

--------------------------------

### Create Email with Social Links in Footer

Source: https://rstudio.github.io/blastula/reference/social_link.html

Construct an email message that includes social sharing icons in the footer. This example demonstrates composing an email with articles in the body and social links in the footer, specifying services like Pinterest and TripAdvisor with a 'color' variant.

```R
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,\n              modern Hong Kong is a teeming,\n              commercially-vibrant metropolis where\n              Chinese and Western influences fuse."
          ),
          article(
            image = "https://i.imgur.com/bJzVIrG.jpg",
            title = "Australia",
            content =
              "Australia ranks as one of the best\n              places to live in the world by all\n              indices of income, human development,\n              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
```

--------------------------------

### Compose email with social links

Source: https://rstudio.github.io/blastula/reference/block_social_links.html

Example of integrating social sharing icons into an email footer using block_social_links within a blocks object.

```R
# 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
```

--------------------------------

### Embed a ggplot2 plot in an email

Source: https://rstudio.github.io/blastula/reference/add_ggplot.html

Example demonstrating the creation of a ggplot object, its conversion to an HTML fragment, and its inclusion within an email body.

```R
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
```

--------------------------------

### Compose Email with Markdown Formatting

Source: https://rstudio.github.io/blastula/articles/blastula.html

Use the `md()` function to enable Markdown formatting for email content. This allows for rich text elements like italics, bold text, and lists. Ensure text is left-aligned in code examples to prevent unintended Markdown formatting.

```R
# Prepare the text inputs
sender_name <- "Shelly"

sending_date <-
  paste0(
    format(Sys.time(), "%A, %B "),
    format(Sys.time(), "%d") %>% as.numeric(),
    ", ",
    format(Sys.time(), "%Y")
  )

# Generate the body text
body_text <-
  md(glue(
    "\nHello,\n\nI just wanted to let you know that the *thing* that
you asked me for is ready to pick up. So, come over
and do that.\n\nCheers,\n\n{sender_name}\n"    
  ))

# Generate the footer text
footer_text <- glue("Sent on {sending_date}.")
```

--------------------------------

### Manage SMTP Credentials via File

Source: https://rstudio.github.io/blastula/reference/smtp_send.html

Creates a credentials file and uses it for SMTP email delivery.

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

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

--------------------------------

### Compose email with blocks

Source: https://rstudio.github.io/blastula/reference/blocks.html

Demonstrates how to structure email content by passing blocks() objects to header, body, and footer arguments.

```R
# 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
```

--------------------------------

### Anonymous SMTP Authentication

Source: https://rstudio.github.io/blastula/reference/credential_helpers.html

Employ `creds_anonymous()` for convenient defaults when authenticating anonymously with an SMTP server. It simplifies setup by providing common settings for anonymous access.

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

--------------------------------

### Initialize blocks container

Source: https://rstudio.github.io/blastula/reference/blocks.html

Use this function to wrap multiple block_*() calls into a single object.

```R
blocks(...)
```

--------------------------------

### Credential management functions

Source: https://rstudio.github.io/blastula/news/index.html

Replaced create_email_creds_file() with a suite of functions for managing SMTP configuration and credentials. Use create_smtp_creds_file(), create_smtp_creds_key(), creds_file(), creds_key(), creds_anonymous(), and creds() for retrieving or specifying credentials.

```R
create_smtp_creds_file()
```

```R
creds_file()
```

```R
creds_key()
```

```R
creds_anonymous()
```

```R
creds()
```

--------------------------------

### Compose Email with Text and Articles

Source: https://rstudio.github.io/blastula/reference/block_text.html

Demonstrates composing an email with a text block at the top, followed by two articles side-by-side. Requires `compose_email()`, `blocks()`, `block_text()`, and `block_articles()`.

```R
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
```

--------------------------------

### Prepare a test email message

Source: https://rstudio.github.io/blastula/articles/sending_using_smtp.html

Generates a sample email object for testing purposes.

```R
# Create the test message, this returns
# an `email_message` object
test_message <- prepare_test_message()
```

--------------------------------

### Prepare Email Content

Source: https://rstudio.github.io/blastula/index.html

Generate a formatted date string and an image object for inclusion in an email.

```R
# Get a nicely formatted date/time string
date_time <- add_readable_time()

# Create an image string using an on-disk
# image file
img_file_path <-
  system.file(
    "img", "pexels-photo-267151.jpeg",
    package = "blastula"
  )

img_string <- add_image(file = img_file_path)
```

--------------------------------

### Email preview with print method

Source: https://rstudio.github.io/blastula/news/index.html

The preview_email() function has been removed. Email objects created by compose_email() now have a print method for previewing.

```R
compose_email()
```

--------------------------------

### Build sophisticated email messages with HTML blocks

Source: https://rstudio.github.io/blastula/news/index.html

Create responsive, higher-level email components using functions like blocks(), block_title(), block_text(), block_spacer(), block_articles(), and block_social_links(). Use article() and social_link() as subcomponents.

```R
blocks()
```

```R
block_title()
```

```R
block_text()
```

```R
block_spacer()
```

```R
block_articles()
```

```R
block_social_links()
```

```R
article()
```

```R
social_link()
```

--------------------------------

### Compose Email with Blocks and Spacers

Source: https://rstudio.github.io/blastula/reference/block_spacer.html

Demonstrates composing an email with introductory text, side-by-side articles, and custom spacing using `block_spacer()`. Ensure `block_spacer()` is within `blocks()` and the composed object is passed to `compose_email()`.

```R
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
```

--------------------------------

### Create SMTP Credentials Key

Source: https://rstudio.github.io/blastula/reference/create_smtp_creds_key.html

Use this function to store SMTP credentials in the system's secure key-value store. Requires the `keyring` package. Provide an `id` for the credential set, and optionally `user`, `provider`, `host`, `port`, and `use_ssl`.

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

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

```

--------------------------------

### Load SMTP Credentials from File

Source: https://rstudio.github.io/blastula/reference/credential_helpers.html

Employ `creds_file()` to load SMTP credentials from a specified file path. This file should ideally be generated using the `create_smtp_creds_file()` function.

```R
creds_file(file)
```

--------------------------------

### create_smtp_creds_file

Source: https://rstudio.github.io/blastula/reference/create_smtp_creds_file.html

Creates a file containing SMTP configuration and access credentials for use with smtp_send().

```APIDOC
## create_smtp_creds_file

### Description
Creates a file with SMTP configuration and access credentials to facilitate sending email messages through smtp_send().

### Parameters
- **file** (string) - Required - The output filename for the credentials file.
- **user** (string) - Optional - The username for the email account, typically the email address.
- **provider** (string) - Optional - Email provider shortname for autocompleting SMTP configuration (gmail, outlook, office365).
- **host** (string) - Optional - The address of the SMTP server.
- **port** (integer) - Optional - The port for the SMTP server.
- **use_ssl** (boolean) - Optional - Whether to allow the use of STARTTLS.

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

--------------------------------

### Create SMTP Credentials Key

Source: https://rstudio.github.io/blastula/reference/smtp_send.html

This code snippet shows how to create a credentials key using `create_smtp_creds_key()`. This key can then be used with the `creds_key()` function to send emails.

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

--------------------------------

### add_imgur_image

Source: https://rstudio.github.io/blastula/reference/add_imgur_image.html

Deploys a local image to Imgur and creates an HTML image tag for email.

```APIDOC
## add_imgur_image

### Description
Deploys a local image to Imgur and creates an HTML image tag for email.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
#### Arguments
- **image** (path) - Required - The path to the local image to deploy to Imgur.
- **client_id** (character) - Optional - The Imgur Client ID value.
- **alt** (character) - Optional - Text description for the `alt` attribute of the `<img>` tag.
- **width** (numeric) - Optional - The width of the image in pixels. Defaults to 520.
- **align** (character) - Optional - The alignment of the image. Can be 'center', 'left', 'right', or 'inline'.
- **float** (character) - Optional - The float value for the image. Can be 'none', 'left', or 'right'.

### Request Example
```R
add_imgur_image(image = "path/to/your/local/image.png", client_id = "YOUR_CLIENT_ID")
```

### Response
#### Success Response
An HTML fragment (`<img>` tag) that can be inserted into an email message body.
```

--------------------------------

### Create an email message with Markdown

Source: https://rstudio.github.io/blastula/reference/compose_email.html

Construct an email object using the md() helper function for body and footer content.

```R
# 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
```

--------------------------------

### Render email functions signatures

Source: https://rstudio.github.io/blastula/reference/render_email.html

Use render_email for general email rendering or render_connect_email when deploying to Posit Connect to include a standard footer.

```R
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()
)
```

--------------------------------

### Add Imgur images with add_imgur_image()

Source: https://rstudio.github.io/blastula/news/index.html

The new add_imgur_image() function simplifies embedding external images by deploying a local image to Imgur and retrieving its tag in a single step.

```R
add_imgur_image()
```

--------------------------------

### Send Email Using Credentials Key

Source: https://rstudio.github.io/blastula/articles/sending_using_smtp.html

This approach sends an email using a pre-configured credentials key. It's useful for managing multiple email accounts or providers without re-entering credentials each time.

```R
test_message %>%
  smtp_send(
    from = "personal@email.net",
    to = "personal@email.net",
    subject = "Testing the `smtp_send()` function",
    credentials = creds_key(id = "gmail")
  )
```

--------------------------------

### prepare_test_message()

Source: https://rstudio.github.io/blastula/reference/prepare_test_message.html

Creates an email test message object, useful for testing with smtp_send().

```APIDOC
## prepare_test_message()

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

### Method
N/A (This is an R function, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Arguments 
- **incl_ggplot** (logical) - Optional - An option to include a ggplot plot within the body of the test message. This requires that the ggplot2 package is installed. By default, this is `FALSE`.
- **incl_image** (logical) - Optional - An option to include a test image within the body of the test message. By default, this is `FALSE`.

### Request Example
```R
prepare_test_message(incl_ggplot = FALSE, incl_image = FALSE)
```

### Response
#### Success Response (200)
- **email_message** (object) - An `email_message` object.

#### Response Example
```R
# Example of the returned object structure (actual content will vary)
list(
  "body" = "...",
  "attachments" = list()
)
```

### Examples
```R
# 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"
#       )
#     )
```
```

--------------------------------

### block_articles()

Source: https://rstudio.github.io/blastula/reference/block_articles.html

Creates a responsive layout of one to three articles to be used within a blocks() container.

```APIDOC
## block_articles(...)

### Description
Creates a single- or multi-column layout of articles that are responsive to screen width. Must be placed inside a blocks() function.

### Parameters
#### Arguments
- **...** (article) - Required - One, two, or three calls to the article() function.

### Request Example
blocks(
  block_articles(
    article(image = "url", title = "Title", content = "Text"),
    article(image = "url", title = "Title", content = "Text")
  )
)
```

--------------------------------

### Compose email with title and articles

Source: https://rstudio.github.io/blastula/reference/block_title.html

Demonstrates integrating a title block with side-by-side articles within an email composition.

```R
# 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
```

--------------------------------

### Send Email Using On-Disk Credentials File

Source: https://rstudio.github.io/blastula/articles/sending_using_smtp.html

Send an email by referencing an on-disk credentials file. This is a secure way to store and manage sensitive SMTP credentials, especially in shared or production environments.

```R
test_message %>%
  smtp_send(
    from = "personal@email.net",
    to = "personal@email.net",
    subject = "Testing the `smtp_send()` function",
    credentials = creds_file(file = "gmail_creds")
  )
```

--------------------------------

### Prepare a test message object

Source: https://rstudio.github.io/blastula/reference/prepare_test_message.html

Creates an email_message object with optional ggplot or image attachments.

```R
prepare_test_message(incl_ggplot = FALSE, incl_image = FALSE)
```

--------------------------------

### Compose a Simple HTML Email

Source: https://rstudio.github.io/blastula/articles/blastula.html

Use `compose_email()` to create a basic email with plain text content in the body. This is suitable for straightforward messages.

```R
compose_email(
  body = 
"Hello,\n\nI just wanted to let you know that the thing that you asked me for is ready to pick up. So, come over and do that.\n\nCheers
")
```

--------------------------------

### Send Email with Manual SMTP Credentials

Source: https://rstudio.github.io/blastula/articles/sending_using_smtp.html

Use this method to send an email when you need to manually provide SMTP username and password. Ensure your email provider (e.g., Gmail) allows access for less secure apps or has app-specific passwords configured.

```R
test_message %>%
  smtp_send(
    from = "personal@email.net",
    to = "personal@email.net",
    subject = "Testing the `smtp_send()` function",
    credentials = creds(
      user = "user_name@gmail.com",
      provider = "gmail"
    )
  )
```

--------------------------------

### Store SMTP credentials in a file

Source: https://rstudio.github.io/blastula/articles/sending_using_smtp.html

Use these functions to save SMTP credentials to a local file. This method is less secure than the key-value store as it creates a human-readable file.

```R
# Store SMTP credentials as a file
# with the filename "gmail_creds"
create_smtp_creds_file(
  file = "gmail_creds",
  user = "user_name@gmail.com",
  host = "smtp.gmail.com",
  port = 465,
  use_ssl = TRUE
)
```

```R
# Create a credentials file for sending
# email through Gmail
create_smtp_creds_file(
  file = "gmail_creds",
  user = "user_name@gmail.com",
  provider = "gmail"
)
```

--------------------------------

### render_connect_email

Source: https://rstudio.github.io/blastula/reference/render_email.html

Renders an R Markdown document into an email message specifically for Posit Connect.

```APIDOC
## render_connect_email

### Description
Renders an R Markdown document for the Posit Connect service, allowing for an optional predefined footer.

### Parameters
- **input** (string) - Required - The input file to be rendered.
- **connect_footer** (boolean) - Optional - Include a prepared footer message with links. Default is TRUE.
- **envir** (environment) - Optional - The environment in which the code chunks are to be evaluated.
- **quiet** (boolean) - Optional - Suppress printing of command line output from Pandoc. Default is TRUE.
- **output_options** (list) - Optional - Options passed to rmarkdown::render().
- **render_options** (list) - Optional - Additional arguments for rmarkdown::render().
```

--------------------------------

### View available credential keys

Source: https://rstudio.github.io/blastula/reference/view_credential_keys.html

Use view_credential_keys() to see a tibble of available credential keys, including their id, key_name, and username. The 'id' is necessary for using smtp_send() with the creds_key() helper.

```R
view_credential_keys()
```

--------------------------------

### article() Function

Source: https://rstudio.github.io/blastula/reference/article.html

Defines an article component with optional image, title, content, and link parameters.

```APIDOC
## article(image = NULL, title = NULL, content = NULL, link = NULL)

### Description
Creates an article component used exclusively within block_articles() to arrange content in a row or column.

### Parameters
- **image** (string) - Optional - A URL pointing to an image resource.
- **title** (string) - Optional - A title for the article.
- **content** (string) - Optional - A paragraph of text for the article.
- **link** (string) - Optional - A URL to apply to the content elements.

### Request Example
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"
)
```

--------------------------------

### Compose a basic email message

Source: https://rstudio.github.io/blastula/articles/blastula.html

Use compose_email to assemble email components like body and footer text.

```R
compose_email(
  body = body_text,
  footer = footer_text
)
```

--------------------------------

### Store SMTP credentials in system key-value store

Source: https://rstudio.github.io/blastula/articles/sending_using_smtp.html

Use these functions to securely store SMTP settings. The password will be requested via an interactive prompt.

```R
# Store SMTP credentials using the
# system's secure key-value store;
# provide the `id` of "gmail"
create_smtp_creds_key(
  id = "gmail",
  user = "user_name@gmail.com",
  host = "smtp.gmail.com",
  port = 465,
  use_ssl = TRUE
)
```

```R
# Store SMTP credentials in the
# system's key-value store with
# `provider = "gmail"`
create_smtp_creds_key(
  id = "gmail",
  user = "user_name@gmail.com",
  provider = "gmail"
)
```

--------------------------------

### Compose Email with Glue String Interpolation

Source: https://rstudio.github.io/blastula/articles/blastula.html

Utilize the `glue` package for string interpolation to create more dynamic email content. This avoids manual string concatenation and allows embedding R variables and expressions.

```R
what <- "thing"
salutation <- "Cheers"

body_text <-
  glue(
    "\nHello,\n\nI just wanted to let you know that the {what}
that you asked me for is ready to pick up. So,
come over and do that.\n\n{salutation}\n"   
  )

compose_email(body = body_text)
```

--------------------------------

### Add an image to an email

Source: https://rstudio.github.io/blastula/articles/blastula.html

Use add_image to convert an image file to a Base64 HTML fragment, then wrap it in md to include it in the email body.

```R
# Prepare the image (as a text input)
img_file_path <-
  system.file(
    "img", "rickenbacker_4001_1972.jpg",
    package = "blastula"
  )

image <- add_image(file = img_file_path)

# Generate the body text
body_text <-
  md(glue(
    "
Hello,

I just wanted to let you know that the **1972 Rickenbacker
4001** is here to pick up. Here is a picture of it:

{image}

Cheers,

{sender_name}
"
  ))

# Compose the email message
compose_email(body = body_text)
```

--------------------------------

### Create SMTP Credentials File Function Signature

Source: https://rstudio.github.io/blastula/reference/create_smtp_creds_file.html

This is the function signature for `create_smtp_creds_file()`. It outlines the parameters available for creating an SMTP credentials file.

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

--------------------------------

### Define SMTP Credentials Manually

Source: https://rstudio.github.io/blastula/reference/credential_helpers.html

Use `creds()` to manually specify SMTP server host, port, and SSL usage, along with user credentials. This is useful when provider-specific defaults are not applicable or desired.

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

--------------------------------

### Compose Email Message

Source: https://rstudio.github.io/blastula/index.html

Construct an email object using Markdown and glue templates for the body and footer.

```R
email <-
  compose_email(
    body = md(glue::glue(
"Hello,

This is a *great* picture I found when looking
for sun + cloud photos:

{img_string}
")),
    footer = md(glue::glue("Email sent on {date_time}."))
  )
```

--------------------------------

### Generate and Embed a CTA Button

Source: https://rstudio.github.io/blastula/reference/add_cta_button.html

Create an HTML button fragment and include it within an email body using the md() function.

```R
# 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
```

--------------------------------

### Functions for scheduled email sending in RStudio Connect

Source: https://rstudio.github.io/blastula/news/index.html

New functions are available for integrating Blastula with RStudio Connect for scheduled email sending during R Markdown publication. These include render_email(), render_connect_email(), attach_connect_email(), blastula_email(), suppress_scheduled_email(), and prepare_rsc_example_files().

```R
render_email()
```

```R
render_connect_email()
```

```R
attach_connect_email()
```

```R
blastula_email()
```

```R
suppress_scheduled_email()
```

```R
prepare_rsc_example_files()
```

--------------------------------

### Configure SMTP with Credentials Key

Source: https://rstudio.github.io/blastula/reference/smtp_send.html

Uses the creds_key function to authenticate SMTP delivery via a stored key.

```R
    from = "sender@email.com",
    to = "recipient@email.com",
    credentials = creds_key(
      "gmail"
      )
  )
```

--------------------------------

### Use RETRY() instead of POST() for API calls

Source: https://rstudio.github.io/blastula/news/index.html

Replaced httr::POST() with httr::RETRY() for improved resilience when interacting with web APIs like Mailgun and Imgur. This change enhances the robustness of network requests.

```R
httr::RETRY()
```

--------------------------------

### View Credential Keys

Source: https://rstudio.github.io/blastula/reference/view_credential_keys.html

Retrieves a list of all available credential keys that have been set using the `create_smtp_creds_key()` function. The output is a tibble containing the `id`, `key_name`, and `username` for each credential.

```APIDOC
## View Credential Keys

### Description
Retrieves a list of all available credential keys that have been set using the `create_smtp_creds_key()` function. The output is a tibble containing the `id`, `key_name`, and `username` for each credential.

### Method
GET

### Endpoint
/api/credentials/keys

### Parameters
This endpoint does not accept any parameters.

### Request Example
```json
{
  "message": "No request body needed for this operation."
}
```

### Response
#### Success Response (200)
- **id** (string) - A unique identifier for the credential key.
- **key_name** (string) - The name of the credential key.
- **username** (string) - The username associated with the credential.

#### Response Example
```json
{
  "credentials": [
    {
      "id": "smtp_key_123",
      "key_name": "my_smtp_service",
      "username": "user@example.com"
    },
    {
      "id": "smtp_key_456",
      "key_name": "another_service",
      "username": "another_user@example.com"
    }
  ]
}
```
```

--------------------------------

### Define block_articles signature

Source: https://rstudio.github.io/blastula/reference/block_articles.html

The function signature for creating article blocks.

```R
block_articles(...)
```

--------------------------------

### SMTP credentials via environment variable

Source: https://rstudio.github.io/blastula/news/index.html

The creds_envvar() helper function allows SMTP password input via an environment variable, simplifying credential management.

```R
creds_envvar()
```

--------------------------------

### DELETE /credentials/all

Source: https://rstudio.github.io/blastula/reference/delete_all_credential_keys.html

Deletes all blastula credential keys from the system's key-value store to provide a clean slate.

```APIDOC
## DELETE /credentials/all

### Description
Deletes all blastula credential keys from the system's key-value store. This operation is irreversible and provides a clean slate for credential management.

### Method
DELETE

### Endpoint
delete_all_credential_keys()

### Details
This function requires the 'keyring' package to be installed and available on the system. It is recommended to use 'view_credential_keys()' before deletion to verify existing keys.

### Request Example
delete_all_credential_keys()
```

--------------------------------

### Preview Email

Source: https://rstudio.github.io/blastula/index.html

Display the composed email object in the RStudio Viewer.

```R
# Preview the email
email
```

--------------------------------

### POST /create_smtp_creds_key

Source: https://rstudio.github.io/blastula/reference/create_smtp_creds_key.html

Stores SMTP access credentials in the system-wide key-value store for later use in email sending functions.

```APIDOC
## POST /create_smtp_creds_key

### Description
Stores SMTP credentials in the system's secure key-value store. This function requires the 'keyring' package to be installed.

### Parameters
#### Request Body
- **id** (string/numeric) - Required - An identifying label for the keyname. Cannot be empty or contain hyphens.
- **user** (string) - Optional - The username for the email account.
- **provider** (string) - Optional - Email provider shortname (e.g., 'gmail', 'outlook', 'office365').
- **host** (string) - Optional - The address for the SMTP server.
- **port** (numeric) - Optional - The port for the SMTP server.
- **use_ssl** (boolean) - Optional - Whether to allow the use of STARTTLS.
- **overwrite** (boolean) - Optional - Whether to overwrite existing keys with the same id. Defaults to FALSE.

### Request Example
{
  "id": "gmail_creds",
  "provider": "gmail",
  "user": "user_name@gmail.com"
}
```

--------------------------------

### Posit Connect Integration

Source: https://rstudio.github.io/blastula/reference/index.html

Functions for rendering and attaching emails within the Posit Connect publishing workflow.

```APIDOC
## render_connect_email()

### Description
R Markdown render function for the blastula_email output format.

## attach_connect_email()

### Description
Associates an email when publishing an R Markdown document to Posit Connect.

## prepare_rsc_example_files()

### Description
Prepares example files for Posit Connect emailing with R Markdown.
```

--------------------------------

### Add Imgur Image Function Signature

Source: https://rstudio.github.io/blastula/reference/add_imgur_image.html

This is the function signature for add_imgur_image. It takes an image path and several optional arguments to control how the image is uploaded and displayed.

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

--------------------------------

### Send Email via SMTP

Source: https://rstudio.github.io/blastula/index.html

Transmit the email using SMTP credentials stored in a file.

```R
# Sending email by SMTP using a credentials file
email |>
  smtp_send(
    to = "jane_doe@example.com",
    from = "joe_public@example.net",
    subject = "Testing the `smtp_send()` function",
    credentials = creds_file("email_creds")
  )
```

--------------------------------

### add_cta_button

Source: https://rstudio.github.io/blastula/reference/add_cta_button.html

Generates an HTML fragment for a call-to-action button with customizable text, URL, and alignment.

```APIDOC
## add_cta_button

### Description
Creates an HTML fragment for a call-to-action button. This fragment is intended to be used within an email body via the md() function.

### Parameters
- **url** (string) - Required - A URL for the button.
- **text** (string) - Required - The text that is placed atop the CTA button.
- **align** (string) - Optional - The alignment of the button inside the main content area. Options are "center" (default), "left", and "right".

### Value
A character object containing the HTML fragment for the CTA button.

### Request Example
add_cta_button(url = "http://www.website.net", text = "Press This Button")

### Response Example
"<div style=\"text-align: center;\">...HTML fragment...</div>"
```

--------------------------------

### SMTP Credential Helper Functions

Source: https://rstudio.github.io/blastula/reference/credential_helpers.html

Functions used to generate a credentials list object for the smtp_send() function.

```APIDOC
## SMTP Credential Helpers

### Description
Helper functions to supply SMTP configuration and authorization information for the `smtp_send()` function.

### Functions
- **creds(user, provider, host, port, use_ssl)**: Manual specification of SMTP configuration.
- **creds_anonymous(provider, host, port, use_ssl)**: Anonymous authentication defaults.
- **creds_envvar(user, pass_envvar, provider, host, port, use_ssl)**: Reads password from an environment variable.
- **creds_key(id)**: Retrieves credentials from the system key-value store.
- **creds_file(file)**: Retrieves credentials from a file on disk.

### Parameters
- **user** (string) - Optional - The username for the email account.
- **provider** (string) - Optional - Email provider shortname (gmail, outlook, office365).
- **host** (string) - Optional - SMTP server address.
- **port** (integer) - Optional - SMTP server port.
- **use_ssl** (boolean) - Optional - Whether to use SSL.
- **pass_envvar** (string) - Optional - Environment variable name for the password.
- **id** (string) - Required (for creds_key) - ID of the key in the system store.
- **file** (string) - Required (for creds_file) - Path to the credential file.

### Response
- **Value** (list) - A credentials list object.
```

--------------------------------

### Retrieve SMTP Credentials from Key-Value Store

Source: https://rstudio.github.io/blastula/reference/credential_helpers.html

Use `creds_key()` to fetch SMTP credentials stored in the system-wide key-value store. The `id` argument corresponds to the key created with `create_smtp_creds_key()`.

```R
creds_key(id)
```