ms_outlook_folder {Microsoft365R}

Outlook mail folder

Description

Class representing a folder in Outlook.

Format

An R6 object of class ms_outlook_folder, inheriting from ms_outlook_object, which in turn inherits from ms_object.

Fields

• token: The token used to authenticate with the Graph host.

• tenant: The Azure Active Directory tenant for the email account.

• type: always "mail folder" for an Outlook folder object.

• user_id: the user ID of the Outlook account.

• properties: The item properties (metadata).

Methods

• new(...): Initialize a new object. Do not call this directly; see 'Initialization' below.

• delete(confirm=TRUE): Delete this folder. By default, ask for confirmation first. Note that special folders cannot be deleted.

• update(...): Update the item's properties (metadata) in Microsoft Graph.

• do_operation(...): Carry out an arbitrary operation on the item.

• sync_fields(): Synchronise the R object with the item metadata in Microsoft Graph.

• list_emails(...): List the emails in this folder.

• get_email(message_id): Get the email with the specified ID.

• create_email(...): Creates a new draft email in this folder, optionally sending it as well. See 'Creating and sending emails'.

• delete_email(message_id, confim=TRUE): Deletes the specified email. By default, ask for confirmation first.

• list_folders(filter=NULL, n=Inf): List subfolders of this folder.

• get_folder(folder_name, folder_id): Get a subfolder, either by the name or ID.

• create_folder(folder_name): Create a new subfolder of this folder.

• delete_folder(folder_name, folder_id, confirm=TRUE): Delete a subfolder. By default, ask for confirmation first.

• ⁠copy(dest),move(dest)⁠: Copies or moves this folder to another folder. All the contents of the folder will also be copied/moved. The destination should be an object of class ms_outlook_folder.

Initialization

Creating new objects of this class should be done via the get_folder, list_folders or create_folder methods of this class or the ms_outlook class. Calling the new() method for this class only constructs the R object; it does not call the Microsoft Graph API to retrieve or create the actual folder.

Creating and sending emails

Outlook allows creating new draft emails in any folder, not just the Drafts folder (although that is the default location for the Outlook app, and the ms_outlook client class). To create a new email, call the create_email() method, which has the following signature:

create_email(body = "", content_type = c("text", "html"), subject = "",
             to = NULL, cc = NULL, bcc = NULL, reply_to = NULL, send_now = FALSE)

• body: The body of the message. This should be a string or vector of strings, which will be pasted together with newlines as separators. You can also supply a message object as created by the blastula or emayili packages—see the examples below.

• content_type: The format of the body, either "text" (the default) or HTML.

• subject: The subject of the message.

• ⁠to,cc,bcc,reply_to⁠: These should be lists of email addresses, in standard "user@host" format. You can also supply objects of class AzureGraph::az_user representing user accounts in Azure Active Directory.

• send_now: Whether the email should be sent immediately, or saved as a draft. You can send a draft email later with its send() method.

This returns an object of class ms_outlook_email, which has methods for making further edits and attaching files.

You can also supply message objects as created by the blastula and emayili packages in the body argument. Note that blastula objects include attachments (if any), and emayili objects include attachments, recipients, and subject line; the corresponding arguments to create_email() will not be used in this case.

To reply to or forward an email, first retrieve it using get_email() or list_emails(), and then call its create_reply(), create_reply_all() or create_forward() methods.

Listing emails

To list the emails in a folder, call the list_emails() method. This returns a list of objects of class ms_outlook_email, and has the following signature:

list_emails(by = "received desc", search = NULL, filter = NULL, n = 100, pagesize = 10)

• by: The sorting order of the message list. The possible fields are "received" (received date, the default), "from" and "subject". To sort in descending order, add a " desc". You can specify multiple sorting fields, with later fields used to break ties in earlier ones. The last sorting field is always "received desc" unless it appears earlier.

• search: An optional string to search for. Only emails that contain the search string will be returned. See the description of this parameter for more information.

• ⁠filter, n⁠: See below.

• pagesize: The number of emails per page. You can change this to a larger number to increase throughput, at the risk of running into timeouts.

Currently, searching and filtering the message list is subject to some limitations. You can only specify one of search and filter; searching and filtering at the same time will not work. Ordering the results is only allowed if neither a search term nor a filtering expression is present. If searching or filtering is done, the result is always sorted by date.

List methods generally

All ⁠list_*⁠ methods have filter and n arguments to limit the number of results. The former should be an OData expression as a string to filter the result set on. The latter should be a number setting the maximum number of (filtered) results to return. The default values are filter=NULL and n=100 for listing emails, and n=Inf for listing folders. If n=NULL, the ms_graph_pager iterator object is returned instead to allow manual iteration over the results.

Support in the underlying Graph API for OData queries is patchy. Not all endpoints that return lists of objects support filtering, and if they do, they may not allow all of the defined operators. If your filtering expression results in an error, you can carry out the operation without filtering and then filter the results on the client side.

See Also

ms_outlook, ms_outlook_email

Microsoft Graph overview, Outlook API reference

Examples

## Not run: 

outl <- get_personal_outlook()

folder <- outl$get_folder("My folder")

##
## listing emails
##

# the default: 100 most recent messages
folder$list_emails()

# sorted by subject, then by most recent received date
folder$list_emails(by="subject")

# sorted by from name in descending order, then by most recent received date
folder$list_emails(by="from desc")

# searching the list
folder$list_emails(search="important information")

# retrieve a specific email:
# note the Outlook ID is NOT the same as the Internet message-id
email_id <- folder$list_emails()[[1]]$properties$id
folder$get_email(email_id)

##
## creating/sending emails
##

# a simple text email with just a body:
# you can add other properties by calling the returned object's methods
folder$create_email("Hello from R")

# HTML-formatted email with all necessary fields, sent immediately
folder$create_email("<emph>Emphatic hello</emph> from R",
    content_type="html",
    to="[e-mail]",
    subject="example email",
    send_now=TRUE)

# using blastula to create a HTML email with Markdown
bl_msg <- blastula::compose_email(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 Microsoft365R"))
folder$create_email(bl_msg, subject="example blastula email")


# using emayili to create an email with attachments
ey_email <- emayili::envelope(
    text="Hello from emayili",
    to="[e-mail]",
    subject="example emayili email") %>%
    emayili::attachment("mydocument.docx") %>%
    emayili::attachment("mydata.xlsx")
folder$create_email(ey_email)


## End(Not run)