Customizing Portal Emails

    If no email templates are loaded, Kong will fall back to the same emails as Kong Gateway 1.3.0.0. By default on 1.3.0.1 and newer, enabling a non-legacy portal on new workspaces loads default editable email templates. For existing non-legacy Portals, editable email templates must be loaded manually.

    Email-specific values are templated in tokens that work similarly to templating in portal layouts and partials. Not all tokens are supported on all emails.

    • The Kong Developer Portal is not running in Legacy Mode
    • The Kong Developer Portal is enabled and running
    • If using CLI tool, kong-portal-cli tool 1.1 or later is installed locally and git installed

    Understanding Email Files

    Portal templates use a combination of HTML, markdown, and .

    The follow example is the template:

    Like other content files, these files have a headmatter between the two --- . The layout is set by layout attribute, this is the layout file this email will render with.

    • subject sets the subject line for email.
    • heading is an optional value that by default is rendered as a h3

    The body of the email is HTML content. You can reference the tokens allowed for the email in the table below. In this case, {{portal.url}} is used to access the portal url

    Token Descriptions

    TokenDescription
    {{portal.url}}Dev Portal URL for the workspace
    {{email.developer_email}}Developers email
    {{email.developer_name}}Developers full name, this value is collected as part of registration by default. If meta-fields are edited to not include full_name then this will fallback to email
    {{email.admin_url}}Kong Manger URL
    {{email.reset_url}}Dev Portal full URL for resetting password (assumes default path for password reset)
    {{email.token_exp}}Human readable string for amount of time from sending of email, password reset token/url is valid.
    {{email.verify_url}}Link to verify account (assumes default path for account verification))
    {{email.invalidate_url}}Link to invalidate account verification request (assumes default path for account verification))
    {{email.token}}Can be used in combination with {{portal.url}} to manually build url string for password reset and account verification/invalidation. Not recommended for use, unless custom path for password reset or account verification has been set.

    The default email templates will be automatically loaded into the Kong Developer Portal’s file system when the Dev Portal is activated. These templates can now be edited in Kong Manager via the Portal Editor or via the Portal CLI tool. Note: If you are using a Dev Portal initiated in a Kong Gateway version prior to 1.3.0.1, you will need to manually load the email templates into the file system. Follow the steps in .

    Email templates can now be edited in the Portal Editor along with the rest of the files in the Kong Developer Portal file system. To view and edit these files:

    1. Log into Kong Manager and navigate to the Workspace whose Dev Portal you wish to edit.
    2. Select the Editor from the sidebar under Dev Portal.

    1. Clone [https://github.com/Kong/kong-portal-templates\] master branch, and navigate into its directory.
    2. If you have any customizations or permissions changes that you want to keep: Run portal fetch <workspacename> This will pull in your modifications locally.
    3. After making any changes, portal deploy <workspacename> to deploy all files.

    Editing Email Appearance

    To edit the appearance of emails, you can change the layout file emails use. By default, emails are set to use the layout emails/email_base.html. If this file does not exist inside your theme (default theme is base), then a hardcoded fallback will be used.

    You can edit the layout this layout file via the Portal Editor or locally with the Portal CLI tool. Follow the instructions for the editing email text, but modifying the layout file instead.

    If you want different emails to have a different appearance, you can set different layout files for each email file.

    The default email layout looks like:

    The img tag loads the logo that can be set in the appearance tab in the manager. If you do not want to display a logo, remove the <img> tag. If you want to set different sizing for your logo, you can change the inline style attribute.

    By modifying the html of this file, you can change the appearance of your emails. For example if you wanted to add a footer that would show on all emails, add it under the <p> tag

    Note: This is only necessary for existing Dev Portals created on Kong Gateway 1.3.0. New Portals created in 1.3.0.1 and later will have these files already loaded, unless manually deleted.

    Editable email templates can be loaded either via the editor or via the kong-portal-cli tool.

    1. Click New File+.
    2. Select Content type email.
    3. Type in one of the supported paths from above.
    4. Click Create File to generate a default email template that is valid for that email.

    5. Do this for emails you want to edit.

      Note: By default, these emails you create will have layout key set: layout: emails/email_base.html. If you don’t create this layout file, all emails fallback to a default layout. You will want to create this layout if you want to customize the Appearance of emails in addition to message.

    To create an email layout:

    1. Click New File+.
    2. Select Content type theme.
    3. Type in the path for the layout, themes/<THEME_NAME>/layouts/email_base.html. The default theme name is base. The layout that loads in the new portals in 1.3.0.1 is the following (this adds the logo image that can be set in the appearance tab in the manager):

    Find out more about customizing the email layout in the section below.

    1. Clone the portal templates master branch and navigate into the folder you cloned.

    2. If you have any customizations or permissions changes that you want to keep:

      1. Run . This pulls in your modifications locally.

    3. Run portal deploy <workspacename>. This deploys all files.