Notify by Email (Auto-Dispatch)

Automatically email self-destructing secret links to recipients from the UI or API

Notify by Email (Auto-Dispatch)

Available in OSS Password Pusher v2.9.0+ and on pwpush.com Pro.

OSS Password Pusher can automatically email the secret link to one or more recipients when a push is created. This feature is called Notify by Email (or Auto-Dispatch).

Auto-dispatch was originally introduced as part of the Pro edition on pwpush.com and has been added to OSS Password Pusher through the Feature Pipeline.

Overview

When creating a push, signed-in users can enter up to 5 recipient email addresses. The application will email each recipient a message containing the secret link, expiration details, and an optional passphrase notice.

Auto-dispatch is available:

• From the push creation form in the web UI (text, file, URL, and QR pushes)
• From the push preview page after a push has been created
• Via the JSON API v2 (on creation or as a separate call for existing pushes)

Requirements

Auto-dispatch activates automatically when all three conditions are met:

1. Feature is enabled — notify_by_email.enabled is true (the default)
2. SMTP is configured — a valid PWP__MAIL__SMTP_ADDRESS is set
3. Logins are not disabled — PWP__DISABLE_LOGINS is not set to true

With default settings, only SMTP configuration is needed — the feature is enabled and logins are available out of the box.

The auto-dispatch input fields appear on the push creation form for signed-in users once these conditions are met.

Limits & Rate Controls

Control	Default	Description
Recipients per push	5 (lifetime)	Maximum number of email addresses across all sends for a single push.
Rate limit	5 requests/minute	Per-user rate limit on the notify-by-email action (web and API).
Daily dispatch cap	500 emails/day	Per-user daily limit on total notification emails sent. Resets at midnight.

Disabling Auto-Dispatch Entirely

To fully disable auto-dispatch (hide the UI, block API routes, reject notify_by_email params):

PWP__NOTIFY_BY_EMAIL__ENABLED=false

Or in settings.yml:

notify_by_email:
  enabled: false

When disabled, the dedicated notify_by_email routes return 404, and API push creation requests that include notify_by_email params are rejected with a 422 error. The version endpoint reports email_auto_dispatch: false.

Configuring the Daily Limit

If you want auto-dispatch available but with controlled volume, use the daily limit instead:

# Set a custom daily limit
PWP__NOTIFY_BY_EMAIL__DAILY_LIMIT=100

# Block all sends (UI still visible with a "limit reached" message)
PWP__NOTIFY_BY_EMAIL__DAILY_LIMIT=0

# Remove the cap entirely (unlimited)
# Leave the variable unset, or set to null in settings.yml

Or in settings.yml:

notify_by_email:
  enabled: true       # Feature is active
  daily_limit: 500    # Per-user daily cap (0 = block sends, null = unlimited)

Note: enabled: false fully disables the feature (UI hidden, routes removed). daily_limit: 0 blocks sends but leaves the UI visible with a “limit reached” message. Use enabled: false when you don’t want the feature at all; use daily_limit: 0 when you want to temporarily pause sends.

Using Auto-Dispatch from the Web UI

On Push Creation

1. Sign in to your OSS Password Pusher instance.
2. Create a new push (text, file, URL, or QR).
3. In the push creation form, find the “Auto-Dispatch: Send Secret Link To” field.
4. Enter one or more recipient email addresses, separated by commas.
5. Optionally select the language for the email and secret link page using the globe dropdown.
6. Submit the push.

The push is created and the email is queued for delivery in the background.

From the Preview Page

After creating a push, you can also send email notifications from the push preview page. This is useful if you forgot to add recipients during creation or need to send the link to additional people (up to the 5-recipient lifetime limit per push).

Using Auto-Dispatch from the API

On Push Creation

Include a notify_by_email object in the push creation request:

curl -X POST "https://your-instance.com/api/v2/pushes.json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "push": {
      "payload": "the-secret-content",
      "expire_after_days": 3,
      "expire_after_views": 5,
      "notify_by_email": {
        "recipients": "alice@example.com, bob@example.com",
        "locale": "fr"
      }
    }
  }'

Parameters:

Parameter	Type	Required	Description
notify_by_email.recipients	string	No	Comma-separated email addresses. Maximum 5.
notify_by_email.locale	string	No	Locale code for the email and link (e.g., en, fr, de). Defaults to the instance’s default locale.

The response includes the notify_by_email object echoed back:

{
  "url_token": "abc123...",
  "notify_by_email": {
    "recipients": "alice@example.com, bob@example.com",
    "locale": "fr"
  }
}

For Existing Pushes

Send email notifications for an already-created push:

curl -X POST "https://your-instance.com/api/v2/pushes/YOUR_URL_TOKEN/notify_by_email" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": "charlie@example.com",
    "locale": "en"
  }'

Parameters:

Parameter	Type	Required	Description
recipients	string	Yes	Comma-separated email addresses. Maximum 5 total per push (across all sends).
locale	string	No	Locale code for the email and link.

Checking Delivery Status via the Audit API

The audit log endpoint (GET /api/v2/pushes/:url_token/audit) includes email notification events:

{
  "logs": [
    {
      "kind": "creation_email_send",
      "created_at": "2026-07-04T12:00:00Z",
      "notify_by_email": {
        "recipients": "alice@example.com, bob@example.com",
        "locale": "fr",
        "status": "completed",
        "successful_sends": "alice@example.com, bob@example.com",
        "proceed_at": "2026-07-04T12:00:05Z"
      }
    }
  ]
}

Status values:

Status	Description
pending	Email is queued but not yet processed.
processing	Email delivery is in progress.
completed	All recipients received the email successfully.
partially_failed	Some recipients received the email; others failed. Check successful_sends and error_message.
failed	No emails were delivered. Check error_message.

Feature Detection via the Version API

Check whether auto-dispatch is available on a given instance:

curl "https://your-instance.com/api/v2/version"

The response includes:

{
  "features": {
    "pushes": {
      "email_auto_dispatch": true
    }
  }
}

When email_auto_dispatch is true, the instance has SMTP configured and auto-dispatch API calls will work.

Audit Logging

Every auto-dispatch action creates a creation_email_send entry in the push’s audit log. The audit log records:

• When the notification was queued
• Who it was sent to (encrypted at rest)
• Delivery status (pending → processing → completed/failed)
• Error messages if delivery failed
• Successful sends showing which recipients received the email

This provides a complete audit trail: push creation → email dispatch → each view → expiration.

Security Notes

• Signed-in users only. Anonymous users cannot use auto-dispatch. This prevents the feature from being used for spam.
• Owner-only. Only the user who created the push can send email notifications for it.
• Expired pushes. You cannot send email notifications for pushes that have already expired.
• Encrypted at rest. Recipient email addresses, locale, delivery status, and error messages are all encrypted in the database.
• Rate limited. Both per-minute (5 requests/min) and per-day (configurable cap) limits prevent abuse.

SMTP Configuration

Auto-dispatch uses your instance’s existing SMTP configuration. If you haven’t set up SMTP yet, see the SMTP configuration guide.

For high-volume use, consider a transactional email provider like SendGrid, Amazon SES, or Brevo. Gmail and Microsoft 365 personal accounts have sending limits that may be too low for production use.

See Troubleshooting Email for common SMTP issues and known-working configurations.

Environment Variables Reference

Variable	Default	Description
PWP__NOTIFY_BY_EMAIL__ENABLED	true	Set to false to fully disable auto-dispatch (hides UI, blocks API routes).
PWP__NOTIFY_BY_EMAIL__DAILY_LIMIT	500	Per-user daily cap on notification emails. 0 = block sends (UI visible), unset/null = unlimited.
PWP__MAIL__SMTP_ADDRESS	(none)	SMTP server address. Required for auto-dispatch to activate.