WARNING: If you are reading this on GitHub, DON’T! Read the documentation at so you have working references and proper formatting.


Get portal object

Getting the Plone portal object is easy with api.portal.get().

from plone import api
portal = api.portal.get()

Get navigation root

In multilingual or multi-site Plone installations you probably want to get the language-specific navigation root object, not the top portal object.

You do this with api.portal.get_navigation_root().

Assuming there is a document english_page in a folder en, which is the navigation root:

from plone import api
nav_root = api.portal.get_navigation_root(english_page)

returns the folder en. If the folder en is not a navigation root it would return the portal.

Get portal url

Since we now have the portal object, it’s easy to get the portal URL.

from plone import api
url = api.portal.get().absolute_url()

Get tool

To get a portal tool easily, use api.portal.get_tool() and pass in the name of the tool you need.

from plone import api
catalog = api.portal.get_tool(name='portal_catalog')

Get localized time

To display the date/time in a user-friendly way, localized to the user’s preferred language, use api.portal.get_localized_time().

from plone import api
from DateTime import DateTime
today = DateTime()
localized = api.portal.get_localized_time(datetime=today)

Get default language

To get the default language, use api.portal.get_default_language().

from plone import api
lang = api.portal.get_default_language()

Get current language

To get the currently negotiated language, use api.portal.get_current_language().

from plone import api
lang = api.portal.get_current_language()


To translate a message in a given language, use api.portal.translate().

from plone import api
msg = api.portal.translate('Edited', lang='es')

Send E-Mail

To send an e-mail use api.portal.send_email():

from plone import api
    body="One for you Bob!",

If you need to add other fields not supported on send_email signature, Python’s standard email module can also be used:

from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText

message = MIMEMultipart()
message.attach(MIMEText("One for you Bar!"))

part = MIMEText('<xml></xml>', 'xml')
    'attachment; filename="report.xml"'

message['Reply-To'] = ""


Show notification message

With api.portal.show_message() you can show a notification message to the user.

from plone import api
api.portal.show_message(message='Blueberries!', request=request)

Get record

Plone comes with a package that provides a common way to store configuration and settings. api.portal.get_registry_record() provides an easy way to access these.

from plone import api

One common pattern when using registry records is to define an interface with all the settings. api.portal.get_registry_record() also allows you to use this pattern.

from plone import api
api.portal.get_registry_record('field_one', interface=IMyRegistrySettings)

It is possible to provide a default value that will be returned by api.portal.get_registry_record() if the queried record is not found.

from plone import api
api.portal.get_registry_record('foo', interface=IMyRegistrySettings, default=u'bar')
api.portal.get_registry_record('foo', default=u'baz')

Set record

api.portal.set_registry_record() provides an easy way to change configuration and settings.

from plone import api
api.portal.set_registry_record('my.package.someoption', False)

api.portal.set_registry_record() allows you to define an interface with all the settings.

from plone import api
api.portal.set_registry_record('field_one', u'new value', interface=IMyRegistrySettings)

Further reading

For more information on possible flags and usage options please see the full plone.api.portal specification.