RPA.Email.Exchange library | Robocorp documentation

RPA.Email.Exchange

Authorize

Connect to Exchange account

Arguments

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

param autodiscover:
param username:	account username
param password:	account password (can be skipped with OAuth2)
	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	Description
folder_name	str	null	name for the new folder (required)
parent_folder	str, None	None	name for the parent folder, by default INBOX

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	Description
folder_name	str	null	current folder name (required)
parent_folder	str, None	None	name for the parent folder, by default INBOX

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

Empty Folder

Empty email folder of all items

Arguments

Argument	Type	Default value	Description
folder_name	str	null	current folder name (required)
parent_folder	str, None	None	name for the parent folder, by default INBOX
delete_sub_folders	bool, None	False	delete sub folders or not, by default 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

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	Description
client_id	str	null	Client app ID. (generated by the provider)

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	Description
client_secret	str	null	Client app secret. (generated by the provider)
response_url	str	null	The final URL containing the authorization code found in the address bar after authenticating and authorizing the Client app through the authorization URL.

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	Description
folder_name	str, None	None	name of the email folder, default INBOX
criterion	str, None	None	list messages matching criterion
contains	bool, None	False	if matching should be done using contains matching and not equals matching, default False is means equals matching
count	int, None	100	number of messages to list
save_dir	str, None	None	set to path where attachments should be saved, default None (attachments are not saved)
items_only	bool, None	False	return only list of Message objects (instead of dictionaries)

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	Description
folder_name	str, None	None	name of the email folder, default INBOX
criterion	str, None	None	list messages matching criterion
contains	bool, None	False	if matching should be done using contains matching and not equals matching, default False is means equals matching
count	int, None	100	number of messages to list
save_dir	str, None	None	set to path where attachments should be saved, default None (attachments are not saved)

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	Description
msg	dict, None	null	dictionary of the message
target	str, None	null	path to target folder

raises AttributeError:
param msg:	dictionary of the message
param target:	path to target folder
	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	Description
criterion	str, None		move messages matching this criterion
source	str, None	None	source folder
target	str, None	None	target folder
contains	bool, None	False	if matching should be done using contains matching and not equals matching, default False is means equals matching

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	Description
client_id	str	null	Client app ID. (generated by the provider)
client_secret	str	null	Client app secret. (generated by the provider)
token	dict	null	Full token dictionary previously obtained with Get OAuth Token.

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	Description
oldname	str	null	current folder name
newname	str	null	new name for the folder
parent_folder	str, None	None	name for the parent folder, by default INBOX

param parent_folder:
param oldname:	current folder name
param newname:	new name for the 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	Description
message	dict, str	null	dictionary or .eml file path containing message details
save_dir	str, None	None	file path where attachments will be saved
attachments_from_emls	bool	False	pass True if the attachment is an EML file (for saving attachments from that EML file instead), False otherwise (default)
overwrite	bool	False	overwrite existing downloaded attachments with the same name if set to True, False otherwise (default)

param attachments_from_emls:
param message:	dictionary or .eml file path containing message details
param save_dir:	file path where attachments will be saved
	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

Examples

${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	Description
message	dict	null	dictionary containing message details
filename	str	null	name of the file to save message into

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	Description
recipients	List[str], str, None	None	list of email addresses
subject	str, None		message subject, defaults to ""
body	str, None		message body, defaults to ""
attachments	List[str], str, None	None	list of filepaths to attach, defaults to None
html	bool, None	False	if message content is in HTML, default False
images	List[str], str, None	None	list of filepaths for inline use, defaults to None
cc	List[str], str, None	None	list of email addresses
bcc	List[str], str, None	None	list of email addresses
save	bool, None	False	is sent message saved to Sent messages folder or not, defaults to False

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

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	Description
message	Message, str	null	either Message object or ID of the message for the message which this is replying to
body	str	null	message body for the reply
subject	str, None	None	optional subject for the reply, defaults to None
reply_all	bool	False	if True then reply is sent to all recipients, defaults to False

param reply_all:
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
	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	Description
criterion	str, None		wait for message matching criterion
timeout	float, None	5.0	total time in seconds to wait for email, defaults to 5.0
interval	float, None	1.0	time in seconds for new check, defaults to 1.0 (minimum)
contains	bool, None	False	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
save_dir	str, None	None	set to path where attachments should be saved, default None (attachments are not saved)

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