Skip to main content
Version: 1.0.0

subscriptionsEmail

Subscription Upgrade Request Template

Function Names: subscriptionUpgradeRequest / testSubscriptionUpgradeRequest

Author: Domenico Cerone Creation Date: 25/09/2025
Last Reviewer: Domenico Cerone

Trigger: HTTPS (onRequest)

Purpose: Handles subscription upgrade requests by sending personalized emails from customers to administrators. Retrieves user profile information from Profiles collection and sends templated emails using ZeptoMail to facilitate subscription upgrade communications between users.

Detailed Functionality​

1. REQUEST VALIDATION​

  • Validates presence of all required parameters: to, from, subject, description, subscriptionDetails, subscriptionName
  • Returns 400 error if any required parameter is missing
  • Validates request body contains data

2. PROFILE DATA RETRIEVAL​

  • Queries 'Profiles' collection for both sender ('from') and recipient ('to') email addresses
  • Retrieves firstName and lastName for both users
  • Handles cases where profiles don't exist (fallback to email addresses)
  • Uses parallel Promise.all for efficient data retrieval

3. NOTIFICATION PREFERENCE CHECK​

  • Checks if the sender has enabled the subscriptionsMail notification in their notification preferences
  • Verifies notification_types.subscriptionsMail field in the sender's profile
  • If notification is disabled (false): returns success without sending email
  • If notification is enabled (true): proceeds with email template preparation
  • Provides clear logging about notification preference status

4. EMAIL TEMPLATE PREPARATION​

  • Uses dedicated ZeptoMail template (MAIL_TEMPLATE_KEY: 13ef.8598f19fbcc5adb.k1.bbfeff10-5d90-11f0-9e15-dad70ff08860.197f47f3181)
  • Prepares template variables:
    • {{subject}}: Email subject line
    • {{from}}: Full name of sender (fallback to email if name unavailable)
    • {{to}}: Full name of recipient (fallback to email if name unavailable)
    • {{subscriptionName}}: Name of the subscription
    • {{subscriptionDetails}}: Detailed subscription information
    • {{description}}: Customer message/description

5. NAME RESOLUTION LOGIC​

  • Combines firstName and lastName for both sender and recipient
  • Trims whitespace and handles empty name fields
  • Falls back to email address if no name information is available
  • Ensures proper display names for email recipients

6. EMAIL SENDING WITH ZEPTOMAIL​

  • Sends email using ZeptoMail template system
  • Sets sender as "ARShades Studio <no-reply@arshades.com>"
  • Uses recipient's full name and email for proper addressing
  • Includes all template variables for dynamic content rendering

7. RESPONSE FORMATTING​

  • Returns detailed success response with user information
  • Includes both sender and recipient profile data
  • Provides ZeptoMail merge information for debugging
  • Logs all operations for monitoring and troubleshooting

8. ERROR HANDLING​

  • Comprehensive error handling for database queries
  • ZeptoMail API error management
  • Detailed error logging with context information
  • Returns structured error responses with HTTP status codes

9. CORS SUPPORT​

  • Implements CORS middleware for cross-origin requests
  • Allows frontend applications to call the function
  • Supports both development and production environments

10. TEST FUNCTION IMPLEMENTATION​

  • Separate test function for development and debugging
  • Identical logic to main function with enhanced logging
  • Enables local testing with Firebase emulators
  • Provides detailed test result information

11. LOGGING AND MONITORING​

  • Comprehensive logging at each processing stage
  • Logs sender/recipient information and subscription details
  • Tracks email sending success and failure scenarios
  • Provides debugging information for troubleshooting

Input (Payload)​

Method: POST

Headers:

  • Content-Type: application/json

Body:

{
  "to": "carmine.bonavoglia@spaarkly.com",
  "from": "92mt@live.it",
  "subject": "Richiesta Upgrade Sottoscrizione ARShades Pro",
  "description": "Vorrei richiedere un upgrade della mia sottoscrizione per accedere a funzionalità avanzate",
  "subscriptionDetails": "Upgrade da Basic a Pro - Include analytics avanzate e supporto prioritario",
  "subscriptionName": "ARShades Pro"
}

Parameters:

  • to (string, required): Recipient email address
  • from (string, required): Sender email address
  • subject (string, required): Email subject line
  • description (string, required): Customer message/description
  • subscriptionDetails (string, required): Detailed subscription information
  • subscriptionName (string, required): Name of the subscription

Output (Success)​

{
  "success": true,
  "message": "Richiesta di upgrade sottoscrizione inviata con successo",
  "details": {
    "to": {
      "email": "carmine.bonavoglia@spaarkly.com",
      "firstName": "Carmine",
      "lastName": "Bonavoglia"
    },
    "from": {
      "email": "92mt@live.it",
      "firstName": "Michele",
      "lastName": "Telesca"
    },
    "subscriptionName": "ARShades Pro"
  },
  "zeptomail_merge_info": {
    "subject": "Richiesta Upgrade Sottoscrizione ARShades Pro",
    "from": "Michele Telesca",
    "to": "Carmine Bonavoglia",
    "subscriptionName": "ARShades Pro",
    "subscriptionDetails": "Upgrade da Basic a Pro - Include analytics avanzate e supporto prioritario",
    "description": "Vorrei richiedere un upgrade della mia sottoscrizione per accedere a funzionalità avanzate"
  }
}

Response Properties:

  • success (boolean): Indicates if the operation was completed successfully
  • message (string): Descriptive message about the operation result
  • details (object): Contains sender and recipient information with resolved names
  • to (object): Recipient information including email and resolved name
  • from (object): Sender information including email and resolved name
  • subscriptionName (string): Name of the subscription being requested
  • zeptomail_merge_info (object): Template variables sent to ZeptoMail for debugging

Testing​

URL (if HTTPS): http://127.0.0.1:5001/arshadesstaging/europe-central2/testSubscriptionUpgradeRequest

Test con Emulator:

  1. Avviare l'emulatore Firebase: firebase emulators:start --only functions
  2. Assicurarsi di usare Node.js versione 20: nvm use 20
  3. Testare con curl:
curl -X POST "http://127.0.0.1:5001/arshadesstaging/europe-central2/testSubscriptionUpgradeRequest" \
-H "Content-Type: application/json" \
-d '{
  "to": "carmine.bonavoglia@spaarkly.com",
  "from": "92mt@live.it",
  "subject": "Richiesta Upgrade Sottoscrizione ARShades Pro",
  "description": "Vorrei richiedere un upgrade della mia sottoscrizione",
  "subscriptionDetails": "Upgrade da Basic a Pro",
  "subscriptionName": "ARShades Pro"
}'

Postman Testing:

  • Metodo: POST
  • URL: http://127.0.0.1:5001/arshadesstaging/europe-central2/testSubscriptionUpgradeRequest
  • Headers:
    • Key: Content-Type
    • Value: application/json
  • Body: raw JSON (vedi esempi sopra)

Deploy Command​

firebase deploy --only functions:subscriptionUpgradeRequest,functions:testSubscriptionUpgradeRequest

Production URL​

subscriptionUpgradeRequest: https://europe-central2-arshades-7e18a.cloudfunctions.net/subscriptionUpgradeRequest

testSubscriptionUpgradeRequest: Not deployed to production (test function only)