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: Optional[str] = None, folder_name: Optional[str] = None, email_filter: Optional[str] = None, save_attachments: bool = False, attachment_folder: Optional[str] = None, sort: bool = False, sort_key: Optional[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: Optional[str] = None, source_folder: Optional[str] = None, email_filter: Optional[str] = None, target_folder: Optional[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, overwrite: bool = False) → 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

  • overwrite – overwrite existing file if True, defaults to False

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: Optional[Any] = None, save_as_draft: bool = False) → 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 []

  • save_as_draft – email is saved as draft when True

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: Optional[Any] = None, save_as_draft: bool = False) → 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 []

  • save_as_draft – message is saved as draft when True instead (and not sent)

Returns

True if there were no errors

wait_for_email(criterion: Optional[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: Optional[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.