StackShift Mail API

Mail delivery and simulation, brands, consent-aware audiences, campaigns, engagement, domain audit, prepaid summaries, inbound messages and signed events. Base URL: https://api.stackshift.cloud/v1 Authentication: Mail credentials select Live/Test; mail:send submits individual mail and mail:manage manages resources/campaigns. Public audit, migration-plan and migration-guides use https://api.stackshift.cloud/api/v1 with no authentication. Other Mail operations use the base URL above. Billing mutations require a signed-in billing owner and are described in the spending guide, not server-key SDK operations. Successful Mail responses are raw JSON, not a success/data envelope. SDK-backed operations are traced to official source files in the coverage report. Routes without an SDK wrapper are explicitly marked contract-only.

Method	SDK route	SDK method	Request type	Response type
`GET`	`/mail/billing`	`MailBillingClient.summary`	`None`	`MailBillingSummary`
`GET`	`/mail/analytics`	`MailAnalyticsClient.get`	`None`	`MailAnalytics`
`POST`	`/mail/brands`	`MailBrandsClient.create`	`MailBrandFields`	`MailBrand`
`POST`	`/mail/audiences`	`MailAudiencesClient.create`	`{ brandId: string; name: string; description?: string; }`	`MailAudience`
`POST`	`/mail/campaigns`	`MailCampaignsClient.create`	`MailCampaignInput`	`MailCampaign`
`POST`	`/mail/automations`	`MailAutomationsClient.create`	`MailAutomationInput`	`MailAutomation`
`POST`	`/mail/forms`	`MailFormsClient.create`	`MailSignupFormInput`	`MailSignupForm`
`POST`	`/mail/segments`	`MailSegmentsClient.create`	`MailSegmentInput`	`MailSegment`
`POST`	`/mail/audiences/{id}/imports`	`MailAudiencesClient.importDetailed`	`{ members: MailAudienceMemberImport[]; mode?: MailImportMode; }`	`MailImportResult`
`GET`	`/mail/audit`	`MailMigrationClient.audit`	`None`	`Record<string, unknown>`
`GET`	`/mail/migration-plan`	`MailMigrationClient.plan`	`None`	`Record<string, unknown>`
`GET`	`/mail/migration-guides`	`Contract-only (no SDK wrapper)`	`None`	`SDK response type`
`GET`	`/mail/migration/checklist`	`MailMigrationClient.checklist`	`None`	`MailMigrationChecklist`
`PUT`	`/mail/migration/checklist`	`MailMigrationClient.saveChecklist`	`{ domain: string; provider: string; completed: string[]; revision: number; }`	`MailMigrationChecklist`
`POST`	`/mail/send`	`MailClient.send`	`MailSendInput`	`MailSendResponse`
`POST`	`/mail/streams`	`MailStreamsClient.create`	`MailMessageStreamCreateInput`	`MailMessageStream`
`POST`	`/mail/tracking/domains`	`MailTrackingClient.createDomain`	`{ domainId: string; hostname: string; }`	`MailTrackingDomain`
`POST`	`/mail/campaigns/{id}/send`	`MailCampaignsClient.send`	`{ revision?: number; approvedMaxKobo?: number; }`	`MailCampaign`
`POST`	`/mail/campaigns/{id}/schedule`	`MailCampaignsClient.schedule`	`{ sendAt: string; revision?: number; approvedMaxKobo?: number; }`	`MailCampaign`
`POST`	`/mail/exports`	`MailExportsClient.create`	`MailExportCreateInput`	`MailExport`
`POST`	`/mail/scheduled`	`MailScheduledClient.create`	`MailScheduledCreateInput`	`MailScheduledMessage`
`POST`	`/mail/batch`	`MailBatchClient.send`	`MailBatchSendInput`	`MailBatch`
`POST`	`/mail/batch-template`	`MailBatchClient.sendTemplate`	`MailBatchTemplateInput`	`MailBatch`
`POST`	`/mail/inbound/domains`	`MailInboundDomainsClient.create`	`{ domain: string; }`	`MailInboundDomain`
`POST`	`/mail/templates`	`MailTemplatesClient.create`	`MailTemplateCreateInput`	`MailTemplate`
`POST`	`/mail/templates/{templateId}/test-send`	`MailTemplatesClient.testSend`	`MailTemplateTestSendInput`	`MailTemplateTestSendResponse`
`POST`	`/mail/domains`	`MailDomainsClient.create`	`{ domain: string; }`	`MailDomain`
`POST`	`/mail/suppressions`	`MailSuppressionsClient.create`	`MailSuppressionCreateInput`	`MailSuppression`
`POST`	`/mail/webhooks`	`MailWebhooksClient.create`	`MailWebhookCreateInput`	`MailWebhookCreateResponse`
`POST`	`/mail/webhooks/{webhookId}/replay`	`MailWebhooksClient.replay`	`{ eventIds: string[]; }`	`MailWebhookReplay`
`POST`	`/mail/webhook-deliveries/{deliveryId}/retry`	`MailWebhooksClient.retryDelivery`	`None`	`MailWebhookDelivery`
`POST`	`/mail/campaigns/{id}/test`	`MailCampaignsClient.test`	`{ to: string; data?: Record<string, unknown>; variant?: string; simulation?: MailSimulationOptions; }`	`{ id: string; status: string; mode: 'live' \| 'test' }`
`POST`	`/mail/send-template`	`MailClient.sendTemplate`	`MailSendTemplateInput`	`MailSendTemplateResponse`
`GET`	`/mail/limits`	`MailLimitsClient.get`	`None`	`MailLimits`
`GET`	`/mail/reputation`	`MailReputationClient.get`	`None`	`MailReputation`
`GET`	`/mail/reputation/events`	`MailReputationEventsClient.list`	`None`	`MailReputationEventListResult`
`GET`	`/mail/templates`	`MailTemplatesClient.list`	`None`	`MailTemplateListResult`
`GET`	`/mail/templates/{templateIdOrSlug}`	`MailTemplatesClient.get`	`None`	`MailTemplateDetail`
`PATCH`	`/mail/templates/{templateId}`	`MailTemplatesClient.update`	`MailTemplateUpdateInput`	`MailTemplate`
`DELETE`	`/mail/templates/{templateId}`	`MailTemplatesClient.delete`	`None`	`void`
`GET`	`/mail/templates/{templateId}/versions`	`MailTemplatesClient.versions`	`None`	`{ data: MailTemplateVersion[] }`
`GET`	`/mail/templates/{templateId}/versions/{versionId}`	`MailTemplatesClient.getVersion`	`None`	`MailTemplateVersion`
`POST`	`/mail/templates/{templateId}/versions/{versionId}/activate`	`MailTemplatesClient.activateVersion`	`None`	`MailTemplate`
`POST`	`/mail/templates/{templateId}/preview`	`MailTemplatesClient.preview`	`MailTemplatePreviewInput`	`MailTemplatePreview`
`POST`	`/mail/templates/{templateId}/diagnostics`	`MailTemplatesClient.diagnostics`	`MailTemplateDiagnosticInput`	`MailTemplateDiagnosticResult`
`GET`	`/mail/domains`	`MailDomainsClient.list`	`None`	`MailDomainListResult`
`GET`	`/mail/domains/{domainId}`	`MailDomainsClient.get`	`None`	`MailDomain`
`POST`	`/mail/domains/{domainId}/verify`	`MailDomainsClient.verify`	`None`	`MailDomain`
`DELETE`	`/mail/domains/{domainId}`	`MailDomainsClient.delete`	`None`	`void`
`GET`	`/mail/messages`	`MailMessagesClient.list`	`None`	`MailMessageListResult`
`GET`	`/mail/messages/{messageId}`	`MailMessagesClient.get`	`None`	`MailMessage`
`GET`	`/mail/messages/{messageId}/attempts`	`MailMessagesClient.attempts`	`None`	`{ data: MailSendAttempt[] }`
`GET`	`/mail/messages/{messageId}/logs`	`MailMessagesClient.logs`	`None`	`{ data: MailLog[] }`
`GET`	`/mail/messages/{messageId}/bounces`	`MailMessagesClient.bounces`	`None`	`{ data: MailBounce[] }`
`GET`	`/mail/suppressions`	`MailSuppressionsClient.list`	`None`	`MailSuppressionListResult`
`DELETE`	`/mail/suppressions/{suppressionId}`	`MailSuppressionsClient.delete`	`None`	`void`
`GET`	`/mail/bounces`	`MailBouncesClient.list`	`None`	`MailBounceListResult`
`POST`	`/mail/otp/send`	`MailOtpClient.send`	`MailOtpSendInput`	`MailOtpSendResponse`
`POST`	`/mail/otp/verify`	`MailOtpClient.verify`	`MailOtpVerifyInput`	`MailOtpVerifyResponse`
`GET`	`/mail/otp/challenges`	`MailOtpChallengesClient.list`	`None`	`MailOtpChallengeListResult`
`GET`	`/mail/otp/challenges/{challengeId}`	`MailOtpChallengesClient.get`	`None`	`MailOtpChallenge`
`POST`	`/mail/otp/challenges/{challengeId}/cancel`	`MailOtpChallengesClient.cancel`	`None`	`MailOtpChallenge`
`GET`	`/mail/scheduled`	`MailScheduledClient.list`	`None`	`{ data: MailScheduledMessage[] }`
`GET`	`/mail/scheduled/{id}`	`MailScheduledClient.get`	`None`	`MailScheduledMessage`
`POST`	`/mail/scheduled/{id}/cancel`	`MailScheduledClient.cancel`	`None`	`MailScheduledMessage`
`GET`	`/mail/batches`	`MailBatchClient.list`	`None`	`{ data: MailBatch[] }`
`GET`	`/mail/batches/{id}`	`MailBatchClient.get`	`None`	`MailBatch`
`GET`	`/mail/batches/{id}/items`	`MailBatchClient.items`	`None`	`{ data: MailBatchItem[] }`
`GET`	`/mail/inbound/domains`	`MailInboundDomainsClient.list`	`None`	`{ data: MailInboundDomain[] }`
`POST`	`/mail/inbound/domains/{id}/verify`	`MailInboundDomainsClient.verify`	`None`	`MailInboundDomain`
`GET`	`/mail/inbound/messages`	`MailInboundMessagesClient.list`	`None`	`{ data: MailInboundMessage[] }`
`GET`	`/mail/inbound/messages/{id}`	`MailInboundMessagesClient.get`	`None`	`MailInboundMessage`
`GET`	`/mail/events`	`MailEventsClient.list`	`None`	`MailEventListResult`
`GET`	`/mail/events/{eventId}`	`MailEventsClient.get`	`None`	`MailEvent`
`GET`	`/mail/webhooks`	`MailWebhooksClient.list`	`None`	`MailWebhookListResult`
`GET`	`/mail/webhooks/{webhookId}`	`MailWebhooksClient.get`	`None`	`MailWebhook`
`PATCH`	`/mail/webhooks/{webhookId}`	`MailWebhooksClient.update`	`MailWebhookUpdateInput`	`MailWebhook`
`POST`	`/mail/webhooks/{webhookId}/rotate-secret`	`MailWebhooksClient.rotateSecret`	`None`	`{ secret: string }`
`DELETE`	`/mail/webhooks/{webhookId}`	`MailWebhooksClient.delete`	`None`	`void`
`GET`	`/mail/webhooks/{webhookId}/deliveries`	`MailWebhooksClient.deliveries`	`None`	`{ data: MailWebhookDelivery[]; nextCursor?: string \| null }`
`GET`	`/mail/webhook-deliveries/{deliveryId}`	`MailWebhooksClient.getDelivery`	`None`	`MailWebhookDeliveryDetail`
`GET`	`/mail/messages/{messageId}/timeline`	`MailMessagesClient.timeline`	`None`	`{ data: MailTimelineItem[] }`
`GET`	`/mail/streams`	`MailStreamsClient.list`	`None`	`MailMessageStreamListResult`
`GET`	`/mail/audiences`	`MailAudiencesClient.list`	`None`	`{ data: MailAudience[] }`
`GET`	`/mail/audiences/{id}`	`MailAudiencesClient.get`	`None`	`MailAudience`
`GET`	`/mail/audiences/{id}/members`	`MailAudiencesClient.members`	`None`	`{ data: MailAudienceMember[] }`
`POST`	`/mail/audiences/{id}/imports/preview`	`MailAudiencesClient.previewImport`	`{ members: MailAudienceMemberImport[]; mode?: MailImportMode; }`	`MailImportResult`
`PUT`	`/mail/audiences/{id}/preferences`	`MailAudiencesClient.setEditableFields`	`{ editableFields: string[]; }`	`{ editableFields: string[] }`
`GET`	`/mail/campaigns`	`MailCampaignsClient.list`	`None`	`{ data: MailCampaign[] }`
`GET`	`/mail/campaigns/{id}`	`MailCampaignsClient.get`	`None`	`MailCampaign`
`PUT`	`/mail/campaigns/{id}`	`MailCampaignsClient.update`	`MailCampaignInput & { revision: number; }`	`MailCampaign`
`POST`	`/mail/campaigns/{id}/preview`	`MailCampaignsClient.preview`	`{ data?: Record<string, unknown>; variant?: string; }`	`MailTemplatePreview & { diagnostics: MailTemplateDiagnosticResult }`
`GET`	`/mail/campaigns/{id}/engagement`	`MailCampaignsClient.engagement`	`None`	`MailEngagementReport`
`GET`	`/mail/campaigns/{id}/estimate`	`MailCampaignsClient.estimate`	`None`	`MailCampaignEstimate`
`GET`	`/mail/exports`	`MailExportsClient.list`	`None`	`{ data: MailExport[] }`
`GET`	`/mail/exports/{id}`	`MailExportsClient.get`	`None`	`MailExport`
`GET`	`/mail/brands`	`MailBrandsClient.list`	`None`	`{ data: MailBrand[] }`
`GET`	`/mail/brands/{id}`	`MailBrandsClient.get`	`None`	`MailBrand`
`PUT`	`/mail/brands/{id}`	`MailBrandsClient.update`	`MailBrandFields & { revision: number; }`	`MailBrand`
`POST`	`/mail/brands/{id}/archive`	`MailBrandsClient.archive`	`None`	`MailBrand`
`GET`	`/mail/automations`	`MailAutomationsClient.list`	`None`	`{data: MailAutomation[]}`
`GET`	`/mail/forms`	`MailFormsClient.list`	`None`	`{data: MailSignupForm[]}`
`GET`	`/mail/segments`	`MailSegmentsClient.list`	`None`	`{data: MailSegment[]}`
`GET`	`/mail/tracking/settings`	`MailTrackingClient.settings`	`None`	`{ settings: MailTrackingSettings; available: boolean }`
`PUT`	`/mail/tracking/settings`	`MailTrackingClient.updateSettings`	`MailTrackingSettings`	`MailTrackingSettings`
`GET`	`/mail/messages/{id}/engagement`	`MailTrackingClient.message`	`None`	`MailEngagementReport`
`GET`	`/mail/tracking/domains`	`MailTrackingClient.domains`	`None`	`{ data: MailTrackingDomain[]; target: string; available: boolean }`
`POST`	`/mail/tracking/domains/{id}/verify`	`MailTrackingClient.verifyDomain`	`None`	`MailTrackingDomain`
`PUT`	`/mail/tracking/domains/{id}`	`MailTrackingClient.updateDomain`	`{ enabled: boolean; revoke?: boolean; }`	`void`

Errors

Mail handler errors return {"error":{"code":"…","message":"…","details":{}}}; details is optional. There is no required success field. Authentication or environment middleware can return {"error":"…"}. Check HTTP status and handle both shapes. See Test environment, brands, consent/imports, tracking, migration, and spending for worked requests, field limits and permission boundaries. The OpenAPI operation servers identify public audit routes separately. Authentication/environment middleware can return a simple error string; inspect HTTP status as well as structured Mail errors.

Examples

These static examples show the verified route and authentication boundary. Use the official SDK method shown in each heading so serialization and response unwrapping remain consistent with the contract. The example below requires a test credential (sspat_test_ prefix). IDs are illustrative; inspect the actual returned ID. A fresh send returns HTTP 202; an idempotent replay returns HTTP 200.

`POST /mail/send`

curl -X POST "https://api.stackshift.cloud/v1/mail/send"   -H "Authorization: Bearer $STACKSHIFT_API_KEY"   -H "Content-Type: application/json"   --data '{"from":"hello@example.com","to":["recipient@example.net"],"subject":"Integration test","text":"No real email is delivered with a test credential.","simulation":{"scenario":"delivered"},"idempotencyKey":"integration-fixture-1"}'

The request body is derived from MailSendInput in the official SDK contract. Response:

{
  "id": "00000000-0000-4000-8000-000000000001",
  "mode": "test",
  "status": "queued",
  "idempotencyStatus": "created"
}

Overview

API Reference

AI Sandboxes

Introduction

StackShift CLI

Getting Started

Assets

StackShift Mail

Durable Jobs

Projects

Applications

Workload Security

Stacks

Templates

WordPress

Ghost

Shopify Hosting

Nodes

Compute

Databases

Operations

Domains & Email

Terminal & Operations

Mobile Distribution

Team & Access

Billing

AI Features

S2 Object Storage

Infrastructure as Code

Settings

StackShift Support

Errors

Examples

`POST /mail/send`

​Errors

​Examples

​POST /mail/send

Errors

Examples

`POST /mail/send`