# Stampwing API essentials: requests, keys, and responses

Exact endpoint paths, single-recipient fields, permissions, idempotency rules, response semantics, templates, and feature boundaries.

Author: Stampwing
Canonical: https://www.stampwing.com/guides/stampwing-api-reference
Published: 2026-10-05
Reviewed: 2026-10-05
Category: Engineering

Build an integration without guessing endpoint names, credential scopes, fields, or delivery meanings.

## Short answer

Section link: https://www.stampwing.com/guides/stampwing-api-reference#short-answer

Call /api/v1 on your installation’s origin with a project Bearer key. Start with the single-recipient POST /api/v1/emails contract, save its ID, and read progress with GET /api/v1/emails/:id. Use the OpenAPI contract for additional operations.

## Before you start

Section link: https://www.stampwing.com/guides/stampwing-api-reference#before-you-start

For: Developers and AI assistants implementing an HTTP client or checking an SDK request.

Bring: An explicit installation origin, a server-side project key, and a persisted business-event identity.

Scope: This reference describes implemented interfaces. An OpenAPI operation is not evidence that it is enabled or publicly deployed. Owner-session and workspace-token operations use different authority from a project key.

## Connect Codex or Claude to your workspace

Section link: https://www.stampwing.com/guides/stampwing-api-reference#connect-assistant

Use the OAuth MCP connector to let an assistant work with saved templates, workflows, diagnostics, and authorized email operations. Follow the client-specific commands and choose the access you want to delegate.

[Connect Codex, Claude Code, or Claude with MCP](https://www.stampwing.com/guides/stampwing-codex-claude-mcp)

## Base URL and authentication

Section link: https://www.stampwing.com/guides/stampwing-api-reference#origins

Set POSTRUNE_BASE_URL to an origin such as http://127.0.0.1:3017 for local development or the exact HTTPS origin provided by your installation. SDK constructors add /api/v1 paths themselves. Do not invent api.stampwing.com or point API requests at the public waitlist website.

Send Authorization: Bearer YOUR_PROJECT_KEY from your server. Dashboard cookies do not substitute for a project API key. Project keys are scoped to a project, environment, and permission list. A query parameter or JSON projectId does not grant access to another project.

| Operation | Required project permission |
| --- | --- |
| GET /api/v1/doctor | Any valid project key; checks the credential and sends nothing. |
| POST /api/v1/emails | email:send; add templates:use for a published template. |
| GET /api/v1/emails/:id | email:read with the matching project/environment. |
| GET /api/v1/emails/:id/diagnostics | email:read; returns evidence, never automatically resends. |
| Template administration | templates:read or templates:write; separate from templates:use. |
| Receiving reads | receiving:read with a Live credential; receiving has separate setup. |

## Single-recipient request fields

Section link: https://www.stampwing.com/guides/stampwing-api-reference#send-fields

| Field | Required? | Meaning and limits |
| --- | --- | --- |
| from | Yes | A single sender address, optionally with a display name. Use hello@postrune.test for a Test tutorial; Live requires the matching verified sending domain. |
| to | Yes | One recipient email string, at most 254 characters. An array selects the separate logical-email contract. |
| subject | For raw content | 1–998 characters after trimming, without carriage returns or newlines. |
| text / html | At least one for raw content | Nonblank content; text up to 100,000 characters and HTML up to 200,000. Include both when useful. |
| replyTo | No | A single reply address. |
| expiresInSeconds | No | Integer from 60 to 86,400. Default 86,400; bounds the waiting period before submission, not the lifetime of a password-reset token. |
| attachments | No | Up to 10 with filename, base64 content, and optional contentType. Legacy MIME limit is 10 MiB; request envelope limit is 15 MiB. |
| templateVersionId + variables | Alternative to raw content | A published version UUID plus values matching its schema. Do not also supply subject/text/html. |
| idempotencyKey | Header or body | Stable 8–128 characters: letters, digits, dot, underscore, colon, hyphen. If both header and body are present, they must agree. |

Note: Do not add mode: "demo" or environment to the send body. The credential and deployment determine Test/Live behavior. Response mode: "demo" labels simulated delivery. Unknown fields can fail validation.

## A complete HTTP request

Section link: https://www.stampwing.com/guides/stampwing-api-reference#http-example

First call GET /api/v1/doctor with the same key and confirm credential.environment is test. This cURL request assumes your shell already has POSTRUNE_BASE_URL and POSTRUNE_API_KEY set. Unlike the downloaded Node script, cURL does not read .env.stampwing automatically and does not enforce the Test guard.

cURL — use a confirmed Test credential only

```shell
curl --fail-with-body --max-time 15 \
  "$POSTRUNE_BASE_URL/api/v1/emails" \
  -H "Authorization: Bearer $POSTRUNE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: stampwing-http:tutorial:001' \
  --data '{"from":"hello@postrune.test","to":"reader@example.com","subject":"Test connection","text":"Simulated Test message."}'
```

[Use the safer automatic Test check](https://www.stampwing.com/guides/stampwing-quickstart#run-test)

## Acceptance and status lookup

Section link: https://www.stampwing.com/guides/stampwing-api-reference#response

POST returns HTTP 202 with { id, status, mode }. Save id before doing other work. GET /api/v1/emails/:id returns metadata including createdAt, updatedAt, latencyMs, and events, without bodies, subject, addresses, or provider identifiers. Use the owner dashboard for authorized content and deeper diagnosis.

Timestamps are UTC ISO strings. Events may arrive out of order; use the reconciled top-level status. Poll at a modest interval such as five seconds with a deadline, respect 429, and stop polling at a useful terminal outcome. Prefer signed webhooks for ongoing updates.

| Status | What it establishes |
| --- | --- |
| queued | Persisted and waiting for processing. |
| submitted | Submission started or the provider accepted it; receiving-server outcome is pending. |
| accepted | The receiving server accepted the message; inbox placement is unknown. |
| bounced / complained | A bounce or complaint was reported. Suppression controls apply. |
| failed / expired | Failure was recorded, or the message expired before submission. Investigate before creating another operation. |
| uncertain | Submission cannot be confirmed. Reconcile the existing message; do not automatically resend. |

## Idempotency and recovery

Section link: https://www.stampwing.com/guides/stampwing-api-reference#idempotency

Save a key with the business event before sending, for example receipt:invoice-42:v1. Reuse the exact content and key after an unconfirmed request. Matching retries return the original message; changed content returns 409 IDEMPOTENCY_CONFLICT. Keys are project scoped, so give Test and Live operations distinct identities.

Avoid internal prefixes such as wf., smtp:, template-test:, out., signup., and marketing:. Do not treat retention as permanent application deduplication: keep your own durable event-to-message mapping. A new key is a new send intent, not a safe way around a conflict.

Ordinary SDK sends do not retry automatically. Opt-in retry helpers reuse frozen payloads, honor retry timing, and stop within their budgets. An accepted request whose eventual state becomes uncertain is still the original operation.

[Work through duplicate prevention](https://www.stampwing.com/guides/prevent-duplicate-emails)

## Logical emails, batches, and optional features

Section link: https://www.stampwing.com/guides/stampwing-api-reference#advanced

Use sendLogical/getLogicalEmail for multi-recipient messages, CC/BCC, scheduling, tags, and tracking options. These return an intent with per-recipient progress, not the legacy single-message shape. Batches accept 1–100 logical emails and return a batch manifest. Do not read a logical ID with the legacy getEmail method.

Extended sending, marketing, inbox workflows, regional controls, collaboration, and enterprise features can be disabled by deployment flags. The schema includes these implemented interfaces for reference; check actual availability and permissions before selecting them. Receiving also needs its own domain and infrastructure configuration.

[Download the complete OpenAPI JSON](https://www.stampwing.com/reference/openapi.json)

## Read collection pages without skipping records

Section link: https://www.stampwing.com/guides/stampwing-api-reference#pagination

Collection methods return one page at a time. Read that endpoint’s response envelope in OpenAPI, then pass its opaque nextCursor back as cursor with the same filters. Stop when nextCursor is null. Do not decode, edit, or invent cursors, and do not reuse one after changing filters or project/environment.

Single-message reads return a message object, not a collection envelope. Logical-email and batch reads have different result shapes. Select the endpoint and SDK method for the ID you actually received.

## Error responses and request IDs

Section link: https://www.stampwing.com/guides/stampwing-api-reference#errors

Errors use an appropriate non-2xx HTTP status and typically { error, code, requestId }. Schema errors may include bounded issues with field and message. Shared JSON responses carry X-Request-Id. Preserve the request ID, status, code, UTC time, and operation identity when escalating; never include secrets.

A proxy can return non-JSON content or a connection can fail without a response. Keep that distinct from a structured API rejection. Do not automatically retry permission, validation, quota, or conflict errors.

[Find the specific error and next step](https://www.stampwing.com/guides/stampwing-troubleshooting)

## Sources

Section link: https://www.stampwing.com/guides/stampwing-api-reference#sources

- [Stampwing API contract (implemented interfaces; deployment gates still apply)](https://www.stampwing.com/reference/openapi.json)

Developer documentation: https://www.stampwing.com/docs

Next step: [Try the request with a Test key](https://www.stampwing.com/guides/stampwing-quickstart)

## Related guides

- https://www.stampwing.com/guides/stampwing-quickstart
- https://www.stampwing.com/guides/stampwing-node-nextjs
- https://www.stampwing.com/guides/stampwing-troubleshooting

Editorial policy: https://www.stampwing.com/resources/editorial