Configuring subscriptions

Requirements for enabling subscriptions

To enable subscriptions, you'll need to:

  1. Configure your SMTP settings: You must use your own or a third party SMTP server to send subscription emails.
  2. Configure the email schedule and subject for notification emails.
  3. Edit your subscription settings to enable subscriptions.
  4. Generate and add a reCAPTCHA: This is only necessary when you want to enable subscriptions on a public knowledge base where readers aren't required to log in before viewing content and you're using your own domain rather than a subdomain.

Note: You must complete steps 1-3 for subscriptions to work properly. You will need the SMTP details for your email server before you begin this process.

Configure SMTP for subscriptions

The KnowledgeOwl subscription notification system uses your own or a third-party SMTP email server to send email notifications. Before you enable subscriptions in your knowledge base, you'll need to configure the SMTP settings so that KnowledgeOwl can talk to your SMTP server.

Configure your SMTP Settings

To do so, go to Settings > Subscriptions.

Scroll to the SMTP section: 

SMTP settings

You'll need to configure each field:

  1. SMTP Host: The address your email server provides for the SMTP host.
  2. Port: Most providers will have specific recommended ports. Where possible and supported, we recommend using port 587, as this is the port used by modern email servers for secure submission of email for delivery. If you'd like to encrypt emails during transmission, we recommend using port 587 with TLS enabled unless otherwise directed by your provider.
  3. Send From Address: The email address that will show up in the "From" field for all subscription notification emails.
    If you're using Google's SMTP, it will automatically override whatever Send From address you use here with the SMTP Username.
  4. Reply To Address: The email address that will show up in the "Reply-to" field for all subscription notification emails. 
  5. Send From Name: The name that will show up in the "From" field for all subscription notification emails.
  6. Unauthenticated: If your SMTP server doesn't utilize a username or password, check this box. This will hide the Username and Password sections and you can jump straight to sending a test email.
  7. Username: The username you use to log in to the SMTP Host.
  8. Password: The password you use to log in to the SMTP Host.
  9. Send Test Email: Once you have entered your SMTP settings, send a test email to an email address of your choice to confirm the settings work properly. (See below!)

Once you're happy with the test email, you can finish configuring this feature. See below for more information.

KnowledgeOwl IP Address

If you need to set up an exception for these communications with your SMTP provider, please contact support for a list of IP addresses.

Find your SMTP settings

Each email server is a bit different, but we've tried to capture information on finding your SMTP settings from these popular providers:

If your provider isn't listed above, see what information they have on configuring SMTP mail relay for external use or checking your SMTP settings.

Gmail with Two-Factor Authentication (2FA)

For Gmail, you'll most likely need to set up an App Password. If you get a warning referencing error code 5.7.9 when you send a test email, you definitely need to set one up. This is most common with Gmail with two-factor authentication (2FA) but may be necessary for other Gmail configurations.

You'll use the App Password in place of your normal Gmail password. All the other SMTP settings are the same as regular Gmail accounts.

If you're using Google's SMTP, it will automatically override whatever Send From address you use with the SMTP Username, so be sure you're using the best account available to generate your App Password.

To create the App Password:

  1. From the Google Account Settings (, click on Security on the left.
  2. About halfway down the screen, in the Signing In to Google section, click the App Passwords link.
  3. The next screen creates and manages App Passwords that will work with 2FA. Click on the dropdown to select an app and select 'Custom' to type in 'KnowledgeOwl' (or something else that will identify that this password is for your KB!).
  4. Click Generate.
  5. A 16-digit password will appear. This is good for only a few minutes. Copy it.
  6. In KnowledgeOwl's SMTP settings, paste the 16-digit password you copied instead of the normal Gmail password.
  7. Finish filling out the rest of the SMTP settings using standard Gmail settings and save.

If you do receive error 5.7.9, there's more information on how to resolve it (and more detail on the above steps) available in Google Account Help for Sign in using App Passwords.

Send a test email for SMTP

Once you have entered your SMTP settings, click the button to send a test email. Following these steps will send a sample subscription notification email using some of our KnowledgeOwl documentation, so you'll be able to see the formatting your subscribers can expect.

We strongly encourage you to do this because it:

  • Lets you confirm that your SMTP host, port, username, and password are properly configured
  • Lets you see how the names and email addresses you've configured show up
  • Lets you see a sample of the layout and structure of the subscription notifications
  • Lets you see this sample and test the settings without having to enable subscriptions for your entire knowledge base

To do , click the Send Test Email button.

This will open a pop-up where you can specify the email address you'd like to send the test to. Enter the test recipient email address and click Send Email.

If anything is improperly configured, you'll get an error message. This should be one of two types:

  • Basic validation: we'll alert you if the email addresses you've entered don't follow standard email address conventions or if no fields have been left blank. 
  • SMTP provider validation: if the error comes from the call to your SMTP provider, we'll return the error message they provide

If everything is properly configured, you'll see a confirmation message:

You should receive an email with the subject line matching the Email Subject defined above, from the address specified in your Send From Address. It should look something like this:

Configure subscription notification schedule and email subject

To enable subscriptions, you'll configure a global notification schedule and email subject line.

To do so, go to Settings > Subscriptions.

Email Schedule

You can schedule notification emails to go out once a day or once a week.

Regardless of the email schedule you select, subscription notification emails will only be sent if there is new or updated content to notify subscribers about.

To send emails once a day, select "Daily."

To send emails once a week, select the day of the week you'd like them to be sent on:

Then select the time of day you'd like the emails sent.

Note: All times used in this schedule are in U.S. EST timezone.

Be sure to click Save once you've made changes to your email schedule!

Email Subject

By default, the email subject for notification emails is set to be:

{{kbName}} Update for {{prettyDate}}

This pulls your knowledge base name as it appears in Settings > Basic and the date as "Month day" (e.g. February 19th). You can modify the subject however you'd like.

Be sure to click Save once you've made changes to your email subject line!

Configure public subscriptions

By default, subscriptions will only be enabled for logged-in readers only.

If you have a knowledge base that is partially or fully available to the public (e.g. doesn't require people to log in to read content), you might want to enable subscriptions for readers who aren't logged in. We call these Public Subscriptions.

Enabling public subscriptions in KnowledgeOwl subdomains

If you are using a KnowledgeOwl subdomain for your knowledge base (such as, to enable public subscriptions:

  1. Go to Settings > Subscriptions.
  2. Check the box next to Enable subscriptions for readers on public knowledge bases

  3. Click Save.

Enabling public subscriptions with private domains

If you are using a private domain for your knowledge base (such as, you will need to add a reCAPTCHA for your public subscriptions. We require this to prevent bot traffic.

If you are using a KnowledgeOwl subdomain (such as, you don't need to configure your own reCAPTCHA.

However, if you have customized your knowledge base to use your own private domain, such as, you'll need to add your own reCAPTCHA to your site if you have any of these options enabled:

  • Settings > Comments: The "Only allow logged in readers and users to leave comments" box is unchecked (e.g. you allow unrestricted commenters)
  • Settings > Subscriptions: The "Enable public subscriptions" box is checked (e.g. you allow public subscriptions)
  • Knowledge Base > Contact Form: The "Require ReCaptcha "I'm not a robot" validation to submit a ticket" box is checked
    • If you are using this setting and also using Contextual Help Widget (2.0), you'll also need to add a V3 reCAPTCHA to add reCAPTCHA to the Contact tab on the Widget.
    • If you are using this setting and don't have reCAPTCHA enabled, your contact form will display an invalid domain error to your end-users.

What is reCAPTCHA?

reCAPTCHA is a free service from Google designed to verify that someone signing up for a subscription is a real person and not a bot. A "CAPTCHA" is a simple test--usually a task that is very easy for a human to perform, but hard for bots and other malicious software to figure out. There are two versions of reCAPTCHA:

  • v2: Verify requests with a challenge. Example: checking a box next to "I am not a robot."
  • v3: Verify requests with a score. Example: click on all the images that have cars in them.

KnowledgeOwl currently supports specific versions in specific places:

  • v2: Supported in the full knowledge base; not supported in Contextual Help Widget (2.0). For these reCAPTCHAs, configurations with "I am not a robot" reCAPTCHAs, and you can see one in action if you try to subscribe to a category in this knowledge base.
  • v3: Supported in Contextual Help Widget (2.0); not supported in the full knowledge base.

Only v2 reCAPTCHAs will work properly in KnowledgeOwl. We've tested our configurations with "I am not a robot" reCAPTCHAs, and you can see one in action if you try to subscribe to a category in this knowledge base!

Creating a new reCAPTCHA

To create a new reCAPTCHA, you'll need a Google account.

  1. Go to
  2. If you've never generated a reCAPTCHA before, this should take you directly into the page to create one. If you've generated a reCAPTCHA before, you'll need to click the + in the upper right to Create a new reCAPTCHA.
  3. Pick a label for your reCAPTCHA. You might use the name of your knowledge base or the URL for it.
  4. Select the reCAPTCHA type:
  5. For domain, use the URL of your KnowledgeOwl knowledge base.
  6. Your Gmail account will automatically be added as an Owner. You can add additional email addresses. If you'd like us to be able to help troubleshoot issues with your reCAPTCHA, add as an owner.
  7. You'll need to check the box next to Accept the reCAPTCHA Terms of Service.
  8. You can choose to receive or opt out of alerts to owners. These alerts will notify you if Google detects problems with your site, such as misconfigurations affecting the reCAPTCHA or increases in suspicious traffic. We recommended receiving the alerts.

    So a completed v2 reCAPTCHA might look something like this:

  9. Once you've entered all your selections, click Submit.
  10. This will take you to a confirmation screen that will provide you with the Site Key and the Secret Key for your reCAPTCHA. You'll need these to add them to your knowledge base!

Add your reCAPTCHA to your knowledge base

With your reCAPTCHA generated, you can add the site key and secret key to your knowledge base. To do so:

  1. Go to Settings > Basic.
  2. In Domain Settings, copy and paste your reCAPTCHA site key and secret key from Google into the appropriate fields here. Note the different sections for reCAPTCHA Key V2 and reCAPTCHA Key V3. Be sure you're using the right ones!Sample Private Domain with v2 and v3 reCAPTCHA keys and secrets
  3. When you're done making changes, click Save.

Once you have a reCAPTCHA key and secret, go to Settings > Subscriptions, check the box next to Enable subscriptions for readers on public knowledge bases (no login) and click Save.

Enable subscriptions

Once you've added your SMTP settings and edited your Email Schedule and Subject to your liking (and, optionally, enabled Public Subscriptions and added a reCAPTCHA), you're ready to turn on Subscriptions.

Just check the box next to Enable reader subscriptions and click Save.

Do not enable reader subscriptions until you have, at minimum, configured your SMTP settings. Without a valid SMTP configuration, no emails will be sent.

Add Subscribe button to topic and custom content categories

Subscribe buttons are automatically added to most category landing pages. They do not appear by default on topic or custom content categories.

If you'd like to add a Subscribe button to a custom content category or topic display category and have it float next to the category header (as is the default for standard categories), you can handle this by creating a snippet that will generate the Subscribe button and adding it to the categories manually.

To do so:

  1. Go to Library > Snippets.
  2. Click on the + Create New Snippet button. 
  3. Give your snippet a Snippet Name, like "Custom Content Subscribe Button". The Merge Code Name will be automatically generated from that Snippet Name, though you can adjust it if you'd like.
  4. Give your snippet a Description, like "This snippet adds the Subscribe button to custom content categories and topic display categories it's added to. It positions the button in the category header. For custom content categories, insert the snippet anywhere into the body of the category; for topic display categories, paste the snippet merge code into the category description."
  5. Click the dropdown next to Snippet Content to select Code Editor.
  6. Copy the script below and paste it into the Code Editor:
    	$(function() {
    		$(".ko-cat-sub-cntr").insertBefore($(".hg-article-header h1"));
  7. Once you're done editing your snippet, be sure to Create it.

With your snippet created, you can now add it to the categories you wish:


If you'd like to play around with where the Subscribe button is positioned, you can see the default behavior by copying this merge code and pasting it into your description of topic categories or the body content of custom content categories: 

This will create a float-right Subscription button wherever you've placed the template code:

This Subscribe button will inherit the styling for Subscription buttons across your site. You can also Style the Subscribe button differently.

Style the Subscribe button differently

There are two CSS classes that impact the Subscribe button:

  • .btn.btn-default.ko-cat-sub: This is the styling for the button itself. So if you'd like to change the button styling in some way, here's where you do it. This might include: background color, the color (for the text), the border, box-shadow, or padding between the text and the button edges.
  • .ko-cat-sub-cntr: This container is what gives the Subscribe button its float: right positioning and the margin-right. If you'd like to change button positioning on the page, you'll want to add custom CSS for this class.

To adjust the style for the button:

  1. Go to Settings > Style.
  2. Below the preview pane, be sure Custom CSS is selected.
  3. Copy the default styling for the button from here and paste it into your Custom CSS:
    .btn.btn-default.ko-cat-sub {
        background: #fff; /* Button color */
        color: #333; /* Subscribe font color */
        border: 1.5px solid #555; /* Button border--#555 sets the color */
        box-shadow: none;
        padding: 8px 18px;
  4. Edit as necessary to get the look and feel you want.
  5. Save your changes.

For example, here, we've added CSS to style the Subscribe button font color and button border to match the color we use across our theme:

.btn.btn-default.ko-cat-sub {
    color: #1d284f; /* Change button font color to KO theme*/
    border: 1.5px solid #1d284f; /* Change border color to KO theme*/

Force readers to subscribe using their reader account email address

By default, when readers subscribe to a category, they will first see a pop-up where they can enter the email address of their choice. This is by design, since some of our customers have readers who share accounts (such as one reader account per client, consulting firm, partner, etc.).

But if you always require your readers to have their own email address, you can bypass the screen where they enter an email address entirely, and take them straight to the Manage Subscriptions page.

This approach has a few advantages:

  • It's more foolproof. There's no risk that they'll enter an improperly-formatted email address, or one with a typo in it.
  • It's faster. It removes the extra step to enter an address and click another button before they're subscribed.
  • It prevents the use of personal email addresses. You may have security or compliance reasons why you don't even want links to your knowledge base content to be emailed to non-work email addresses.

Note: you cannot make these changes if you are using Public Subscriptions.

To make these changes:

  1. Go to Settings > Style.
  2. Below the Preview pane, be sure Custom HTML is selected.
  3. Next to the Custom HTML dropdown, be sure Body is selected.
  4. Copy the code below and paste it into the bottom of the Custom HTML editor:
      $('.documentation-article .ko-cat-sub').click(function(){
          $('#subscription-modal form').submit();
  5. Now select Custom CSS below the Preview pane.
  6. Copy the CSS Below and paste it anywhere into the Custom CSS section:
    /* Hide the Subscription modal by default */
    #subscription-modal {
        display: none !important;
  7. Save your changes.