ms_outlook_email: Outlook mail message

In Microsoft365R: Interface to the 'Microsoft 365' Suite of Cloud Services

Outlook mail message

Description

Class representing an Outlook mail message. The one class represents both sent and unsent (draft) emails.

Format

An R6 object of class ms_outlook_email, 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 "email" for an Outlook mail message.

• properties: The item properties (metadata).

Methods

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

• delete(confirm=TRUE): Delete this email. By default, ask for confirmation first.

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

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

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

• set_body(body=NULL, content_type=NULL): Update the email body. See 'Editing an email' below.

• set_subject(subject): Update the email subject line.

• set_recipients(to=NULL, cc=NULL, bcc=NULL): Set the recipients for the email, overwriting any existing recipients.

• add_recipients(to=NULL, cc=NULL, bcc=NULL): Adds recipients for the email, leaving existing ones unchanged.

• set_reply_to(reply_to=NULL): Sets the reply-to field for the email.

• add_attachment(object, ...): Adds an attachment to the email. See 'Attachments' below.

• add_image(object): Adds an inline image to the email.

• get_attachment(attachment_name=NULL, attachment_id=NULL): Gets an attachment, either by name or ID. Note that attachments don't need to have unique names; if multiple attachments share the same name, the method throws an error.

• list_attachments(filter=NULL, n=Inf): Lists the current attachments for the email.

• remove_attachment(attachment_name=NULL, attachment_id=NULL, confirm=TRUE): Removes an attachment from the email. By default, ask for confirmation first.

• download_attachment(attachment_name=NULL, attachment_id=NULL, ...): Downloads an attachment. This is only supported for file attachments (not URLs).

• send(): Sends an email. See 'Sending, replying and forwarding'.

• create_reply(comment="", send_now=FALSE): Replies to the sender of an email.

• create_reply_all(comment="", send_now=FALSE): Replies to the sender and all recipients of an email.

• create_forward(comment="", to=NULL, cc=NULL, bcc=NULL, send_now=FALSE): Forwards the email to other recipients.

• ⁠copy(dest),move(dest)⁠: Copies or moves the email to the destination folder.

• get_message_headers: Retrieves the Internet message headers for an email, as a named character vector.

Initialization

Creating new objects of this class should be done via the the appropriate methods for the ms_outlook or ms_outlook_folder classes. 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.

Editing an email

This class exposes several methods for updating the properties of an email. They should work both for unsent (draft) emails and sent ones, although they make most sense in the context of editing drafts.

set_body(body, content_type) updates the message body of the email. This has 2 arguments: body which is the body text itself, and content_type which should be either "text" or "html". For both arguments, you can set the value to NULL to leave the current property unchanged. The body argument can also be a message object from either the blastula or emayili packages, much like when creating a new email.

set_subject(subject) sets the subject line of the email.

set_recipients(to, cc, bcc) sets or clears the recipients of the email. The to, cc and bcc arguments should be lists of either email addresses as character strings, or objects of class az_user representing a user account in Azure Active Directory. The default behaviour is to overwrite any existing recipients; to avoid this, pass NA as the value for the relevant argument. Alternatively, you can use the add_recipients() method.

add_recipients(to, cc, bcc) is like set_recipients() but leaves existing recipients unchanged.

set_reply_to(reply_to) sets or clears the reply-to address for the email. Leave the reply_to argument at its default NULL value to clear this property.

Attachments

This class exposes the following methods for working with attachments.

add_attachment(object, type, expiry, password, scope) adds an attachment to the email. The arguments are as follows:

• object: A character string containing a filename or URL, or an object of class ms_drive_item representing a file in OneDrive or SharePoint. In the latter case, a shareable link to the drive item will be attached to the email, with the link details given by the other arguments.

• ⁠type, expiry, password, scope⁠: The specifics for the shareable link to attach to the email, if object is a drive item. See the create_share_link() method of the ms_drive_item class; the default is to create a read-only link valid for 7 days.

add_image(object) adds an image as an inline attachment, ie, as part of the message body. The object argument should be a filename, and the message content type will be set to "html" if it is not already. Currently Microsoft365R does minimal formatting of the image; consider using a package like blastula for more control over the layout of inline images.

list_attachments() lists the attachments for the email, including inline images. This will be a list of objects of class ms_outlook_attachment containing the metadata for the attachments.

get_attachment(attachment_name, attachment_id): Retrieves the metadata for an attachment, as an object of class ms_outlook_attachment. Note that multiple attachments can share the same name; in this case, you must specify the ID of the attachment.

download_attachment(attachment_name, attachment_id, dest, overwrite): Downloads a file attachment. The default destination filename is the name of the attachment.

remove_attachment(attachment_name, attachment_id) removes (deletes) an attachment.

Sending, replying and forwarding

Microsoft365R's default behaviour when creating, replying or forwarding emails is to create a draft message object, to allow for further edits. The draft is saved in the Drafts folder by default, and can be sent later by calling its send() method.

The methods for replying and forwarding are create_reply(), create_reply_all() and create_forward(). The first argument to these is the reply text, which will appear above the current message text in the body of the reply. For create_forward(), the other arguments are to, cc and bcc to specify the recipients of the forwarded email.

Other methods

The copy() and move() methods copy and move an email to a different folder. The destination should be an object of class ms_outlook_folder.

The get_message_headers() method retrieves the Internet message headers for the email, as a named character vector.

List methods

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=Inf. 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_folder, ms_outlook_attachment

Microsoft Graph overview, Outlook API reference

Examples

## Not run: 

outl <- get_personal_outlook()

##
## creating a new email
##

# a blank text email
em <- outl$create_email()

# add a body
em$set_body("Hello from R", content_type="html")

# add recipients
em$set_recipients(to="[e-mail]")

# add subject line
em$set_subject("example email")

# add an attachment
em$add_attachment("mydocument.docx")

# add a shareable link to a file in OneDrive
mysheet <- get_personal_onedrive()$get_item("documents/mysheet.xlsx")
em$add_attachment(mysheet)

# add an inline image
em$add_image("myggplot.jpg")

# oops, wrong recipient, it should be someone else
# this removes [e-mail] from the to: field
em$set_recipients(to="[e-mail]")

# and we should also cc a third user
em$add_recipients(cc="[e-mail]")

# send it
em$send()

# you can also compose an email as a pipeline
outl$create_email()$
    set_body("Hello from R")$
    set_recipients(to="[e-mail]", cc="[e-mail]")$
    set_subject("example email")$
    add_attachment("mydocument.docx")$
    send()

# 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"))
outl$create_email()
    set_body(bl_msg)$
    set_subject("example blastula email")


##
## replying and forwarding
##

# get the most recent email in the Inbox
em <- outl$list_emails()[[1]]

# reply to the message sender, cc'ing Carol
em$create_reply("I agree")$
    add_recipients(cc="[e-mail]")$
    send()

# reply to everyone, setting the reply-to address
em$create_reply_all("Please do not reply")$
    set_reply_to("[e-mail]")$
    send()

# forward to Dave
em$create_forward("FYI", to="[e-mail]")$
    send()


##
## attachments
##

# download an attachment by name (assumes there is only one 'myfile.docx')
em$download_attachment("myfile.docx")

# a more reliable way: get the list of attachments, and download via the object
atts <- em$list_attachments()
atts[[1]]$download()

# add and remove an attachment
em$add_attachment("anotherfile.pptx")
em$remove_attachment("anotherfile.pptx")


##
## moving and copying
##

# copy an email to a nested folder: /folder1/folder2
dest <- outl$get_folder("folder1")$get_folder("folder2")
em$copy(dest)

# move it instead
em$move(dest)


## End(Not run)

Microsoft365R documentation built on May 31, 2023, 6:10 p.m.