📎 Send Joget Emails with File Attachments Using BeanShell

Overview

Joget can send notification emails through its built-in email tool, but some projects need to call an external email API and include files uploaded or generated inside Joget. This pattern reads a Joget-managed file, converts it to Base64, builds a JSON payload, and sends it to an email API.

The example below is sanitized with generic field IDs, form table names, API variables, and recipient logic.

How It Works

Resolve recipients from a Joget participant or direct email list.
Read an uploaded/generated file using FileUtil.getFile.
Validate the file extension before attaching it.
Convert the file bytes to Base64.
Send the email payload to an external API using HttpURLConnection.
Close streams and disconnect the HTTP connection in inally.

Where to Use in Joget

Use this in Workflow Builder as a BeanShell Tool after a document is generated, a request is approved, or a certificate/report is ready to send.

Full Code

import java.io.BufferedReader;
import java.io.File;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.util.Base64;
import org.joget.apps.app.model.AppDefinition;
import org.joget.apps.app.service.AppUtil;
import org.joget.apps.form.service.FileUtil;
import org.joget.commons.util.LogUtil;
import org.joget.workflow.model.WorkflowAssignment;
import org.json.JSONArray;
import org.json.JSONObject;

public boolean isSupportedFileType(String fileName) {
    String[] allowedExtensions = {".pdf", ".png", ".jpg", ".jpeg"};
    String lowerName = fileName == null ? "" : fileName.toLowerCase();
    for (String ext : allowedExtensions) {
        if (lowerName.endsWith(ext)) {
            return true;
        }
    }
    return false;
}

public void addAttachment(JSONArray attachments, String fileName, String formTableName, String recordId) {
    try {
        if (!isSupportedFileType(fileName)) {
            LogUtil.warn("email-attachment", "Skipped unsupported file type: " + fileName);
            return;
        }

        File file = FileUtil.getFile(fileName, formTableName, recordId);
        if (file == null || !file.exists() || !file.isFile()) {
            LogUtil.warn("email-attachment", "File not found: " + fileName);
            return;
        }

        byte[] fileBytes = Files.readAllBytes(file.toPath());
        String base64 = Base64.getEncoder().encodeToString(fileBytes);

        JSONObject attachment = new JSONObject();
        attachment.put("name", fileName);
        attachment.put("bytes", base64);
        attachment.put("type", fileName.toLowerCase().endsWith(".pdf") ? "application/pdf" : "application/octet-stream");
        attachments.put(attachment);
    } catch (Exception e) {
        LogUtil.error("email-attachment", e, "Failed to process attachment: " + fileName);
    }
}

public Object execute(WorkflowAssignment assignment, AppDefinition appDef) {
    String apiUrl = "#appVariable.email_api_url#";
    String toParticipantId = "requester";
    String toSpecific = "";
    String cc = "";
    String bcc = "";

    String subject = "Request Completed - #form.service_request.request_no#";
    String htmlContent = "<p>Dear User,</p>"
            + "<p>Your request <strong>#form.service_request.request_no#</strong> has been completed.</p>"
            + "<p>Please find the generated document attached.</p>";

    JSONArray recipients = new JSONArray();
    Object emailObject = AppUtil.getEmailList(toParticipantId, toSpecific, assignment, appDef);
    String[] emailArray = emailObject.toString().replace("[", "").replace("]", "").split(",");
    for (String email : emailArray) {
        email = email.trim();
        if (!email.isEmpty()) {
            recipients.put(email);
        }
    }

    JSONArray attachments = new JSONArray();
    addAttachment(attachments, "Generated Document.pdf", "service_request", "#form.service_request.id#");

    JSONObject payloadJson = new JSONObject();
    payloadJson.put("recipients", recipients);
    payloadJson.put("cc", new JSONArray());
    payloadJson.put("bcc", new JSONArray());
    payloadJson.put("subject", subject);
    payloadJson.put("content", htmlContent);
    payloadJson.put("attachments", attachments);

    HttpURLConnection conn = null;
    OutputStream os = null;
    BufferedReader br = null;
    try {
        URL url = new URL(apiUrl);
        conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("POST");
        conn.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
        conn.setDoOutput(true);

        os = conn.getOutputStream();
        byte[] input = payloadJson.toString().getBytes(StandardCharsets.UTF_8);
        os.write(input, 0, input.length);
        os.flush();

        br = new BufferedReader(new InputStreamReader(conn.getInputStream(), "UTF-8"));
        StringBuilder response = new StringBuilder();
        String line;
        while ((line = br.readLine()) != null) {
            response.append(line);
        }
        LogUtil.info("email-api", "Response: " + response.toString());
    } catch (Exception e) {
        LogUtil.error("email-api", e, "Failed to send email with attachment.");
    } finally {
        try { if (br != null) br.close(); } catch (Exception e) { }
        try { if (os != null) os.close(); } catch (Exception e) { }
        if (conn != null) conn.disconnect();
    }
    return null;
}

return execute(workflowAssignment, appDef);

Example Use Cases

Send generated PDFs after workflow approval.
Attach uploaded documents to a notification email.
Send service-completion certificates through a central email API.
Add images or PDFs to escalation emails.

Customization Tips

Store the API endpoint in an app variable like email_api_url.
Keep allowed extensions strict and small.
Avoid logging full payloads because attachments are Base64 encoded.
Use generic form table names in public examples and real table names only inside your private environment.
Add API authentication headers if your email service requires a token.

Key Benefits

Works with Joget-managed uploaded files.
Keeps attachment handling reusable.
Avoids hard-coded file-system paths.
Sends structured JSON to a central email service.

Security Note

Never publish real email addresses, API URLs, tokens, table names, record IDs, or generated Base64 payloads. Treat attachment payloads as sensitive because they may contain private documents.