Custom Email Attachments

Modified on Mon, 22 Jan 2024 at 11:38 AM

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. 


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": "",
  "userToken": "27e009cd8d1e8df917ee0be13262631f:098dec436bc21937a99343ec1112fb22",
  "jobId": "29e8138d-b28c-49da-b357-f4974adbf0a6"



The identifier for the App


The identifier for the Form


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


Set to true  if it was a draft submission


The secret you entered in the submission event configuration


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


The identifier for the submission


An ISO_8601 Timestamp at the time of submission


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


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


 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


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": "",         "key": "expires-daily/33ccf39e-7a1e-434f-96c4-9a18e273d914/image.png"   }



An array of attachments


The name of the file


The MIME type of the file


The AWS S3 configuration referencing the file


The AWS region the file was uploaded into


The S3 bucket the file was uploaded into


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. 

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 We are happy to assist in any way we can.

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article