Overview
The useLettermint composable provides a convenient way to send emails from your Nuxt application’s client-side code. It returns reactive state and a send method that handles API communication with the Lettermint service.
Signature
function useLettermint(): UseLettermintReturn
Return Value
The composable returns an object with the following properties and methods:
send
(options: LettermintEmailOptions) => Promise<LettermintResponse>
required
Async function to send an email. Returns a promise that resolves to a response object.
Reactive boolean indicating whether an email is currently being sent.
error
Ref<string | null>
required
Reactive string containing the last error message, or null if no error occurred.
lastMessageId
Ref<string | null>
required
Reactive string containing the message ID of the last successfully sent email, or null if no email has been sent yet.
Email Options
LettermintEmailOptions
The send method accepts an options object with the following parameters:
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.attachments: [
{
filename: 'invoice.pdf',
content: base64String,
contentType: 'application/pdf'
}
]
Response Type
LettermintResponse
The send method returns a promise that resolves to:
Indicates whether the email was sent successfully.
Unique identifier for the sent message. Only present on successful sends.
The status of the email (e.g., ‘pending’, ‘sent’).
Error message if the send failed. Only present when success is false.
Usage Example
Basic Usage
With Attachments
With Metadata
Reactive State
<script setup>
const { send, sending, error, lastMessageId } = useLettermint()
const sendWelcomeEmail = async () => {
const response = await send({
from: '[email protected]',
to: '[email protected]',
subject: 'Welcome!',
html: '<h1>Welcome to our service!</h1>'
})
if (response.success) {
console.log('Email sent:', response.messageId)
}
}
</script>
<template>
<div>
<button @click="sendWelcomeEmail" :disabled="sending">
{{ sending ? 'Sending...' : 'Send Email' }}
</button>
<p v-if="error" class="error">{{ error }}</p>
<p v-if="lastMessageId">Last message ID: {{ lastMessageId }}</p>
</div>
</template>
<script setup>
const { send } = useLettermint()
const sendInvoice = async (invoiceData: string) => {
await send({
from: '[email protected]',
to: '[email protected]',
subject: 'Your Invoice',
html: '<p>Please find your invoice attached.</p>',
attachments: [
{
filename: 'invoice.pdf',
content: invoiceData, // base64 string or Buffer
contentType: 'application/pdf'
}
],
tags: ['invoice', 'billing']
})
}
</script>
<script setup>
const { send } = useLettermint()
const sendCampaignEmail = async (userId: string) => {
await send({
from: '[email protected]',
to: '[email protected]',
subject: 'Special Offer',
html: '<p>Check out our special offer!</p>',
metadata: {
userId,
campaign: 'summer-2024',
segment: 'premium'
},
tags: ['campaign', 'promotional']
})
}
</script>
<script setup>
const { send, sending, error, lastMessageId } = useLettermint()
// Watch for changes
watch(sending, (isSending) => {
console.log('Sending status:', isSending)
})
watch(error, (err) => {
if (err) {
console.error('Email error:', err)
}
})
watch(lastMessageId, (msgId) => {
if (msgId) {
console.log('New message sent:', msgId)
}
})
</script>
Type Definitions
export interface LettermintEmailOptions {
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 interface LettermintResponse {
success: boolean
messageId?: string
status?: string
error?: string
}
export interface UseLettermintReturn {
send: (options: LettermintEmailOptions) => Promise<LettermintResponse>
sending: Ref<boolean>
error: Ref<string | null>
lastMessageId: Ref<string | null>
}
Notes
This composable is designed for client-side use only. For server-side email sending, use the sendEmail utility function. The composable makes requests to /api/lettermint/send. Ensure the Lettermint module is properly configured with a valid API key.