Authorize

Connect to Exchange account

Arguments

Argument Type Default value Description
usernamestrnullaccount username
passwordstr, NoneNoneaccount password (can be skipped with OAuth2)
autodiscoverboolTrueuse autodiscover or set it off (on by default)
access_typeAccessType, strDELEGATEdefault "DELEGATE", other option "IMPERSONATION"
serverstr, NoneNonerequired for configuration setting (with autodiscover off)
primary_smtp_addressstr, NoneNoneby default set to username, but can be set to be different from username
is_oauthboolFalseuse the OAuth2 authorization code flow (instead of basic auth)
client_idstr, NoneNoneregistered application ID
client_secretstr, NoneNoneregistered application secret (password)
tokendict, NoneNonecontains 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 Folder

Create email folder.

Arguments

Argument Type Default value Description
folder_namestrnullname for the new folder (required)
parent_folderstr, NoneNonename 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_namestrnullcurrent folder name (required)
parent_folderstr, NoneNonename 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_namestrnullcurrent folder name (required)
parent_folderstr, NoneNonename for the parent folder, by default INBOX
delete_sub_foldersbool, NoneFalsedelete 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_idstrnullClient 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_secretstrnullClient app secret. (generated by the provider)
response_urlstrnullThe 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_namestr, NoneNonename of the email folder, default INBOX
criterionstr, NoneNonelist messages matching criterion
containsbool, NoneFalseif matching should be done using contains matching and not equals matching, default False is means equals matching
countint, None100number of messages to list
save_dirstr, NoneNoneset 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

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

Arguments

Argument Type Default value Description
folder_namestr, NoneNonename of the email folder, default INBOX
criterionstr, NoneNonelist messages matching criterion
containsbool, NoneFalseif matching should be done using contains matching and not equals matching, default False is means equals matching
countint, None100number of messages to list
save_dirstr, NoneNoneset 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
msgdict, Nonenulldictionary of the message
targetstr, Nonenullpath 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 Messages

Move message(s) from source folder to target folder

Arguments

Argument Type Default value Description
criterionstr, Nonemove messages matching this criterion
sourcestr, NoneNonesource folder
targetstr, NoneNonetarget folder
containsbool, NoneFalseif 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

On Token Refresh

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

Arguments

Argument Type Default value Description
tokenOAuth2Tokennull

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_idstrnullClient app ID. (generated by the provider)
client_secretstrnullClient app secret. (generated by the provider)
tokendictnullFull 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
oldnamestrnullcurrent folder name
newnamestrnullnew name for the folder
parent_folderstr, NoneNonename 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

Save attachments from message into given directory.

Arguments

Argument Type Default value Description
messagedict, strnulldictionary or .eml file path containing message details
save_dirstr, NoneNonefile path where attachments will be saved
attachments_from_emlsboolFalsepass True if the attachment is an EML file (for saving attachments from that EML file instead), False otherwise (default)
overwriteboolFalseoverwrite 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 Message

Save email as .eml file.

Arguments

Argument Type Default value Description
messagedictnulldictionary containing message details
filenamestrnullname 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
recipientsstr, List[str], NoneNonelist of email addresses
subjectstr, Nonemessage subject, defaults to ""
bodystr, Nonemessage body, defaults to ""
attachmentsstr, List[str], NoneNonelist of filepaths to attach, defaults to None
htmlbool, NoneFalseif message content is in HTML, default False
imagesstr, List[str], NoneNonelist of filepaths for inline use, defaults to None
ccstr, List[str], NoneNonelist of email addresses
bccstr, List[str], NoneNonelist of email addresses
savebool, NoneFalseis 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 Message

Wait for email matching criterion to arrive into INBOX.

Arguments

Argument Type Default value Description
criterionstr, Nonewait for message matching criterion
timeoutfloat, None5.0total time in seconds to wait for email, defaults to 5.0
intervalfloat, None1.0time in seconds for new check, defaults to 1.0 (minimum)
containsbool, NoneFalseif 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_dirstr, NoneNoneset 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