Custom Email Attachments

This is a developer feature. You will not be able to leverage this functionality without writing code.

There is often a need to be able to add attachments to emails sent via email based form workflow events (currently Email and Email + PDF events). To account for this need, we have added the Custom Email Attachments feature which allows developers to setup an API endpoint to return references to files which will be added as email attachments. The endpoint will have a request made to it every time the form workflow event is run.

How to set up

Custom attachments are configurable for Email and Email + PDF workflow events. To configure the custom attachments open the form you want to add the email event to. Open the workflow tab and add an email event. 

From here turn on the "Include custom attachments" switch. 

This will give you the option to choose between Custom URL or Hosted API, from here you will be able to configure your endpoint and secrets. 

Request

The request will be HTTP Post method with the following request headers:

Accept: application/json
Content-Type: application/json

The request payload will be a JSON object, in the following format:

{
  "formsAppId": 1,
  "formId": 1,
  "externalId": "external identifier",
  "isDraft": false,
  "secret": "ssshhh",
  "submissionId": "85fad0a4-b778-4aea-a6e7-671d84d58156",
  "submissionTimestamp": "2018-01-01T00:00:00.000Z",
  "username": "[email protected]",
  "userToken": "27e009cd8d1e8df917ee0be13262631f:098dec436bc21937a99343ec1112fb22",
  "jobId": "29e8138d-b28c-49da-b357-f4974adbf0a6"
}

Properties

formsAppId

The identifier for the App

formId

The identifier for the Form

externalId

Your identifier provided via the URL or receipt generation when opening the form

isDraft

Set to true  if it was a draft submission

secret

The secret you entered in the submission event configuration

submissionId

The identifier for the submission

submissionTimestamp

An ISO_8601 Timestamp at the time of submission

username

The username of the logged in user that submitted the form (no included for anonymous submissions)

jobId

The identifier for the job if the user is attempting to complete a job, will be set to null if not specified

userToken

 An encrypted token containing an identifier for the user that submitted the form if set by a developer when generating a Forms as a Service (FaaS) URL

Response

The expected response from the endpoint should be in a JSON format. The properties you put in the JSON object should be in the following format:

{ 
  "attachments": [
    { 
      "filename": "image.png",
      "contentType": "image/png",
      "s3": {
        "region": "ap-southeast-2",
        "bucket": "customer.storage.oneblink.io",
        "key": "expires-daily/33ccf39e-7a1e-434f-96c4-9a18e273d914/image.png"
      }
    }
  ]
}

Properties

attachments

An array of attachments

attachments[].filename

The name of the file

attachments[].contentType

The MIME type of the file

attachments[].s3

The AWS S3 configuration referencing the file

attachments[].s3.region

The AWS region the file was uploaded into

attachments[].s3.bucket

The S3 bucket the file was uploaded into

attachments[].s3.key

The key representing the object in S3

Use Cases

Use Case 1: Add a custom PDF to an email

One example of where this has been used is create custom PDFs that are sent as part of the submission. In some instances, you may not want to use the PDF that is generated out of the box as part of the Email + PDF workflow event. For these instances, you can create an Email event and add a custom attachment, use the SDK to generate a custom PDF with the look and feel you want and then attach that to the out-of-the-box email workflow event. 

Below is an example of how to generate a custom PDF.

console.log("Generating custom PDF");
 const pdf = await pdfSDK.generatePDF({
  body: {
   html: pdfHtml,
  },
 });
const OneBlink = require('@oneblink/sdk')
  const options = {
    accessKey: '',
    secretKey: '',
  }
  const forms = new OneBlink.Forms(options)
const emailAttachment = await forms.uploadEmailAttachment({
      filename: 'invoice.pdf',
      contentType: 'application/pdf',
      body: pdf,
    })
 const attachments =
 {
  "attachments": [
   emailAttachment
  ]
 };
 if (Logs.LogLevel <= Logs.LogLevelEnum.info) console.log('attachments:', attachments);
 return attachments
}

Use Case 1: Add files uploaded by user to an email

By default files that are uploaded to the form are included in the Email body as links. These links last as long as your link account retention policy is configured. In some instances you may want to instead add these files as attachments. The custom email attachment feature now allows you to do this using an out of the box email event and some custom development to generate the attachments and add them to your email. 

Get Help

If you have any questions or would like assistance with setting up your Custom Email Attachments please contact us via this support portal or email [email protected]. We are happy to assist in any way we can.