Skip to end of metadata
Go to start of metadata

 

See the SendEMailToPage AddOn in the Atlassian MarketPlace

 

Purpose of this plugin:

The goal of this plugin is to make it extremely easy for people to send email to Confluence thereby creating pages, adding attachments, interacting with comment threads, etc.

When possible the plugin allows each page in Confluence (both existing and not yet existing) to have it's own unique email address. Anytime an email is sent to that address the contents of the email will be added to the page.

The idea for this dates back to JotSpot wiki which had this feature implemented wonderfully before Google acquired it.

 

Download Plugin
Download from the plugins.atlassian.com page or directly from the plugin repsitory page.

 

Confluence has some other email capabilities but nothing like this currently exists that lets you send email to Confluence to create content.

Usage Examples:

Examples:

 

Configuration

Navigate to Administration : Send Email To Page Admin

 

You can control how often the email server is polled by navigating to Adminstration: Scheduled Jobs

 

Usage Examples:

Example 1 - Creating a new page:

Preconditions:
  • no page named "My New Page" exists in the space spkey
Email Details:

To: my.account+spkey+My+New+Page@gmail.com

Subject: Subject Of My New Page

Body: Body text of my new page

What happens
  • A page is created in the space with space key: spkey
  • The new page has a title of "My New Page"
  • The new page has body text: "Body text of my new page" 

<video coming>

Example 2 - Adding an attachment:

Everything same as example 1, but if you add attachments to the email they are added to the

Example 3 - Adding comments to a page:

Preconditions:
  • a page named "My New Page" already exists in the space spkey
Email Details:

To: my.account+spkey+My+New+Page@gmail.com

Subject: re: Subject Of My New Page

Body: some comment about this topic

What happens
  • A comment is added to the bottom of the comment list for the page "My New Page"
  • The comment contains the text "some comment about this topic" 

Example 4 - No special details are given in email address:

Preconditions:
  • no page named "My New Page" exists in the space spkey
Email Details:

To: my.account@gmail.com

Subject: Subject Of My New Page

Body: Body text of my new page

What happens
  • A page is created in the default space which is configured in the SendEmailToPage Admin screen
  • The new page has a title of "Subject Of My New Page"
  • The new page has body text: "Body text of my new page"
Note:

I'll be adding other options shortly to give more control over what happens when you don't or can't insert metadata into the email address.

Example 5: Sending an email with a defined 'Default Parent Page'

The default parent page can be defined on the admin tab "EMail Configuration Handling Options"

<video coming>

 

Example 6: Using command tags to route content creation and more

Command tag documentation is found here

<video coming>

 

Troubleshooting:

 

 

Email Page Command Tags:

Command tags version 1.0 allow a user to embed 'tags' that can achieve a wide variety of behavior including routing the content, specifying a page/blog, adding a label to pages, etc.

Command Tag Definitions and Examples:

Command Tag Description:

A "command tag" is a string you can put into an email which gives the sender a great deal of control over the content being created in Confluence. It overrides other settings found elsewhere in the email as well as the default settings found in the admin area. Command tags are stripped from the content before that content is created in Confluence.

For cases where a user wants to send email to create content but only have a standard email server not supporting 'plus addressing' or a 'catchall account' it is still possible to control everything about how and where that emails is used to create content in Confluence.

However there is an additional option. The plugin also searches for a "command tag" of the following format in the emails body content (also searches the subject).

Please note each parameter in the command tag is separated by a colon: :

After each parameter value should be an = sign, thus paramName=paramValue
Mixing up the colon and = sign is easy to do and the primary source of reported issues with the command tags.
Thus the correct format is: <M2P:param=paramValue:param=paramValue>
Colons : and equal signs = cannot be used in parameter value names

<M2P:param=paramValue:param=paramValue>

<M2P:space=MySpaceKey:title=This Is A Page Title>

M2P - searched for by the system to identify a command tag.

  • space (optional) - if this is not included the default space specified on the admin screen will be used
  • title (optional) - specifying this will override the title found in the to: and subject, otherwise the title will default to those
  • parent (optional) - format: "page name" or "spaceKey,page name" this should be a page title or pageId. If this is a 'blog' then this option is ignored.
  • contentType (optional) - "blog" or "page"
  • labels (optional) - format:   <M2P:labels=label1,label2,label3:otherOption=otherOptionValue>
  • soon to be implemented:
    • templatePage (not yet implemented) (optional) -this will look to use a page in the same space for a template unless "templateSpaceKey" is defined at which point we'll look in that space.
    • templateSpaceKey (not yet implemented) (optional) - defines what space to look for the templatePage in.

More examples:
<M2P:space=MySpaceKey:title=This Is A Blog Title:contentType=blog:template=MySpaceKey>

Future - related features:

  • I'm planning to implement an admin feature that lets you define "keywords" that are essentially translated into a specific command tag.

Other notes:

If the target page/blog already exists then the command tag is disabled because it's likely this is a reply to another email.
Characters to keep an eye on in page titles: ":" and ","


Using Templates with SendEMailToPage


Presedence - How the system decides what instructions to use:

For page/blog title:
Email subject for Title
overriden by title found in email address (when found)
overriden by a Command Tag (when found)

Where and what type of content to create:
Admin Screen settings (such as for a space and Page or Blog as the default destination)
overriden by title found in email address (when found)
overriden by a Command Tag (when found)

Currently command tags are only looked for and handled in the email's body, not the subject. If that is of interest please ping me help(at)artemissoftware.freshdesk.com and vote for this issue. Thank you!

 

Confluence Plugin Installation and Configuration

  • standard plugin installation from Confluence's built in "Plugin Repository" or or download from the plugin's front page.
  • There will be a new link on the Administration screen to "Send Email To Page Admin" in the left nav column
  • Enter your account info, click the 'Update' button, click the 'Test Configuration' button
  • Send a test email to the account, then on the admin screen click the "Check Mail Now" button, then navigate to see if your page appeared in Confluence. Note that your page will not appear in 'Recently Updated' or search for a couple of minutes until Confluence indexes it.
  • It seems that Google's GMail is now looking for something along the lines of:

 

protocol: imaps
hostname: imap.googlemail.com
port: 993

 

 

 

 

This demonstrates simple configuration of the plugin and verifying connectivity with your email server. I would recommend clicking through to watch it directly on YouTube and increasing the YouTube "Quality" setting to 480

Displaying a page's unique email address:

Currently you can 'customize' the page template for a space or globally and put this line to execute the macro at the bottom:

 

$helper.renderConfluenceMacro("{SendToPageEmailAddress}")

This needs to be added somewhere into the 'decorator' rendering the Confluence page.

For example in the "Page Layout" which you can access via Space Tools -> Look and Feel -> Layout ->Content Layouts ->Page Layout  (in Confluence 5 that is the location)

as with this screenshot:

Here is a video walk through showing how to add it:  (you will probably want to expand the video by watching directly on YouTube)

You can place this at the top or bottom and surround it with your own text such as "Click here to email this page"

 

Or in case you're using the popular "Documentation Theme" you can configure it to put this in the Footer:

 

{SendToPageEmailAddress}

 

The result will be something like this: 

This screenshot represents only a first cut at this feature of displaying the page's email address. It will get a bit more fancy before long. #.#

Email Server Options To Get the most out of the Plugin:

The Send Email to Page Plugin can be used to create a page anywhere in your Confluence server even with no special email server (IMAP/POP) abilities or settings.

However to get the most out of this plugin you'll want the plugin to be able to parse the to: address to give each page it's own unique address.

There are at least two ways to do this.

Method 1: Plus Addressing (also called email aliasing):

There are several email servers and email services which support "plus addressing". The most well known of these is GMail.

This allows an address such as Steve.Jobs@gmail.com to also receive any email to Steve.Jobs+Some+More+Text@gmail.com where 'Some+More+Text' can be any alphanumeric chars and the + signs represent spaces essentially.

The Send-Email-To-Page-Plugin will get messages from that account and then parse the to: address to see if it can derive a space key and page name to deliver the content/attachments to.

Many companies running Confluence will of course need to run behind a firewall and cannot use GMail or even a GMail account provided by a Google Apps account. However there are some email servers which appear to support 'plus addressing'

  • Dovecot - open source, very well documented, runs everywhere on everything, however requires a sysadmin to install / configure
  • Smarter Tools Mail Server - Windows only, free for up to 10 accounts (this plugin only needs 1), I haven't tried it or tested with it as of yet but plan to shortly #.#
Method 2: Setting up a Catch-all account

Another potentially simple way to set this all up is to create what's called a 'catchall' account. In this case you are able to 'catch' all the email sent to a certain domain and forward it to another account.

So in the scenario you configure an email domain such as mydomain1.com so that email sent to *@mydomain1.com  (where * is a wild card for any address) is then forwarded to an account such as SendEmailToPagePlugin@mydomain2.com

Thus a user could send a note to 'plugin+myspacekey+My+New+Page@mydomain1.com',  then the email would be forwarded to the account 'SendEmailToPagePlugin@mydomain2.com'.  The plugin would go check this account and be able to parse the To: address   thus knowing to create a new page called 'My New Page' in the space having the space key myspacekey.

Here are simple instructions for creating a catchall account at 1and1 hosting. I just did this and it only took a few seconds. Of course most people won't use 1and1 for email hosting, but hopefully something similar can be made to work.

There are likely other similar ways to get this to work without needing 'Plus Addressing' or separate domains. I'll try and get discover some more answers soon.

Screenshots:

Email address aliasing and how Google Mail makes unique page addressing possible:

For this feature to work most effectively the IMAP or POP server being used must support 'email aliasing'.

This feature can be called:

  • plus email addressing
  • address aliasing

(same feature - just different names).

In a nutshell :
  An email account 'your.username' can receive messages sent to your.username+any.alias@somedomain.com. For a GMail example, messages sent to jane.doe+notes@somedomain.com are delivered to jane.doe@gmail.com.

The feature is very clearly and succinctly explained on these two pages:

http://www.smartertools.com/help/smartermail/v3/Topics/User/Mail/PlusAddressing.aspx

 

Configure when and how often the plugin will run

With version 2.x+ you can configure how often the plugin checks for email. Go to Admin -> Scheduled Jobs

 

(click on image to expand)

  • No labels