This vignette describes how to use Microsoft365R to interact with Outlook for managing and sending email. See the “Authenticating to Microsoft 365” vignette for more details on authentication if required.
Note that Microsoft365R only works with your primary Outlook (Microsoft Exchange) account. It does not support other email providers that you may have connected to your Outlook account, eg Gmail.
To access your Outlook inbox, call either
get_personal_outlook()
or
get_business_outlook()
. The first one is for your personal
account, and the second is for your work & school account. They
return objects of R6 class ms_outlook
, which has methods
for drafting new emails, listing emails in your Inbox, and working with
folders.
outl <- get_personal_outlook()
outlb <- get_business_outlook()
# list the most recent emails in your Inbox
outl$list_emails()
# create and send a new email
outl$create_email("Hello from R", subject="Hello", to="bob@example.com")$send()
# list your mail folders
outl$list_folders()
# get some common folders
inbox <- outl$get_inbox()
drafts <- outl$get_drafts()
sent <- outl$get_sent_items()
deleted <- outl$get_deleted_items()
# get a specific folder by name
folder <- outl$get_folder("myfolder")
To write a new email, call the create_email()
method as
noted above; this returns an object of R6 class
ms_outlook_email
. You can create a blank email which you
then edit using the object’s methods, or supply the details in the
create_email()
call itself. The message will be saved in
the Drafts folder.
# create a draft email
em <- outl$create_email("Hello from R", subject="Hello",
to="bob@example.com", cc="charlie@example.com")
# or: create a blank draft, then add details
em <- outl$create_email()
em$set_body("Hello from R")
em$set_subject("Hello")
em$set_recipients(to="bob@example.com", cc="charlie@example.com")
# alternatively, use method chaining to achieve the same thing
em <- outl$
create_email()$
set_body("Hello from R")$
set_subject("Hello")$
set_recipients(to="bob@example.com", cc="charlie@example.com")
In the example above, the email has a plain text message body which
is the default. To create an email in HTML format, set the
content_type
argument to “html”.
However, Microsoft365R also supports using the blastula and emayili packages to write nicely-formatted HTML emails. In particular, blastula lets you compose your email in Markdown, which is often easier than writing raw HTML.
bl_body <- "## 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"
library(blastula)
bl_em <- compose_email(
body=md(bl_body),
footer=md("sent via Microsoft365R")
)
em <- outl$create_email(bl_em, subject="Hello", to="bob@example.com")
Once the message is created, you send it with its send()
method. Sending an email will move it to the Sent Items folder.
You can add file attachments to a draft email with the
add_attachment()
method. The attachment can be located on
your local machine or in OneDrive/SharePoint. In the latter case, you
should supply a drive item object, along with the details for how it
should be shared: a OneDrive/Sharepoint file is actually attached as a
shared link, and you can specify things like whether to make a viewable
or editable link, the expiry time, whether a password is required, and
so on.
# attach a file on your local machine
em$add_attachment("mydocument.docx")
# attach a file in OneDrive/SharePoint: an editable link, valid for 1 month
item <- get_sharepoint_site("My site")$
get_drive()$
get_item("Documents/myproject.pptx")
em$att_attachment(item, type="edit", expiry="1 month")
The “OneDrive and SharePoint” vignette has more information on drive item objects, including the arguments for creating shared links.
You can also add an image file as an inline attachment with
the add_image()
method. The image will be placed at the end
of the message body, which should be in HTML format. Currently
Microsoft365R does minimal formatting of the inline image; for more
control over layout details, consider using the similar feature in the
blastula package.
# add an inline image: note the email message body must be HTML
em <- create_email("See picture below", content_type="html")
em$add_image("mypicture.jpg")
# or with blastula
library(blastula)
bl_body <- md(c(
"See picture below",
add_image("mypicture.jpg")
))
bl_em <- compose_email(bl_body)
em <- outl$create_email(bl_em)
In addition to the methods noted above, an email message object has the following methods for editing its contents:
add_recipients(to, cc, from)
: Adds recipients to the
email. Unlike set_recipients()
which was used before, this
will retain any existing recipients rather than deleting them.set_reply_to()
: Sets the reply-to email address for the
email.The Outlook client list_emails()
method by default
returns a list of the 50 most recent emails in your Inbox, sorted by
date received. Each email is an object of class
ms_outlook_email
, the same as for messages that you send.
You can customise the list to set the number of emails returned, and the
criterion for retrieving them: by date, sender or subject.
# a list of 50 email objects
outl$list_emails()
# 100 most recent emails
outl$list_emails(n=100)
# 50 emails, sorted by sender in ascending order
outl$list_emails(by="from")
# 200 emails, sorted by subject in descending order
outl$list_emails(by="subject desc", n=200)
A specific email object can be retrieved with
get_email()
. However, as this requires knowing its Outlook
message ID, it will usually be easier to examine the result of
list_emails()
to get the email desired.
You can list the attachments for an email with
list_attachments()
, retrieve the metadata for an attachment
with get_attachment()
, and download the attachment with
download_attachment()
. Note that these methods work both
for messages that you send, and those that you’ve received.
# get the most recent email
em <- outl$list_emails()[[1]]
# a list of the attachments for the email
em$list_attachments()
# get a single attachment object
em$get_attachment("myfile.csv")
# download it
em$download_attachment("myfile.csv")
To delete an email, simply call its delete()
method. By
default, this will prompt you for confirmation first. The email will be
moved to the Deleted Items folder.
An email object has create_reply()
,
create_reply_all()
and create_forward()
methods for creating replies and forwarding. The first argument is the
reply comment, which is inserted above the quoted message body of the
original email. Each of these creates a new draft email, and the methods
described in “Writing emails” above apply here as well.
# get the most recent email in the Inbox
em <- outl$list_emails()[[1]]
# draft a reply to it, adding an attachment
repl <- em$create_reply("See attached report")$
add_attachment("report.md")
# reply-all, setting the reply-to address
repl_all <- em$create_reply_all("Please do not reply")$
set_reply_to("do_not_reply@example.com")
# or forward it
fwd <- em$create_forward("FYI", to="mallory@example.com")
As with drafting new emails, you send a reply by calling its
send()
method:
Also as with writing new emails, you can use blastula and emayili to create the reply comment:
Microsoft365R provides a rich set of tools for managing your email
folders. A folder is represented by an object of R6 class
ms_outlook_folder
, which has methods for listing emails,
drafting replies, and copying and moving items.
# list all the folders in your account
outl$list_folders()
# get a folder by name
folder <- outl$get_folder("myfolder")
# you can also get nested folders
folder2 <- outl$get_folder("top level")$get_folder("2nd level")
# create a new folder
outl$create_folder("test folder")
# delete it
outl$delete_folder("test folder")
In addition, the Outlook client object provides some convenience
functions for retrieving well-known folders: get_inbox()
,
get_drafts()
, get_sent_items()
, and
get_deleted_items()
.
To list the emails in a folder, call its list_emails()
method. This has the same arguments as the list_emails()
method for the Outlook client object; in fact, the latter simply calls
the folder method for the Inbox folder.
# list all the emails in the Inbox -- the same as outl$list_emails()
outl$get_inbox()$list_emails()
# list all the emails in a specific folder
out$get_folder("myfolder")$list_emails()
Similarly, to create a new draft email in a folder, call its
create_email()
method. Again, this has the same arguments
as the Outlook client object method, which calls the folder method for
the Drafts folder.
# create a new email in Drafts -- same as outl$create_email()
outl$get_drafts()$create_email("Hello from R")
# create a new email in a specific folder
outl$get_folder("myfolder")$create_email("Hello from R")
You can move and copy folder items by calling their
move()
and copy()
methods. This works for both
emails and (nested) folders. The destination should be another folder
object.