Python API

Outlook.Application

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

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

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 email
    Send Email         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_email():
    app = Application()
    app.open_application()
    app.send_email(
        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)

Caveats

This library works on a Windows operating system with UI enabled only, and you must ensure that you open the app first with Open Application before running any other relevant keyword which requires to operate on an open app. The application is automatically closed at the end of the task execution, so this can be changed by importing the library with the autoexit=${False} setting.

*** Settings ***
Library     RPA.Excel|Outlook|Word.Application    autoexit=${False}

If you’re running the Process by Control Room through a custom self-hosted Worker service, then please make sure that you enable an RDP session by ticking “Use Desktop Connection” under the Step configuration.

If you still encounter issues with opening a document, please ensure that file can be opened first manually and dismiss any alert potentially blocking the process.

Check the documentation below for more info:

APP_DISPATCH = 'Outlook.Application'
ROBOT_LIBRARY_DOC_FORMAT = 'REST'
ROBOT_LIBRARY_SCOPE = 'GLOBAL'
property app
close_document(save_changes: bool = False) → None

Close the active document and app (if open).

Parameters

save_changes – Enable changes saving on quit. (False by default)

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[Any] = None, target_folder: Optional[str] = None, mark_as_read: bool = True) → 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

  • mark_as_read – mark emails as read after move, defaults to True

Returns

True if move operation was success, False if not

Python example.

outlook = RPA.Outlook.Application()

# moving messages from Inbox to target_folder
outlook.move_emails(
    target_folder='Processed Invoices',
    email_filter="[Subject]='incoming invoice'"
)

# moving messages from source_folder to target_folder
outlook.move_emails(
    source_folder='Incoming Invoices',
    target_folder='Processed Invoices',
    email_filter="[Subject]='incoming invoice'"
)

# move message objects from `get_emails` result
emails = outlook.get_emails("[Subject]='incoming invoice'")
outlook.move_emails(
    target_folder='Processed Invoices',
    email_filter=emails
)

Robot Framework 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'

# moving message objects from `Get Emails` result
${emails}=    Get Emails    [Subject]='incoming invoice'
Move Emails
...    target_folder=Processed Invoices
...    email_filter=${emails}
open_application(visible: bool = False, display_alerts: bool = False) → None

Open the application.

Parameters

  • visible – Show the window on opening. (False by default)

  • display_alerts – Display alert popups. (False by default)

quit_application(save_changes: bool = False) → None

Quit the application.

Parameters

save_changes – Enable to save changes on quit. (False by default)

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: Union[str, List[str]], subject: str, body: str, html_body: bool = False, attachments: Optional[Union[str, List[str]]] = None, save_as_draft: bool = False, cc_recipients: Optional[Union[str, List[str]]] = None, bcc_recipients: Optional[Union[str, List[str]]] = None, reply_to: Optional[Union[str, List[str]]] = None, check_names: 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

  • cc_recipients – list of addresses for CC field, default None

  • bcc_recipients – list of addresses for BCC field, default None

  • reply_to – list of addresses for changing email’s reply-to field, default None

  • check_names – all recipients are checked if the email address is recognized on True, default False

Returns

True if there were no errors

Example:

library = Outlook()
library.open_application()
cc_recipients = ["recipient3@domain.com","recipient4@domain.com"]
library.send_email(
    recipients="recipient1@domain.com",
    cc_recipients=cc_recipients,
    bcc_recipients="recipient3@domain.com;recipient4@domain.com",
    subject="hello from Outlook",
    body="empty body",
    attachments=os.path.join(os.path.curdir, "example.xslx")
)

${cc}=  Create List   recipient3@domain.com   recipient4@domain.com
Send Email
...    recipients=recipient1@domain.com
...    cc_repients=${cc}
...    bcc_repients=recipient5@domain.com;recipient6@domain.com
...    subject=hello from Outlook
...    body=empty body
...    attachments=${CURDIR}${/}example.xlsx
set_object_property(object_instance, property_name: str, value: str)

Set the property of any object.

This is a utility keyword for Robot Framework syntax to set object property values.

${new_value}=    Replace String    ${value}    10.132.    5511.11.
Set Object Property    ${result}    Value    ${new_value}
Parameters

  • object_instance – object instance to set the property

  • property_name – property name to set

  • value – value to set

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