Scheduling, batches, and attachments

​

Goal

​

Prerequisites

• A StackShift API key
• A verified sender domain
• StackShift Assets uploaded when using asset-backed attachments

​

Workflow

​

Scheduled messages

const scheduled = await stackshift.mail.scheduled.create({
  sendAt: '2026-05-12T09:00:00Z',
  message: {
    from: 'noreply@example.com',
    to: 'ada@example.net',
    subject: 'Renewal reminder',
    text: 'Your renewal is coming up.',
    idempotencyKey: 'renewal_ada_2026_05_12',
  },
})

await stackshift.mail.scheduled.cancel(scheduled.id)

​

Batch template sends

const batch = await stackshift.mail.batch.sendTemplate({
  template: 'weekly-report',
  from: 'reports@example.com',
  recipients: [
    { to: 'ada@example.net', data: { firstName: 'Ada' }, idempotencyKey: 'weekly_ada_2026_19' },
    { to: 'grace@example.net', data: { firstName: 'Grace' }, idempotencyKey: 'weekly_grace_2026_19' },
  ],
})

console.log(batch.id, batch.status, batch.messageCount)

​

Attachments

• MailSendInput, MailSendTemplateInput, and scheduled/template workflows accept attachments.
• Attachment input supports assetId or uploadId, filename, and optional contentType.
• Use StackShift Assets for files you want to attach by assetId.

​

API endpoints

• Scheduled: POST /mail/scheduled, GET /mail/scheduled, GET /mail/scheduled/{scheduledId}, DELETE or POST /mail/scheduled/{scheduledId}/cancel.
• Batch: POST /mail/batch, POST /mail/batch-template, GET /mail/batches, GET /mail/batches/{batchId}, GET /mail/batches/{batchId}/items.

​

Expected result

​

Common failures

​

Related guides