---
title: "Primitive API Sandbox"
description: "Exercise Primitive's send and receive API with synthetic data, no credentials, and no production side effects."
canonical: "https://docs.primitive.dev/docs/sandbox"
last-updated: "2026-05-17T00:00:00.000Z"
---

# Primitive API Sandbox

Primitive provides a public test mode at `https://api.primitive.dev/v1`. No account or API key is required. Use the demo paths below to validate requests and inspect responses before calling authenticated production endpoints.

## Test endpoints

MethodURLBehaviorPOST`https://api.primitive.dev/v1/send-mail/demo`Validates a send request and returns a synthetic accepted response. No email is sent, queued, or stored.GET`https://api.primitive.dev/v1/demo/emails`Returns fixed synthetic email summaries.GET`https://api.primitive.dev/v1/demo/emails/{id}`Returns a synthetic email detail. Use an ID from the summaries.POST`https://api.primitive.dev/v1/demo/jobs`Returns a synthetic job and its status URL with HTTP 202.GET`https://api.primitive.dev/v1/demo/jobs/{id}`Returns a fixed processing status; this sample does not advance to completion.

Successful demo responses include `demo: true`. Demo reads expose no tenant data, and demo jobs run no real work. These endpoints are rate limited per IP; on HTTP 429, wait for the `Retry-After` interval before retrying.

## Try a send


```
curl -i https://api.primitive.dev/v1/send-mail/demo \
  -H 'Content-Type: application/json' \
  -d '{"from":"agent@example.com","to":"recipient@example.com","subject":"Sandbox test","body_text":"Hello from the Primitive sandbox."}'
```


Expect HTTP 200 with `success: true`, `demo: true`, and a synthetic send record under `data`. The body uses the same send schema as the live endpoint. To inspect validation errors safely, repeat the request with `{}` and expect HTTP 400 with `success: false` and a typed `error.code` and `error.message`.


```
curl https://api.primitive.dev/v1/demo/emails
```


The [OpenAPI document](https://api.primitive.dev/v1/openapi) describes these operations with `security: []`. See [error handling](/docs/errors) for the response envelope.

## Moving to production

The sandbox covers synthetic send, receive, and job examples. It does not simulate domain provisioning, Functions, billing, or payments. For real mail, [obtain credentials](/docs/auth), switch to `/v1/send-mail` or `/v1/emails`, and supply `Authorization: Bearer prim_<key>`. Authenticated endpoints operate on real organization data; a demo ID cannot identify a production resource.

Maintained by the [primitive.dev team](/about) · [Trust & security](/trust)Last updated: May 17, 2026