Skip to main content

Email Notifications

What it is​

Automated email notifications sent to workspace owners for important events and system alerts using SendGrid.

Who it's for​

Workspace Owner

Access & Scope​

PropertyValue
Moduleemail-notifications
Personasworkspace-owner
ScopeWorkspace-level
UI LocationAutomated (sent via email)

| Status | active |

UI Location​

Email notifications are sent directly to the workspace owner's email address. No UI configuration is required.

How it works​

The Email Notifications feature automatically sends email alerts to workspace owners when important events occur. Here's how it works:

  1. Automatic Triggers:

    • System automatically detects events that require notification
    • Emails are sent asynchronously (non-blocking)
    • Notifications are sent to the workspace owner's registered email

  2. Notification Types:

    • New Order: Sent when a new storefront order is received
    • SMS Balance Warnings: Sent when SMS balance reaches $10 or $2 thresholds
    • AI Balance Warnings: Sent when AI balance reaches $10 or $2 thresholds
    • Storage Quota Warnings: Sent when storage usage reaches 80% or 95% of quota
    • Registration Welcome: Sent after successful workspace registration
    • Failed Login: Sent when a failed login attempt is detected

  3. Rate Limiting:

    • Balance and quota warnings have 24-hour cooldown periods
    • Prevents email spam for the same threshold
    • Each threshold is tracked separately

  4. Email Delivery:

    • Uses SendGrid for reliable email delivery
    • Professional HTML email templates
    • Plain text fallback for email clients that don't support HTML
    • Responsive design for mobile devices

Notification Details​

New Order Notification​

Trigger: When a new storefront order is created

Content:

  • Order code (public ID)
  • Order date and time
  • Number of items
  • Total order amount
  • Customer name and phone
  • Link to view order details

Frequency: Every new order

SMS Balance Warnings​

Triggers:

  • When SMS balance reaches $10 (first warning)
  • When SMS balance reaches $2 (critical warning)

Content:

  • Current SMS balance
  • Threshold reached
  • Estimated remaining messages
  • Link to add SMS credits

Frequency: Once per threshold per 24 hours

AI Balance Warnings​

Triggers:

  • When AI balance reaches $10 (first warning)
  • When AI balance reaches $2 (critical warning)

Content:

  • Current AI balance
  • Threshold reached
  • Estimated remaining usage
  • Link to add AI credits

Frequency: Once per threshold per 24 hours

Storage Quota Warnings​

Triggers:

  • When storage usage reaches 80% of quota (first warning)
  • When storage usage reaches 95% of quota (critical warning)

Content:

  • Current storage usage (MB)
  • Maximum quota (MB)
  • Percentage used
  • Remaining storage (MB)
  • Link to manage storage

Frequency: Once per threshold per 24 hours

Registration Welcome Email​

Trigger: After successful workspace registration

Content:

  • Welcome message
  • Workspace name
  • Email address
  • Selected plan name
  • Getting started guide
  • Link to dashboard

Frequency: Once per registration

Failed Login Notification​

Trigger: When a login attempt fails (workspace exists)

Content:

  • Security alert
  • Email address that attempted login
  • Timestamp of attempt
  • IP address (if available)
  • Security recommendations
  • Link to reset password

Frequency: Every failed login attempt

Security Note: Only sent if workspace exists (doesn't reveal if email exists in system)

Settings​

Email notifications are automatically configured and require no user setup. However, the following applies:

  1. Email Address:

    • Notifications are sent to the workspace owner's registered email
    • Email address is set during workspace registration
    • Can be updated in workspace settings

  2. Notification Preferences:

    • All notifications are enabled by default
    • Notifications cannot be disabled (critical for security and operations)
    • Rate limiting prevents email spam

  3. Email Templates:

    • Professional HTML templates with Placio branding
    • Responsive design for all devices
    • Consistent styling across all notification types

Permissions​

Email notifications are sent to:

  • Workspace Owner: Receives all email notifications
  • Staff: Do not receive email notifications (only workspace owner)

Note: Email notifications contain sensitive information about workspace operations, orders, and security events. They are only sent to the workspace owner's registered email address.

Use Cases​

  1. Order Management:

    • Get notified immediately when new orders arrive
    • Never miss a customer order
    • Quick access to order details via email link

  2. Balance Management:

    • Stay informed about SMS and AI balance levels
    • Prevent service interruption by adding credits
    • Plan budget based on usage warnings

  3. Storage Management:

    • Monitor storage usage proactively
    • Clean up files before reaching quota limit
    • Upgrade plan if needed

  4. Security Monitoring:

    • Get alerted about failed login attempts
    • Take immediate action if account is compromised
    • Maintain account security awareness

  5. Onboarding:

    • Receive welcome email after registration
    • Get started with helpful links and information
    • Understand your plan and features

  6. Operational Awareness:

    • Stay informed about workspace activities
    • Monitor system health and quotas
    • Take proactive actions when needed

Notes / Limits​

  1. Email Delivery:

    • Emails are sent asynchronously (non-blocking)
    • Email failures don't block main operations
    • Delivery is handled by SendGrid service
    • Check spam folder if emails are not received

  2. Rate Limiting:

    • Balance warnings: Once per threshold per 24 hours
    • Storage warnings: Once per threshold per 24 hours
    • Order notifications: Every order (no limit)
    • Failed login: Every attempt (no limit)
    • Registration: Once per registration

  3. Email Format:

    • HTML emails with professional design
    • Plain text fallback included
    • Responsive for mobile devices
    • Placio branding included

  4. Template Customization:

    • Templates are managed in SendGrid
    • Template IDs are configured in system
    • Logo and branding can be updated in templates

  5. Email Address:

    • Must be a valid email address
    • Should be regularly checked
    • Can be updated in workspace settings
    • Used for all notifications

  6. Error Handling:

    • Email failures are logged but don't block operations
    • System continues to function if email service is unavailable
    • Failed emails are logged for debugging

  7. Privacy:

    • Email addresses are not shared
    • Notifications contain only workspace-specific information
    • Security best practices are followed

  8. SendGrid Configuration:

    • Requires SendGrid API key in environment variables
    • Templates must be created in SendGrid dashboard
    • Template IDs must be configured in system

Configuration​

Email notifications are configured at the system level:

  1. Environment Variables:

    • SENDGRID_API_KEY: SendGrid API key for email sending

  2. Template IDs:

    • Each notification type has a SendGrid template ID
    • Template IDs are configured in email-templates.ts
    • Templates must be created in SendGrid dashboard

  3. Sender Information:

    • From email: service@placio.app (configurable)
    • From name: Placio

Changelog​

Current Version​

  • Initial email notification system implementation
  • Support for 6 notification types
  • Rate limiting for balance and quota warnings
  • Professional HTML email templates
  • SendGrid integration
  • Automatic workspace owner email detection