RPA.Email.Exchange

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 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 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 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 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

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}

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 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)

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 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

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

Examples

${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 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

Callable you can override in order to save the newly obtained token in a safe place.

Arguments

Argument	Type	Default value	Description
token	OAuth2Token	null

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 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 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 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 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

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 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

Keyword for sending message through connected Exchange account.

Arguments

Argument	Type	Default value	Description
recipients	str, List[str], None	None	list of email addresses
subject	str, None		message subject, defaults to ""
body	str, None		message body, defaults to ""
attachments	str, List[str], None	None	list of filepaths to attach, defaults to None
html	bool, None	False	if message content is in HTML, default False
images	str, List[str], None	None	list of filepaths for inline use, defaults to None
cc	str, List[str], None	None	list of email addresses
bcc	str, List[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.

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