---
title: "Custom Email Attachments"
slug: "custom-email-attachments"
description: "Enhance your email workflows with custom attachments for PDFs and user-uploaded files, requiring developer setup for seamless integration."
updated: 2026-09-22T14:02:44Z
published: 2026-09-22T14:02:44Z
canonical: "www.civicplus.help/custom-email-attachments"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://www.civicplus.help/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Email Attachments

[Email submission events](/process-automation/docs/add-an-email-submission-event-to-a-form) have a Custom Email Attachments feature. This allows developers to set up an API 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.

> [!NOTE]
> 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. For these instances, you can create an Email event and add a custom attachment. You can then 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. The following is an example of how to generate a custom PDF:

```plaintext
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
}
```
- **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:

```http
Accept: application/jsonContent-Type: application/json
```

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

```json
{"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"}
```

### Request Properties

- **formsAppId:** The identifier for the App
- **formId:** The identifier for the Form
- **externalId:** Your identifier provided using 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 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:

```json
{ 
"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"
}
}
]
}
```

### Response 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 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** Submission Event to a form](/process-automation/docs/add-an-email-submission-event-to-a-form) ![](https://cdn.us.document360.io/17dc564a-8310-4f61-b929-1bd73b36e158/Images/Documentation/Email Event Fields - PADS.png?sv=2026-02-06&spr=https&st=2026-11-12T19%3A08%3A27Z&se=2026-11-12T20%3A08%3A27Z&sr=c&sp=r&sig=hmHec6T3yoN2dJvtyjpTlUJNdNY%2B3xqKJu%2F2GW2fo1g%3D)
2. Toggle on **Include custom attachments**![The Include custom attachments toggle on the email submission event.](https://cdn.us.document360.io/17dc564a-8310-4f61-b929-1bd73b36e158/Images/Documentation/Include%20Custom%20Attachments%20-%20PADS.png?sv=2026-02-06&spr=https&st=2026-11-12T19%3A08%3A27Z&se=2026-11-12T20%3A08%3A27Z&sr=c&sp=r&sig=hmHec6T3yoN2dJvtyjpTlUJNdNY%2B3xqKJu%2F2GW2fo1g%3D)
3. Choose to add a **Custom URL** or **Hosted API**
  - **Custom URL:** Enter the URL address and Secret for an API endpoint ![Form submission section highlighting required URL field and error message for input.](https://cdn.us.document360.io/17dc564a-8310-4f61-b929-1bd73b36e158/Images/Documentation/Custom%20Attachments%20URL%20-%20PADS.png?sv=2026-02-06&spr=https&st=2026-11-12T19%3A08%3A27Z&se=2026-11-12T20%3A08%3A27Z&sr=c&sp=r&sig=hmHec6T3yoN2dJvtyjpTlUJNdNY%2B3xqKJu%2F2GW2fo1g%3D)
  - **Hosted API:** Select a previously created [Hosted API](/process-automation/docs/api-hosting) and a Route from the dropdowns, and add a Secret ![Form fields for Hosted API and Route with required indicators highlighted.](https://cdn.us.document360.io/17dc564a-8310-4f61-b929-1bd73b36e158/Images/Documentation/Custom%20Attachments%20API%20-%20PADS.png?sv=2026-02-06&spr=https&st=2026-11-12T19%3A08%3A27Z&se=2026-11-12T20%3A08%3A27Z&sr=c&sp=r&sig=hmHec6T3yoN2dJvtyjpTlUJNdNY%2B3xqKJu%2F2GW2fo1g%3D)
4. Click **Save![](https://cdn.us.document360.io/17dc564a-8310-4f61-b929-1bd73b36e158/Images/Documentation/Save Workflow - PADS.png?sv=2026-02-06&spr=https&st=2026-11-12T19%3A08%3A27Z&se=2026-11-12T20%3A08%3A27Z&sr=c&sp=r&sig=hmHec6T3yoN2dJvtyjpTlUJNdNY%2B3xqKJu%2F2GW2fo1g%3D)**

Application Programming Interface. A set of rules that allows programmers to develop software for a particular operating system without having to be completely familiar with that operating system.

Portable Document Format.

Software Development Kit. A collection of open-source software development tools designed to enable developers in the creation of applications, integrations, designs, and experiences.

Hypertext Transfer Protocol.

JavaScript Object Notation.

Application. A program that performs a particular task or set of tasks.

Uniform Resource Locator

Forms as a Service. A highly flexible way of deploying forms in a variety of ways to fulfill your use case needs.

Amazon Web Services. A cloud omputing platform that offers a wide range of on-demand services.