How to send an email attachment to a Confluence page
One workflow I wish that Confluence supported natively was the ability to send an email to a confluence page and then attach the files in that email to the page. After doing some research, I wasn’t able to find a solution that was simple and extensible, so I built one with Zapier.
Automate using Zapier
Zapier has a number of popular apps that they offer at the free tier and several apps provided by Zapier
Zapier has a native app that provides an email gateway. This app is called Email by Zapier and provides a unique email address to send to and integrate with other applications. Though Zapier does have Confluence app, this app only supports one action, to create a page or blog post.
Digging through Confluence Cloud’s api, there is an endpoint that allows you to attach documents to a page.
I was able to build a postman request to confirm the behavior and successfully attach a document to a specific Confluence page.
Looking at other applications in Zapier, the Webhooks by Zapier seemed suitable to send this request. The Webhooks app is not available in the free tier and does require a subscription. The email gateway provided by zapier and the webhook combined should be able to send an email with an attachment to Confluence page.
Zap Design
The configuration is a bit complex, but the design is simple.
Looking at the Zapier trigger, select a New Inbound Email then click continue.
Zapier generates a custom email address for you. You must provide a prefix to the generated email to move to the next step. This email will be used to test the trigger and check the fields that Zapier finds on the incoming email in the next step.
After you send an email, you should see that email in the test trigger section
The next step is configuring the webhook. Start by selecting the Action Event PUT and click continue.
Next, enter the URL for the Confluence cloud API call to add/update an attachment on a page. I tested this by hard coding a confluence page id. You can see a page id in Confluence cloud as the numerical id after the /wiki/spaces /<YOURSPACENAME>/pages/<THISISYOURPAGEID>. Select the Payload type as Form and then add the fields minorEdit, file, and comment as seen below. Place the email attachment field in both the file value in the form section and in the file section below.
In the bottom half of the webhook definition, add your authentication in the Basic Auth section. This page from Confluence describes how the API uses basic authentication and this page describes how to obtain your token. Once you have this completed, you can test this zap and enable it.
After you’ve setup this zap, you should be able to send an email with an attachment to the zapier email address on the trigger. This zap is hard coded to a single page for now. Next we’ll see how to use email aliases to pass in the page id.
Using an email with a plus email alias
Both Google Workspace and Outlook support the ability to alias an email address by using a plus sign in the name portion of the email.
To make the zap more extensible, I created a google group in our Google Workspace that has as a single member, the zapier email. This allows me to use the google group name to pass a parameter to the zap. For example, if the group name is cfattachments@mydomain.com I can add the page id after the plus symbol and use that in the zapier to send the email attachment to a specific page. So an example email address would look like cfattachments+8005882300@mydomain.com. Now we need to add a bit of logic to the zap to extract this page id.
Extracting the page Id from the username
Returning to our zap, if we add a step that that is the Zapier Formatter and select the Text event and select continue.
We can use the Extract Number operation to extract the number from the user portion of the email. I found that the field I need to extract from was the Raw To: field.
After you select this field, try to test your zap.
One thing you will notice is that it seems to capture the “+” from the email address. It seems that this doesn’t impact the PUT operation on the api call to Confluence.
Warning
You should secure the email address provided by zapier to prevent unauthorized users from posting attachments to your pages. You should ensure that only people in your enterprise can send to the google (or outlook) group that you create.
This zap is a reference design. This does not take into consideration malformed inputs or error conditions.
Limitations
I haven’t been able to figure out how to have multiple attachments added to a single page. If there are multiple attachments, it seems zip them up and add the zip file to the page. This is less desirable for me as typically I want to see what I’ve attached and not have to download it to see the contents.
You have to lookup the page id for each new page that you want to send an attachment to. You can reduce subsequent lookups by storing a contact for pages that you intend to send to frequently.
The zap should be updated to be more robust to handle failure conditions like no attachment, and id that doesn’t exist, or a malformed id.
