Overview The sendEmail utility provides a high-level server-side function for sending emails through the Lettermint API. It abstracts the fluent email builder API and provides a simple object-based interface.
This function can only be used in server contexts such as API routes, server middleware, or Nitro plugins.
Signature async function sendEmail ( options : SendEmailOptions ) : Promise < any >
Parameters The function accepts a single options object with the following properties:
The sender’s email address. to
string | string[]
required
The recipient’s email address or an array of recipient addresses. The email subject line. subject : 'Welcome to our service'
Plain text content of the email. text : 'Thank you for signing up!'
HTML content of the email. If both text and html are provided, email clients will display the HTML version with text as a fallback. html : '<h1>Welcome!</h1><p>Thank you for signing up!</p>'
Carbon copy recipient(s). Blind carbon copy recipient(s). Custom email headers as key-value pairs. headers : { 'X-Custom-Header' : 'value' , 'X-Priority' : 'high' }
Custom metadata to attach to the email for tracking purposes. metadata : { userId : '12345' , campaign : 'welcome-series' }
Tags to categorize and filter emails. tags : [ 'welcome' , 'onboarding' ]
attachments
Array<{ filename: string, content: string | Buffer, contentType?: string }>
File attachments to include with the email. The name of the file as it will appear to recipients.
The file content as a base64 string or Buffer.
The MIME type of the file (e.g., ‘application/pdf’, ‘image/png’).
attachments : [ { filename: 'invoice.pdf' , content: pdfBuffer , contentType: 'application/pdf' } ]
Return Value Returns a promise that resolves to the Lettermint API response. The exact shape depends on the Lettermint SDK, but typically includes a message ID and status.
Usage Examples API Route
With Multiple Recipients
With Attachments
In Nitro Plugin
// server/api/welcome.post.ts export default defineEventHandler ( async ( event ) => { const body = await readBody ( event ) const result = await sendEmail ({ from: '[email protected] ' , to: body . email , subject: 'Welcome to our service!' , html: ` <h1>Welcome, ${ body . name } !</h1> <p>Thank you for signing up.</p> ` }) return { success: true , messageId: result . message_id } } )
// server/api/send-invoice.post.ts import fs from 'fs' export default defineEventHandler ( async ( event ) => { const { email , invoiceId } = await readBody ( event ) // Generate or read PDF const pdfBuffer = fs . readFileSync ( `./invoices/ ${ invoiceId } .pdf` ) await sendEmail ({ from: '[email protected] ' , to: email , subject: `Invoice # ${ invoiceId } ` , html: '<p>Please find your invoice attached.</p>' , attachments: [ { filename: `invoice- ${ invoiceId } .pdf` , content: pdfBuffer , contentType: 'application/pdf' } ], metadata: { invoiceId , type: 'invoice' }, tags: [ 'invoice' , 'billing' ] }) return { success: true } } )
// server/plugins/welcome-email.ts export default defineNitroPlugin (( nitroApp ) => { nitroApp . hooks . hook ( 'user:registered' , async ( user ) => { await sendEmail ({ from: '[email protected] ' , to: user . email , subject: 'Welcome!' , html: `<h1>Welcome, ${ user . name } !</h1>` , metadata: { userId: user . id , event: 'registration' }, tags: [ 'welcome' , 'onboarding' ] }) }) } )
Type Definition export interface SendEmailOptions { from : string to : string | string [] subject : string text ?: string html ?: string cc ?: string | string [] bcc ?: string | string [] replyTo ?: string | string [] headers ?: Record < string , string > metadata ?: Record < string , unknown > tags ?: string [] attachments ?: Array <{ filename : string content : string | Buffer contentType ?: string }> } export async function sendEmail ( options : SendEmailOptions ) : Promise < any >
How It Works The sendEmail function:
Retrieves the Lettermint SDK instance using useLettermint()
Uses the fluent email builder API to construct the email
Handles array values for recipients (to, cc, bcc, replyTo)
Converts Buffer attachments to base64 strings
Sends the email and returns the result
Error Handling try { const result = await sendEmail ({ from: '[email protected] ' , to: '[email protected] ' , subject: 'Test' , html: '<p>Test email</p>' }) console . log ( 'Email sent:' , result . message_id ) } catch ( error ) { console . error ( 'Failed to send email:' , error ) throw createError ({ statusCode: 500 , message: 'Failed to send email' }) }