# Stampwing API reference preview

Explore Stampwing’s public API contract and a local example that sends no email. Customer accounts and hosted API access aren’t available yet.

Canonical: https://www.stampwing.com/reference
Contract version: 0.1.0

## Availability

Customer accounts and hosted API access aren’t available yet. We haven’t announced a launch date. This reference documents implemented interfaces, including features that still need a separate rollout.

OpenAPI: https://www.stampwing.com/reference/openapi.json

The OpenAPI server is an intentionally non-resolving .invalid placeholder. Do not treat it as a live endpoint. The public reference excludes private owner-session routes.

## Authentication

Project API keys are bearer credentials scoped to a project, environment, and permissions. Workspace administration endpoints use a separate scoped workspace credential. A project key never grants owner access. Keep credentials on your server.

## Sending and delivery

Use a stable idempotency key for each logical send and reuse it when retrying. A successful API request confirms acceptance for processing; receiving-server acceptance does not prove inbox placement. Test credentials simulate delivery.

## Try a local example

Download: https://www.stampwing.com/downloads/email-mock-server.mjs

The local fixture needs Node.js 22+. It has no authentication, keeps synthetic messages in memory, implements only a small subset of the send/status protocol, and never sends email. It is not a complete implementation of the OpenAPI contract.

```sh
# Download the linked email-mock-server.mjs, then run it in one terminal:
node email-mock-server.mjs

# In another terminal, create a simulated message:
curl -sS http://127.0.0.1:3027/api/v1/emails \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: preview-example-001' \
  --data '{"to":"reader@example.com","subject":"Local example","text":"This fixture sends no email."}'
```

The response contains a synthetic id, status queued, and mode demo. Repeat the same request with the same key to retrieve the same message. Change its body with that key to receive an idempotency conflict. Restarting the fixture clears its data.

Request lifecycle: https://www.stampwing.com/guides/transactional-email-api
Retry safety: https://www.stampwing.com/guides/prevent-duplicate-emails
Delivery webhooks: https://www.stampwing.com/guides/reliable-email-webhooks