Python API¶

Outlook.Application¶

class RPA.Outlook.Application.Application(autoexit: bool = True)¶

Bases: object

Outlook.Application is a library for controlling the Outlook application.

Note. Library works only Windows platform.

About Email Filtering

Emails can be filtered according to specification set by Restrict method of the Item class https://docs.microsoft.com/en-us/office/vba/api/outlook.items.restrict.

Couple of examples:

Get Emails
...   email_filter=[Subject]='test email'

Move Emails
...   email_filter=[SenderEmailAddress]='hello@gmail.com'

Examples

Robot Framework

*** Settings ***
Library                 RPA.Outlook.Application
Task Setup              Open Application
Suite Teardown          Quit Application

*** Variables ***
${RECIPIENT}            address@domain.com

*** Tasks ***
Send message
    Send Message       recipients=${RECIPIENT}
    ...                subject=This is the subject
    ...                body=This is the message body
    ..                 attachments=approved.png

Python

from RPA.Outlook.Application import Application

def send_message():
    app = Application()
    app.open_application()
    app.send_message(
        recipients='EMAILADDRESS_1, EMAILADDRESS_2',
        subject='email subject',
        body='email body message',
        attachments='../orders.csv'

For more information, see: https://docs.microsoft.com/en-us/previous-versions/office/developer/office-2007/bb219950(v=office.12)

ROBOT_LIBRARY_DOC_FORMAT = 'REST'¶

ROBOT_LIBRARY_SCOPE = 'GLOBAL'¶

close_document(save_changes: bool = False) → None¶

Close the active document (if open).

Parameters: save_changes – if changes should be saved on close, default False

get_emails(account_name: str = None, folder_name: str = None, email_filter: str = None, save_attachments: bool = False, attachment_folder: str = None, sort: bool = False, sort_key: str = None, sort_descending: bool = True) → List¶

Get emails from a specified email folder. Can be used to save attachments.

Parameters

account_name – needs to be given if there are shared accounts in use, defaults to None
folder_name – target folder where to get emails from, default Inbox
email_filter – how to filter email, default no filter, ie. all emails in folder
save_attachments – if attachments should be saved, defaults to False
attachment_folder – target folder where attachments are saved, defaults to current directory
sort – if emails should be sorted, defaults to False
sort_key – needs to be given if emails are to be sorted
sort_descending – set to False for ascending sort, defaults to True

Returns

list of emails (list of dictionaries)

Example:

${emails}=  Get Emails
...    email_folder=priority
...    email_filter=[Subject]='incoming order'
...    save_attachments=True
...    attachment_folder=%{ROBOT_ROOT}${/}attachments
...    sort=True
...    sort_key=Received
...    sort_descending=False

mark_email_as_read(email: Any, read: bool = True) → None¶

Mark email ‘read’ property. Can be used to mark email as unread.

Parameters

email – target email
read – True marks email as Read, False as Unread

Example:

${emails}=  Get Emails
# Mark all as read
FOR  ${email}  IN  @{emails}
    Mark Email As Read  ${email}
END

# Mark all as unread
FOR  ${email}  IN  @{emails}
    Mark Email As Read  ${email}  False
END

move_emails(account_name: str = None, source_folder: str = None, email_filter: str = None, target_folder: str = None) → bool¶

Move emails from source folder to target folder.

Use of “account_name” is recommended if there are shared accounts in use.

Parameters

account_name – needs to be given if there are shared accounts in use, defaults to None
source_folder – folder where source emails exist
email_filter – how to filter email, default no filter, ie. all emails in folder
target_folder – folder where emails are moved into

Returns

True if move operation was success, False if not

Example:

# moving messages from Inbox to target_folder
Move Emails
...    target_folder=Processed Invoices
...    email_filter=[Subject]='incoming invoice'

# moving messages from source_folder to target_folder
Move Emails
...    source_folder=Incoming Invoices
...    target_folder=Processed Invoices
...    email_filter=[Subject]='incoming invoice'

open_application(visible: bool = False, display_alerts: bool = False) → None¶

Open the Outlook application.

Parameters

visible – show window after opening, default False
display_alerts – show alert popups, default False

quit_application(save_changes: bool = False) → None¶

Quit the application.

Parameters: save_changes – if changes should be saved on quit, default False

save_email_attachments(attachments: Any, attachment_folder: str) → None¶

Save email attachments

Note. Keyword “Get Emails” can be also used to save attachments.

Parameters

attachments – all attachments from email or single attachment
attachment_folder – target folder where attachments are saved, defaults to current directory

Example:

${emails}=  Get Emails
...    email_folder=priority
FOR  ${email}  IN   @{emails}
    FOR  ${attachment}  IN  @{email}[Attachments]
        IF  ${attachment}[size] < 100000   # bytes
            Save Email Attachments
            ...  ${attachment}
            ...  ${CURDIR}${/}attachments
        ELSE IF  ".pdf" in "${attachment}[filename]"
            Save Email Attachments
            ...  ${attachment}
            ...  ${CURDIR}${/}attachments${/}pdf
        END
    END
END

send_email(recipients: Any, subject: str, body: str, html_body: bool = False, attachments: Any = None) → bool¶

Send email with Outlook

Parameters

recipients – list of addresses
subject – email subject
body – email body
html_body – True if body contains HTML, defaults to False
attachments – list of filepaths to include in the email, defaults to []

Returns

True if there were no errors

Example:

Send Email
...    recipients=robocorp.tester@gmail.com
...    subject=hello from Outlook
...    body=empty body
...    attachments=${CURDIR}${/}example.xlsx

send_message(recipients: Any, subject: str, body: str, html_body: bool = False, attachments: Any = None) → bool¶

Send message with Outlook

Parameters

recipients – list of addresses
subject – email subject
body – email body
html_body – True if body contains HTML, defaults to False
attachments – list of filepaths to include in the email, defaults to []

Returns

True if there were no errors

wait_for_email(criterion: str = None, timeout: float = 5.0, interval: float = 1.0) → Any¶

Wait for email matching criterion to arrive into mailbox.

Parameters

criterion – email filter to wait for, defaults to “”
timeout – total time in seconds to wait for email, defaults to 5.0
interval – time in seconds for new check, defaults to 1.0

Returns

list of messages or False

Possible wait criterias are: SUBJECT, SENDER and BODY

Example:

Wait for Email     SUBJECT:rpa task calling    timeout=300    interval=10

wait_for_message(criterion: str = None, timeout: float = 5.0, interval: float = 1.0) → Any¶

Wait for email matching criterion to arrive into mailbox.

Parameters

criterion – message filter to wait for, defaults to “”
timeout – total time in seconds to wait for email, defaults to 5.0
interval – time in seconds for new check, defaults to 1.0

Returns

list of messages or False

Possible wait criterias are: SUBJECT, SENDER and BODY

Example:

Wait for message     SUBJECT:rpa task calling    timeout=300    interval=10

RPA.Outlook.Application.catch_com_error()¶: Try to convert COM errors to human readable format.