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 knowledgeowl.com 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: 

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.
  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. Username: The username you use to log in to the SMTP Host.
  7. Password: The password you use to log in to the SMTP Host.
  8. 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!)

KnowledgeOwl IP Address

If you need to set up an exception for these communications with your SMTP provider, you'll need our IP address.

KnowledgeOwl currently uses the following IP address:

  • 54.152.202.195
  • 54.84.80.113

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.

To create the App Password:

  1. From the Google Account Settings (https://myaccount.google.com), 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 my-amazing-kb.knowledgeowl.com), 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 help.our-amazing-company.com), 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 my-amazing-kb.knowledgeowl.com), 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 www.mykb.mycompany.com, 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

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.

We only require a v2 reCAPTCHA. 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 https://www.google.com/recaptcha/admin
  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 your reCAPTCHA type. We only require v2 and use "I'm not a robot" checkboxes in the reCAPTCHAs we set up.
  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 support@knowledgeowl.com 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 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, click on the wrench icon next to your private domain. Click the wrench next to your Private Domain
  3. The pop-up will open the configuration for your Private Domain. Copy and paste your reCAPTCHA site key and secret key from Google reCAPTCHA into the fields here: Sample Private Domain with reCAPTCHA key and secret
  4. 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. 

Create the Subscribe button by adding the following merge code to your description of topic categories or the body content of custom content categories: [template("cat-subscribe")]

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.

If you don't want the Subscribe button to appear in the text of the category, but floating next to the heading for the category (as is the default for standard categories), you can add Javascript to a snippet:

  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 positions it in the category header. Only for use in custom content categories."
  5. Click the dropdown next to Snippet Content to select Code Editor.
  6. Copy the script below and paste it into the Code Editor:
    <script>
    	$(function() {
    		$(".ko-cat-sub-cntr").insertBefore($(".hg-article-header"));
    	});
    </script>
  7. Click Save Changes.
  8. Now you can Insert your Snippet into any custom category and it will add the Subscribe button to the category header.

Pro Tip: Save yourself a step and include the subscribe template in your snippet so you only ever have to add the snippet! Sample snippet with the Subscribe button template and the script to insert the button next to the category header

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.

Here is the default button styling:

.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;
}

If you'd like to style the button differently, you can add Custom CSS in Settings > Style.

For example:

.btn.btn-default.ko-cat-sub {
    color: #00BCD4; /* Change button font color to KO theme*/
    border: 1.5px solid #00BCD4; /* 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, go to Settings > Style.

In Custom HTML, make sure you're in the Body section. Copy and paste this code to the bottom of the text editor:

<script>
  $('.documentation-article .ko-cat-sub').click(function(){
      $('#subscription-modal form').submit();
  });
</script>

Add this CSS to the Custom CSS section:

#subscription-modal {
    display: none !important;
}

Save your changes.