Custom Email Attachments

Email and Email + PDF submission events have a Custom Email Attachments feature. This allows developers to set up an API (Application Programming Interface) endpoint to return references to files that will be added as email attachments. The endpoint will have a request made to it every time the form workflow event is run.

Important Note

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

Use Cases

Add a Custom PDF to an Email

One example of where this has been used is to 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. You can then use the Software Development Kit (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.

Add Files Uploaded by a 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.

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": "user@example.com",
"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 previous approval step if the user is attempting to complete a request for clarification as part of an approval flow, will be set to null if not specified
• 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 (not 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 Multipurpose Internet Mail Extensions (MIME) type of the file
• attachments[].s3: The Amazon Web Services (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

Instructions

1. Add an Email + PDF or Email Submission Event to a form
   
2. Toggle on Include custom attachments
   
3. Choose to add a Custom URL or Hosted API
   • Custom URL: Enter the URL address and Secret for an API endpoint
     
   • Hosted API: Select a previously created Hosted API and a Route from the drop-downs and add a Secret
     
4. Click Save