Principle:Langfuse Langfuse Export Completion Notification

Knowledge Sources	Langfuse
Domains	Batch Export, Email Notification, User Experience
Last Updated	2026-02-14 00:00 GMT

Overview

Export Completion Notification is the principle of proactively informing the user when their asynchronous batch export has finished processing, by sending an email containing a time-limited download link, so the user does not need to continuously poll the application.

Description

Batch exports are long-running operations that may take seconds to hours depending on data volume. Once the user initiates an export, they typically navigate away from the export page or close the browser entirely. Without a notification mechanism, the user would need to periodically return to the application and check the export status -- a frustrating experience that leads to missed exports and expired download links.

Export Completion Notification addresses this by sending an email when the export pipeline completes successfully. The email contains:

• A personalized greeting using the user's name.
• The name of the export (as specified during creation) so the user can identify which export is ready.
• A prominent download button linking to the signed URL.
• A note that the download link is time-limited (valid for a configurable number of hours).
• A disclaimer that the export does not reflect custom column ordering or visibility settings from the UI.

The notification system is designed with graceful degradation: if SMTP credentials (EMAIL_FROM_ADDRESS and SMTP_CONNECTION_URL) are not configured, the email sending is silently skipped. This allows self-hosted deployments to operate without email infrastructure -- users can still retrieve exports from the application UI. If the email sending fails for any other reason (SMTP error, network timeout), the error is logged but does not cause the overall export to fail. The export status is still set to COMPLETED and the download URL is still stored.

The notification is the final step in the export pipeline, occurring after:

1. The database status has been updated to COMPLETED with the signed URL.
2. The export's finishedAt and expiresAt timestamps have been recorded.

This ordering ensures that even if the email fails, the user can retrieve the export from the UI.

Usage

Use Export Completion Notification whenever:

• An asynchronous operation produces a downloadable artifact that the user needs to retrieve.
• The operation takes long enough that the user is unlikely to be waiting on the same page.
• The download link has a limited lifetime, making timely notification important.
• The platform supports optional SMTP configuration for self-hosted deployments.

Theoretical Basis

The notification follows a fire-and-forget with graceful degradation pattern:

FUNCTION notifyExportComplete(exportRecord, signedUrl):

  -- Step 1: Update database record (already done before this function)
  -- exportRecord.status = COMPLETED
  -- exportRecord.url = signedUrl
  -- exportRecord.finishedAt = NOW
  -- exportRecord.expiresAt = NOW + expirationHours

  -- Step 2: Look up requesting user
  user = LOOKUP(users WHERE id = exportRecord.userId)
  IF user IS NULL OR user.email IS NULL:
    LOG "No user email found, skipping notification"
    RETURN

  -- Step 3: Check email configuration
  IF NOT CONFIGURED(EMAIL_FROM_ADDRESS) OR NOT CONFIGURED(SMTP_CONNECTION_URL):
    LOG "Email not configured, skipping notification"
    RETURN

  -- Step 4: Render and send email
  TRY:
    template = RENDER(BatchExportSuccessEmailTemplate, {
      receiverEmail: user.email,
      downloadLink: signedUrl,
      userName: user.name,
      batchExportName: exportRecord.name,
    })

    SEND_EMAIL({
      to: user.email,
      from: { address: EMAIL_FROM_ADDRESS, name: "Langfuse" },
      subject: "Your data export is ready",
      html: template,
    })

    LOG "Email sent successfully to user {user.id}"
  CATCH error:
    LOG_ERROR(error)
    -- Do NOT throw: email failure must not affect export success status

The React Email rendering approach is worth noting: the email template is a React component that is rendered to static HTML at send time using @react-email/render. This allows the email to use the same component library and styling system (Tailwind CSS) as the web application, ensuring visual consistency. The template includes the Langfuse logo, structured sections, and a styled call-to-action button.

The state machine completion is also significant: the export record's status is updated to COMPLETED before the email is sent. This means that if a user checks the UI while the email is being sent (or if the email fails), they will see the export as completed with a valid download link. The email is purely supplementary notification, not a gate for the status transition.

Related Pages

Implemented By

• Implementation:Langfuse_Langfuse_SendBatchExportSuccessEmail