RPA.Email.Exchange library | Robocorp documentation

RPA.Email.Exchange

module `RPA.Exchange`

class `RPA.Email.Exchange.Exchange`

Exchange(vault_name: Optional[str] = None, vault_token_key: Optional[str] = None, tenant: Optional[str] = None)

Exchange is a library for sending, reading, and deleting emails. Exchange is interfacing with Exchange Web Services (EWS).

For more information about server settings, see this Microsoft support article.

Examples

Robot Framework

Python

from RPA.Email.Exchange import Exchange from RPA.Robocorp.Vault import Vault vault_name = "email_oauth_microsoft" secrets = Vault().get_secret(vault_name) ex_account = "ACCOUNT_NAME" mail = Exchange( vault_name=vault_name, vault_token_key="token", tenant="ztzvn.onmicrosoft.com" ) mail.authorize( username=ex_account, is_oauth=True, client_id=secrets["client_id"], client_secret=secrets["client_secret"], token=secrets["token"] ) mail.send_message( recipients="RECIPIENT", subject="Message from RPA Python", body="RPA Python message body", )

OAuth2

The OAuth2 flow is the only way of authorizing at the moment as Microsoft disabled entirely the usage of passwords, even App Passwords. And since you have to work with tokens now and because this library has the capability to automatically refresh an expired token, please don’t forget to initialize the library with the following parameters: vault_name, vault_token_key and tenant.

Learn more on how to use the OAuth2 flow in this Portal robot example-oauth-email.

About criterion parameter

Following table shows possible criterion keys that can be used to filter emails. There apply to all keywords which have criterion parameter.

Key	Effective search
subject	subject to match
subject_contains	subject to contain
body	body to match
body_contains	body to contain
sender	sender (from) to match
sender_contains	sender (from) to contain
before	received time before this time
after	received time after this time
between	received time between start and end
category	categories to match
category_contains	categories to contain
importance	importance to match

Keys before, after and between at the moment support two different timeformats either %d-%m-%Y %H:%M or %d-%m-%Y. These keys also support special string NOW which can be used especially together with keyword Wait for message criterion=after:NOW.

When giving time which includes hours and minutes then the whole time string needs to be enclosed into single quotes.

before:25-02-2022 after:NOW between:'31-12-2021 23:50 and 01-01-2022 00:10'

Different criterion keys can be combined.

subject_contains:'new year' between:'31-12-2021 23:50 and 01-01-2022 00:10'

Please note that all values in the criterion that contain spaces need to be enclosed within single quotes.

In the following example the email subject is going to matched only against new not new year.

subject_contains:new year

variable `ROBOT_LIBRARY_DOC_FORMAT`

ROBOT_LIBRARY_DOC_FORMAT = 'REST'

variable `ROBOT_LIBRARY_SCOPE`

ROBOT_LIBRARY_SCOPE = 'GLOBAL'

variable `TO_PROTECT`

TO_PROTECT = ['authorize', 'get_oauth_token', 'refresh_oauth_token']

method `authorize`

authorize(username: str, password: Optional[str] = None, autodiscover: bool = True, access_type: Union[AccessType, str] = AccessType.DELEGATE, server: Optional[str] = None, primary_smtp_address: Optional[str] = None, is_oauth: bool = False, client_id: Optional[str] = None, client_secret: Optional[str] = None, token: Optional[dict] = None)

Connect to Exchange account

Parameters

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

method `create_folder`

create_folder(folder_name: str, parent_folder: Optional[str] = None)

Create email folder.

Parameters

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

method `delete_folder`

delete_folder(folder_name: str, parent_folder: Optional[str] = None)

Delete email folder.

Parameters

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

method `delete_message`

delete_message(message: Dict)

Delete message.

Parameters: message – dictionary containing message details

method `empty_folder`

empty_folder(folder_name: str, parent_folder: Optional[str] = None, delete_sub_folders: Optional[bool] = False)

Empty email folder of all items

Parameters

folder_name – current folder name (required)
parent_folder – name for the parent folder, by default INBOX
delete_sub_folders – delete sub folders or not, by default False

Returns: True if operation was successful, False if not

method `forward_message`

forward_message(message: Dict, recipients: Union[str, List])

Forward message.

Parameters

message – dictionary containing message details
recipients – email address or list of email addresses

method `generate_oauth_url`

generate_oauth_url(client_id: str)

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

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

Example: Robot Framework

method `get_oauth_token`

get_oauth_token(client_secret: str, response_url: str)

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

Parameters

client_secret – Client app secret. (generated by the provider)
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

method `list_messages`

list_messages(folder_name: Optional[str] = None, criterion: Optional[str] = None, contains: Optional[bool] = False, count: Optional[int] = 100, save_dir: Optional[str] = None, items_only: Optional[bool] = False)

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

Parameters

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

method `list_unread_messages`

list_unread_messages(folder_name: Optional[str] = None, criterion: Optional[str] = None, contains: Optional[bool] = False, count: Optional[int] = 100, save_dir: Optional[str] = None)

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

Parameters

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

method `move_message`

move_message(msg: Optional[dict], target: Optional[str])

Move a message into target folder

Parameters

msg – dictionary of the message
target – path to target folder

Raises: AttributeError – if msg is not a dictionary containing id and changekey attributes

method `move_messages`

move_messages(criterion: Optional[str] = '', source: Optional[str] = None, target: Optional[str] = None, contains: Optional[bool] = False)

Move message(s) from source folder to target folder

Parameters

criterion – move messages matching this criterion
source – source folder
target – target folder
contains – if matching should be done using contains matching and not equals matching, default False is means equals matching

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

method `refresh_oauth_token`

refresh_oauth_token(client_id: str, client_secret: str, token: dict)

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)

Parameters

client_id – Client app ID. (generated by the provider)
client_secret – Client app secret. (generated by the provider)
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

method `rename_folder`

rename_folder(oldname: str, newname: str, parent_folder: Optional[str] = None)

Rename email folder

Parameters

oldname – current folder name
newname – new name for the folder
parent_folder – name for the parent folder, by default INBOX

Returns: True if operation was successful, False if not

method `save_attachments`

save_attachments(message: Union[dict, str], save_dir: Optional[str] = None, attachments_from_emls: bool = False, overwrite: bool = False)

Save attachments from message into given directory.

Parameters

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

Returns: list of saved attachments

method `save_message`

save_message(message: dict, filename: str)

Save email as .eml file.

Parameters

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

method `send_message`

send_message(recipients: Optional[Union[List[str], str]] = None, subject: Optional[str] = '', body: Optional[str] = '', attachments: Optional[Union[List[str], str]] = None, html: Optional[bool] = False, images: Optional[Union[List[str], str]] = None, cc: Optional[Union[List[str], str]] = None, bcc: Optional[Union[List[str], str]] = None, save: Optional[bool] = False, reply_to: Optional[str] = None)

Keyword for sending message through connected Exchange account.

Parameters

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

method `send_reply_message`

send_reply_message(message: Union[Message, str], body: str, subject: Optional[str] = None, reply_all: bool = False)

Send reply to a message.

Parameters

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

Robot Framework example

method `wait_for_message`

wait_for_message(criterion: Optional[str] = '', timeout: Optional[float] = 5.0, interval: Optional[float] = 1.0, contains: Optional[bool] = False, save_dir: Optional[str] = None)

Wait for email matching criterion to arrive into INBOX.

Parameters

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

Returns: list of messages