Email Endpoints

This document outlines the complete email system for Powersport Share, including all available email types, API endpoints, and usage examples.

📧 Email API Endpoints

1. Booking Emails (/api/email/booking)

Handles all booking-related email notifications.

Required Data:

{
  emailType: string,
  data: {
    bookingRef: string,
    cancellationReason?: string, // For cancellation emails
    claimFiledBy?: 'guest' | 'host' // For claim emails
  }
}

Available Email Types:

Booking Request

  • guestRequested - Guest requests a booking
    • Sends confirmation to guest
    • Sends notification to host

Booking Confirmation

  • hostConfirmed - Host confirms a booking request
    • Sends confirmation to guest
    • Sends confirmation to host

Booking Declined

  • hostDeclined - Host declines a booking request
    • Sends notification to guest
    • Sends confirmation to host

Booking Cancellation

  • guestCanceled - Guest cancels their booking
    • Sends confirmation to guest
    • Sends notification to host
  • hostCanceled - Host cancels a booking
    • Sends notification to guest
    • Sends confirmation to host

Pickup & Check-in

  • pickupReminder - Reminder before pickup time
    • Sends reminder to guest
    • Sends reminder to host
  • checkinTime - When rental period begins
    • Sends check-in notification to guest
    • Sends check-in notification to host

Return & Experience

  • returnReminder - Reminder before return time
    • Sends reminder to guest
    • Sends reminder to host
  • experienceFollowUp - Post-rental review request
    • Sends review request to guest
    • Sends review request to host

Claims

  • claimFiled - When a damage claim is filed
    • Sends appropriate emails based on who filed the claim
    • Requires claimFiledBy parameter

Example Usage:

// Guest requests a booking
await $fetch("/api/email/booking", {
  method: "POST",
  body: {
    emailType: "guestRequested",
    data: {
      bookingRef: "BK123456",
    },
  },
});

// Host cancels with reason
await $fetch("/api/email/booking", {
  method: "POST",
  body: {
    emailType: "hostCanceled",
    data: {
      bookingRef: "BK123456",
      cancellationReason: "Vehicle maintenance required",
    },
  },
});

2. Host Management Emails (/api/email/host)

Handles host-related notifications for vehicle documentation.

Required Data:

{
  emailType: string,
  data: {
    hostId: string,
    vehicleId: string,
    expirationDate?: string // ISO date string
  }
}

Available Email Types:

  • insuranceExpired - Vehicle insurance has expired
  • insuranceRenewal - Insurance renewal reminder
  • registrationExpired - Vehicle registration has expired
  • registrationRenewal - Registration renewal reminder

Example Usage:

await $fetch("/api/email/host", {
  method: "POST",
  body: {
    emailType: "insuranceRenewal",
    data: {
      hostId: "user123",
      vehicleId: "vehicle456",
      expirationDate: "2024-03-15T00:00:00Z",
    },
  },
});

3. Listing Management Emails (/api/email/listing)

Handles listing approval workflow notifications.

Required Data:

{
  emailType: string,
  data: {
    listingId: string,
    denialReason?: string // For denied listings
  }
}

Available Email Types:

  • listingApproved - Listing has been approved
  • listingDenied - Listing has been denied
  • listingAwaitingApproval - Listing submitted for review

Example Usage:

await $fetch("/api/email/listing", {
  method: "POST",
  body: {
    emailType: "listingDenied",
    data: {
      listingId: "listing789",
      denialReason: "Insufficient vehicle photos",
    },
  },
});

4. Communication Emails (/api/email/communication)

Handles messaging and communication notifications.

Required Data:

{
  emailType: string,
  data: {
    userId: string,
    bookingRef: string,
    messageCount?: number // Defaults to 1
  }
}

Available Email Types:

  • messageReminder - Reminds user of unread messages

Example Usage:

await $fetch("/api/email/communication", {
  method: "POST",
  body: {
    emailType: "messageReminder",
    data: {
      userId: "user123",
      bookingRef: "BK123456",
      messageCount: 3,
    },
  },
});

🏗️ Email Template Structure

All email templates follow a consistent structure:

<script setup lang="ts">
import { Text, Tailwind, Button } from "@vue-email/components";
import BaseLayout from "@/emails/layouts/BaseLayout.vue";
import BookingDetails from "@/emails/components/BookingDetails.vue";

defineProps({
  // Common props
  title: String,
  recipient: String,
  previewText: String,

  // Booking-specific props
  guestName: String,
  hostName: String,
  requestedDates: String,
  listing: String,
  vehicle: String,
  bookingUrl: String,

  // Context-specific props
  cancellationReason: String,
  // ... other props as needed
});
</script>

<template>
  <BaseLayout
    :title="title"
    :recipient="recipient"
    :previewText="previewText">
    <Tailwind>
      <!-- Email content -->
    </Tailwind>
  </BaseLayout>
</template>

🔧 Common Data Formatting

The APIs automatically format common data:

  • Dates: Formatted as "MMM dd, yyyy" (e.g., "Mar 15, 2024")
  • Names: Privacy-protected as "FirstName L." (e.g., "John D.")
  • Vehicles: Formatted as "Year Make Model" (e.g., "2023 Yamaha YZ450F")
  • URLs: Automatically include domain from environment variables

🚀 Integration Examples

Booking Workflow Integration

// When a guest requests a booking
const handleBookingRequest = async (bookingRef) => {
  try {
    // Send booking request emails
    await $fetch("/api/email/booking", {
      method: "POST",
      body: {
        emailType: "guestRequested",
        data: { bookingRef },
      },
    });

    console.log("Booking request emails sent successfully");
  } catch (error) {
    console.error("Failed to send booking emails:", error);
  }
};

// When a host confirms a booking
const handleBookingConfirmation = async (bookingRef) => {
  try {
    await $fetch("/api/email/booking", {
      method: "POST",
      body: {
        emailType: "hostConfirmed",
        data: { bookingRef },
      },
    });

    console.log("Booking confirmation emails sent successfully");
  } catch (error) {
    console.error("Failed to send confirmation emails:", error);
  }
};

📝 Error Handling

All email APIs return consistent error responses:

try {
  const result = await $fetch("/api/email/booking", {
    /* ... */
  });
  console.log("Email sent successfully:", result);
} catch (error) {
  if (error.statusCode === 400) {
    console.error("Invalid email type or missing data:", error.statusMessage);
  } else if (error.statusCode === 500) {
    console.error("Server error:", error.statusMessage);
  }
}

🔐 Environment Variables Required

Make sure these environment variables are set:

RESEND_API_KEY=your_resend_api_key
DOMAIN=https://your-domain.com

📋 Email Template Locations

emails/templates/
├── booking/
│   ├── request/          # Booking request emails
│   ├── confirmation/     # Booking confirmation emails
│   ├── declined/         # Booking declined emails
│   ├── cancellation/     # Booking cancellation emails
│   ├── pickup/           # Pickup reminder emails
│   ├── checkin/          # Check-in emails
│   ├── return/           # Return reminder emails
│   ├── experience/       # Post-rental review emails
│   └── claim/            # Damage claim emails
├── host/                 # Host management emails
├── listing/              # Listing approval emails
└── communication/        # Message reminder emails

This email system provides comprehensive coverage for all user communication needs in the Powersport Share platform.

Table of Contents