Stack0
Dashboard

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:

OptionTypeDescription
fromstringSender email address (required)
tostring | string[]Recipient(s) (required)
subjectstringEmail subject line (required)
htmlstringHTML content
textstringPlain text fallback
replyTostringReply-to address
ccstring | string[]CC recipients
bccstring | string[]BCC recipients
templateIdstringTemplate ID to use
templateVariablesobjectVariables for template
scheduledAtDateSchedule 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
await stack0.mail.cancel('email_xxx')

Email Sub-Clients

The mail client provides sub-clients for managing the full email platform:

mail.domains

Manage sending domains with DNS verification

mail.templates

Create reusable email templates with variables

mail.audiences

Organize contacts into targeted lists

mail.contacts

Manage contacts with metadata and status

mail.campaigns

Create and send email campaigns to audiences

mail.sequences

Build automated email sequences with triggers

mail.events

Track custom events to trigger sequences

sub-clients.ts
// Domains
await stack0.mail.domains.add({ domain: 'yourdomain.com' })
await stack0.mail.domains.verify('domain_id')
 
// Templates
const template = await stack0.mail.templates.create({
  name: 'Welcome Email',
  slug: 'welcome',
  subject: 'Welcome {{name}}!',
  html: '<h1>Hi {{name}}</h1>',
})
 
// Contacts & Audiences
const audience = await stack0.mail.audiences.create({ name: 'Newsletter' })
const contact = await stack0.mail.contacts.create({ email: 'user@example.com' })
await stack0.mail.audiences.addContacts({ id: audience.id, contactIds: [contact.id] })
 
// Campaigns
const campaign = await stack0.mail.campaigns.create({
  name: 'Product Launch',
  fromEmail: 'news@yourdomain.com',
  audienceId: audience.id,
  templateId: template.id,
})
await stack0.mail.campaigns.send({ id: campaign.id, sendNow: true })
 
// Sequences
const sequence = await stack0.mail.sequences.create({
  name: 'Onboarding',
  triggerType: 'event_received',
  triggerConfig: { eventName: 'user_signup' },
})
await stack0.mail.sequences.publish(sequence.id)
 
// Events (trigger sequences)
await stack0.mail.events.track({
  eventName: 'user_signup',
  contactEmail: 'newuser@example.com',
  properties: { plan: 'pro' },
})

Related

React Email TemplatesEmail API ReferenceError Handling