Sending Emails

Complete guide to sending emails with the Stack0 SDK, including templates, batch sending, and broadcasts.

Basic Email

Send a simple email with HTML content:

send-email.ts

import { Stack0 } from '@stack0/sdk'
 
const stack0 = new Stack0({
  apiKey: process.env.STACK0_API_KEY!
})
 
const result = await stack0.mail.send({
  from: 'you@yourdomain.com',
  to: 'recipient@example.com',
  subject: 'Hello from Stack0!',
  html: '<h1>Welcome!</h1><p>This is your first email.</p>',
})
 
console.log('Email ID:', result.id)

Email Options

Full list of options for the send method:

Option	Type	Description
from	string	Sender email address (required)
to	string \| string[]	Recipient(s) (required)
subject	string	Email subject line (required)
html	string	HTML content
text	string	Plain text fallback
replyTo	string	Reply-to address
cc	string \| string[]	CC recipients
bcc	string \| string[]	BCC recipients
templateId	string	Template ID to use
templateVariables	object	Variables for template
scheduledAt	Date	Schedule send time

Using Templates

Send emails using predefined templates with dynamic variables:

template-example.ts

await stack0.mail.send({
  from: 'orders@yourdomain.com',
  to: 'customer@example.com',
  subject: 'Your order has shipped!',
  templateId: 'order-shipped',
  templateVariables: {
    customerName: 'John',
    orderNumber: 'ORD-12345',
    trackingNumber: '1Z999AA10123456784',
    trackingUrl: 'https://tracking.example.com/...',
    items: [
      { name: 'Product A', quantity: 2 },
      { name: 'Product B', quantity: 1 },
    ],
  },
})

Batch Sending

Send multiple emails with different content in a single API call:

batch-send.ts

const result = await stack0.mail.sendBatch({
  emails: [
    {
      from: 'noreply@yourdomain.com',
      to: 'user1@example.com',
      subject: 'Hello User 1',
      html: '<p>Personal message for user 1</p>',
    },
    {
      from: 'noreply@yourdomain.com',
      to: 'user2@example.com',
      subject: 'Hello User 2',
      html: '<p>Personal message for user 2</p>',
    },
    {
      from: 'noreply@yourdomain.com',
      to: 'user3@example.com',
      subject: 'Hello User 3',
      html: '<p>Personal message for user 3</p>',
    },
  ],
})
 
console.log(`Sent ${result.data.length} emails`)

Tip: Batch sending is ideal when each recipient needs different content. For the same content to multiple recipients, use broadcast instead.

Broadcast

Send the same email to multiple recipients efficiently:

broadcast.ts

const result = await stack0.mail.sendBroadcast({
  from: 'newsletter@yourdomain.com',
  to: [
    'subscriber1@example.com',
    'subscriber2@example.com',
    'subscriber3@example.com',
    // ... up to 1000 recipients per call
  ],
  subject: 'Weekly Newsletter - December Edition',
  html: `
    <h1>This week in tech</h1>
    <p>Here are the latest updates...</p>
  `,
})
 
console.log('Broadcast sent to', result.recipientCount, 'recipients')

Scheduled Emails

Schedule emails to be sent at a specific time:

scheduled-email.ts

// Schedule for tomorrow at 9am
const tomorrow = new Date()
tomorrow.setDate(tomorrow.getDate() + 1)
tomorrow.setHours(9, 0, 0, 0)
 
const result = await stack0.mail.send({
  from: 'reminders@yourdomain.com',
  to: 'user@example.com',
  subject: 'Your daily digest',
  html: '<p>Here is your daily summary...</p>',
  scheduledAt: tomorrow,
})
 
console.log('Email scheduled for:', result.scheduledAt)

Get Email Status

Check the delivery status of a sent email:

get-status.ts

const email = await stack0.mail.get({ id: 'email_xxx' })
 
console.log('Status:', email.status)
// 'queued' | 'sending' | 'sent' | 'delivered' | 'bounced' | 'failed'
 
console.log('Delivered at:', email.deliveredAt)
console.log('Opened at:', email.openedAt)
console.log('Clicked at:', email.clickedAt)

List Emails

Query and filter sent emails:

list-emails.ts

const { emails, total, hasMore } = await stack0.mail.list({
  status: 'delivered',
  from: 'noreply@yourdomain.com',
  limit: 50,
  offset: 0,
})
 
console.log(`Found ${total} delivered emails`)
 
for (const email of emails) {
  console.log(`- ${email.to}: ${email.subject}`)
}

Cancel Scheduled Email

Cancel a scheduled email before it's sent:

cancel-email.ts

const result = await stack0.mail.cancel({ id: 'email_xxx' })
 
if (result.success) {
  console.log('Email cancelled successfully')
} else {
  console.log('Could not cancel - email may have already been sent')
}

React Email Templates Email API Reference Error Handling