Events, webhooks, and timelines

​

Goal

​

Prerequisites

• A public HTTPS webhook endpoint
• Storage for webhook endpoint secret values
• An idempotent event handler

​

Workflow

​

Event types

• Message events: mail.message.accepted, mail.message.queued, mail.message.sending, mail.message.mta_accepted, mail.delivery.delayed, mail.delivery.delivered, mail.message.bounced, mail.message.failed, mail.message.suppressed, and mail.message.complained.
• Suppression events: mail.suppression.created and mail.suppression.deleted.
• OTP events: mail.otp.created, mail.otp.sent, mail.otp.verified, mail.otp.failed_attempt, mail.otp.failed, mail.otp.expired, and mail.otp.canceled.
• Template events: mail.template.created, mail.template.updated, mail.template.deleted, mail.template.version.created, and mail.template.test_queued.
• Domain events: mail.domain.created, mail.domain.verified, mail.domain.failed, and mail.domain.deleted.
• Webhook events: mail.webhook.created, mail.webhook.updated, mail.webhook.disabled, mail.webhook.delivery.succeeded, and mail.webhook.delivery.failed.
• Operations events: mail.scheduled.created, mail.scheduled.canceled, mail.scheduled.dispatched, mail.scheduled.failed, mail.batch.created, mail.batch.completed, and mail.batch.failed.
• Audience and campaign events: mail.audience.created, mail.audience.members.imported, mail.campaign.created, and mail.campaign.queued.
• Inbound events: mail.inbound.domain.created, mail.inbound.domain.verified, mail.inbound.domain.routing_paused, mail.inbound.received, mail.inbound.quarantined, mail.inbound.failed, and mail.message.replied.
• Reputation events include workspace/domain watch, throttled, and disabled states; limit changes; recipient-domain throttling; and manual-review outcomes.

​

Create a webhook

const webhook = await stackshift.mail.webhooks.create({
  url: 'https://example.com/webhooks/stackshift-mail',
  description: 'Production mail lifecycle events',
  eventTypes: [
    'mail.message.mta_accepted',
    'mail.delivery.delayed',
    'mail.delivery.delivered',
    'mail.message.bounced',
    'mail.otp.verified',
  ],
})

// Store webhook.secret now. It is only returned on create or rotate.
console.log(webhook.id, webhook.secret)

​

Verify a signature

import { verifyWebhookSignature } from '@stackshift-cloud/sdk'

const valid = verifyWebhookSignature({
  rawBody,
  signatureHeader: request.headers.get('StackShift-Signature'),
  timestampHeader: request.headers.get('StackShift-Timestamp'),
  secret: process.env.STACKSHIFT_MAIL_WEBHOOK_SECRET!,
  toleranceSeconds: 300,
})

if (!valid) throw new Error('Invalid StackShift Mail webhook signature')

​

Operational APIs

• GET /mail/events filters by type, resourceType, resourceId, messageId, from, to, limit, and cursor.
• GET /mail/messages/{id}/timeline returns timeline items with type, label, createdAt, and optional metadata.
• GET /mail/webhooks/{webhookId}/deliveries filters webhook deliveries by status, limit, and cursor.
• GET /mail/webhook-deliveries/{deliveryId} includes delivery attempts.
• POST /mail/webhook-deliveries/{deliveryId}/retry requests a retry for a delivery.

​

Expected result

​

Common failures

​

Related guides