RPA.Email.Exchange library | Robocorp documentation

RPA.Email.Exchange

Authorize

Connect to Exchange account

Arguments

Argument	Type	Default value
username	str	null
password	str, None	None
autodiscover	bool	True
access_type	AccessType, str	DELEGATE
server	str, None	None
primary_smtp_address	str, None	None
is_oauth	bool	False
client_id	str, None	None
client_secret	str, None	None
token	dict, None	None

param username:	account username
param password:	account password (can be skipped with OAuth2)
param autodiscover:	use autodiscover or set it off (on by default)
param access_type:	default "DELEGATE", other option "IMPERSONATION"
param server:	required for configuration setting (with autodiscover off)
param primary_smtp_address:	by default set to username, but can be set to be different from username
param is_oauth:	use the OAuth2 authorization code flow (instead of basic auth)
param client_id:	registered application ID
param client_secret:	registered application secret (password)
param token:	contains access and refresh tokens, type, scope, expiry etc.

Create Folder

Create email folder.

Arguments

Argument	Type	Default value
folder_name	str	null
parent_folder	str, None	None

param folder_name:	name for the new folder (required)
param parent_folder:	name for the parent folder, by default INBOX

Delete Folder

Delete email folder.

Arguments

Argument	Type	Default value
folder_name	str	null
parent_folder	str, None	None

param folder_name:	current folder name (required)
param parent_folder:	name for the parent folder, by default INBOX

Delete Message

Delete message.

Arguments

Argument	Type	Default value
message	Dict	null

param message:	dictionary containing message details

Empty Folder

Empty email folder of all items

Arguments

Argument	Type	Default value
folder_name	str	null
parent_folder	str, None	None
delete_sub_folders	bool, None	False

param folder_name:	current folder name (required)
param parent_folder:	name for the parent folder, by default INBOX
param delete_sub_folders:	delete sub folders or not, by default False
return:	True if operation was successful, False if not

Forward Message

Forward message.

Arguments

Argument	Type	Default value
message	Dict	null
recipients	str, List	null

param message:	dictionary containing message details
param recipients:	email address or list of email addresses

Generate Oauth Url

Generates an authorization URL which must be opened by the user to start the OAuth2 flow and obtain an authorization code as response.

Arguments

Argument	Type	Default value
client_id	str	null

param client_id:	Client app ID. (generated by the provider)
returns:	Authorization URL string not containing any sensitive info in it.

Example: Robot Framework

*** Tasks *** Start OAuth Flow ${auth_url} = Generate OAuth URL ... client_id=810482312368-19htmcgcj*******googleusercontent.com Log Start OAuth2 flow: ${auth_url}

Get Oauth Token

Exchanges the code obtained previously with Generate OAuth URL for a token.

Arguments

Argument	Type	Default value
client_secret	str	null
response_url	str	null

param client_secret:	Client app secret. (generated by the provider)
param response_url:	The final URL containing the authorization code found in the address bar after authenticating and authorizing the Client app through the authorization URL.
returns:	A dictionary containing the access & refresh token, plus metadata.

Example: Robot Framework

*** Tasks *** Finish OAuth Flow ${token} = Get OAuth Token ... client_secret=GOCSPX-******mqZAW89 ... response_url=${resp_url} # redirect of Generate OAuth URL

List Messages

List messages in the account inbox. Order by descending received time.

Arguments

Argument	Type	Default value
folder_name	str, None	None
criterion	str, None	None
contains	bool, None	False
count	int, None	100
save_dir	str, None	None
items_only	bool, None	False

param folder_name:	name of the email folder, default INBOX
param criterion:	list messages matching criterion
param contains:	if matching should be done using contains matching and not equals matching, default False is means equals matching
param count:	number of messages to list
param save_dir:	set to path where attachments should be saved, default None (attachments are not saved)
param items_only:	return only list of Message objects (instead of dictionaries)

List Unread Messages

List unread messages in the account inbox. Order by descending received time.

Arguments

Argument	Type	Default value
folder_name	str, None	None
criterion	str, None	None
contains	bool, None	False
count	int, None	100
save_dir	str, None	None

param folder_name:	name of the email folder, default INBOX
param criterion:	list messages matching criterion
param contains:	if matching should be done using contains matching and not equals matching, default False is means equals matching
param count:	number of messages to list
param save_dir:	set to path where attachments should be saved, default None (attachments are not saved)

Move Message

Move a message into target folder

Arguments

Argument	Type	Default value
msg	dict, None	null
target	str, None	null

param msg:	dictionary of the message
param target:	path to target folder
raises AttributeError:	if msg is not a dictionary containing id and changekey attributes

${messages}= List Messages ... INBOX ... criterion=subject:about my orders FOR ${msg} IN @{messages} Run Keyword If "${msg}[sender][email_address]"=="${priority_account}" ... Move Message ${msg} target=INBOX / Problems / priority END

Move Messages

Move message(s) from source folder to target folder

Arguments

Argument	Type	Default value
criterion	str, None
source	str, None	None
target	str, None	None
contains	bool, None	False

param criterion:	move messages matching this criterion
param source:	source folder
param target:	target folder
param contains:	if matching should be done using contains matching and not equals matching, default False is means equals matching
return:	boolean result of operation, True if 1+ items were moved else False

Criterion examples:

subject:my message subject
body:something in body
sender:sender@domain.com

Refresh Oauth Token

Refreshes the token as the access one usually expires after 1h and the refresh one never expires. (as long as it doesn't get revoked)

Arguments

Argument	Type	Default value
client_id	str	null
client_secret	str	null
token	dict	null

param client_id:	Client app ID. (generated by the provider)
param client_secret:	Client app secret. (generated by the provider)
param token:	Full token dictionary previously obtained with `Get OAuth Token`.
returns:	A token dictionary containing a new access token and updated metadata.

Example: Robot Framework

*** Tasks *** Refresh OAuth Flow ${token} = Refresh OAuth Token ... client_id=810482312368-19htmcgcj*******googleusercontent.com ... client_secret=GOCSPX-******mqZAW89 ... token=${token} # from Get OAuth Token

Rename Folder

Rename email folder

Arguments

Argument	Type	Default value
oldname	str	null
newname	str	null
parent_folder	str, None	None

param oldname:	current folder name
param newname:	new name for the folder
param parent_folder:	name for the parent folder, by default INBOX
return:	True if operation was successful, False if not

Save Attachments

Save attachments from message into given directory.

Arguments

Argument	Type	Default value
message	dict, str	null
save_dir	str, None	None
attachments_from_emls	bool	False
overwrite	bool	False

param message:	dictionary or .eml file path containing message details
param save_dir:	file path where attachments will be saved
param attachments_from_emls:	pass True if the attachment is an EML file (for saving attachments from that EML file instead), False otherwise (default)
param overwrite:	overwrite existing downloaded attachments with the same name if set to True, False otherwise (default)
return:	list of saved attachments

Usage

${messages} = List Messages FOR ${msg} IN @{messages} Save Attachments ${msg} %{ROBOT_ARTIFACTS} ... attachments_from_emls=${True} END ${attachments} = Save Attachments ${CURDIR}${/}saved.eml ... %{ROBOT_ARTIFACTS} overwrite=${True}

Save Message

Save email as .eml file.

Arguments

Argument	Type	Default value
message	dict	null
filename	str	null

param message:	dictionary containing message details
param filename:	name of the file to save message into

Send Message

Keyword for sending message through connected Exchange account.

Arguments

Argument	Type	Default value
recipients	List[str], str, None	None
subject	str, None
body	str, None
attachments	List[str], str, None	None
html	bool, None	False
images	List[str], str, None	None
cc	List[str], str, None	None
bcc	List[str], str, None	None
save	bool, None	False
reply_to	str, None	None

param recipients:	list of email addresses
param subject:	message subject, defaults to ""
param body:	message body, defaults to ""
param attachments:	list of filepaths to attach, defaults to None
param html:	if message content is in HTML, default False
param images:	list of filepaths for inline use, defaults to None
param cc:	list of email addresses
param bcc:	list of email addresses
param save:	is sent message saved to Sent messages folder or not, defaults to False
param reply_to:	email address to reply to

Email addresses can be prefixed with ex: to indicate an Exchange account address.

At least one target needs to exist for recipients, cc or bcc.

Send Reply Message

Send reply to a message.

Arguments

Argument	Type	Default value
message	Message, str	null
body	str	null
subject	str, None	None
reply_all	bool	False

param message:	either Message object or ID of the message for the message which this is replying to
param body:	message body for the reply
param subject:	optional subject for the reply, defaults to None
param reply_all:	if True then reply is sent to all recipients, defaults to False

Robot Framework example

${messages}= List Messages criterion=subject:'I have new query' FOR ${m} IN @{messages} # Verifying that this is email that I want to reply to ${now}= RPA.Calendar.Time Now UTC return_format=YYYY-MM-DD HH:mm ${received}= Evaluate str($m["datetime_received"]) ${diff}= RPA.Calendar.Time Difference In Minutes ${received} ${now} # message was received less than 5 minutes # and it came from the expected address IF $diff < 5 and "${m}[sender]" == "mika@robocorp.com" Send Reply Message ... ${m}[id] ... body=I totally agree END END

Wait For Message

Wait for email matching criterion to arrive into INBOX.

Arguments

Argument	Type	Default value
criterion	str, None
timeout	float, None	5.0
interval	float, None	1.0
contains	bool, None	False
save_dir	str, None	None

param criterion:	wait for message matching criterion
param timeout:	total time in seconds to wait for email, defaults to 5.0
param interval:	time in seconds for new check, defaults to 1.0 (minimum)
param contains:	if matching should be done using contains matching and not equals matching, default False is means equals matching THIS PARAMETER IS DEPRECATED AS OF rpaframework 12.9.0
param save_dir:	set to path where attachments should be saved, default None (attachments are not saved)
return:	list of messages