Sandbox and test mode

Test mode exists so you can build and run a full integration — send, sign, complete, webhook, download — without usage charges. Recipients receive real emails explicitly marked as test documents. Use addresses you control.

How a request becomes a test request

Two ways, and they agree:

1. The key. Any request with an sk_test_ key is a test request, and nothing the caller sends can turn that off.
2. The flag. test_mode: true on a create makes that document a test document even with a live key.

There is nothing else to configure. If your code has an if (env === 'staging') branch deciding whether to set a flag, delete it and use a sandbox key instead.

Both routes need the plan entitlement that sandbox keys come with: Light and above. On Free, test_mode: true is refused.

What test mode does

	Test mode
Billing	Never counted. A test document never touches the monthly counters and can never be refused for being over them.
Email	Delivered to recipients with “This is a test document” in the message and [TEST] in the subject.
Signing	Works normally. Open the signing URL and sign.
Artifacts	Every page is watermarked “Not legally binding – test mode,” including the completed PDF.
Webhooks	Delivered only to endpoints with include_test_mode: true.
Rate limit	The same buckets and the same numbers as live keys: 120/min general, 10/min for POST, PUT and PATCH, 120/min for POST /files.
Document limits	Unlimited.

Real delivery in test mode

Invitations, reminders, passcodes, and completed copies go to the intended recipients. Test emails include an explicit notice, and test documents are not legally binding. Invalid recipient addresses can bounce just as they do in live mode.

What a sandbox key cannot reach

A sandbox key is not merely filtered to test rows; it is confined to a list of route families, and everything else answers 403 sandbox_key_not_allowed. Documents, templates, files, bulk sends, webhook endpoint configuration, the event catalog, its own API keys and /me are allowed. The address book, the suppression list, webhook delivery logs and replay, the debug inbox, data exports, members, billing, workspace settings and OAuth applications are not — they hold live data with no test-mode column to filter on.

Webhook endpoints are allowed but partitioned: a sandbox key sees and can change only the endpoints a sandbox key registered, so the production callback is a 404 to a staging credential. Delivery is not partitioned — an endpoint a sandbox key registered still receives the live events it subscribed to.

A sandbox key also creates only sandbox keys. Asking it for a live key is a 422 on mode, and a live key reached by id is a 404.

Sending test events

Every webhook endpoint has a “send test event” action for each event type: POST /webhook_endpoints/{id}/ping with an event_type sends a realistic sample of that event, synchronously, and never counts towards the endpoint’s health. Creating an endpoint with verify: true sends a plain ping first and activates the endpoint only if your receiver answers 2xx. Both let you exercise a receiver before there is a real document to exercise it with.

Moving to live

1. Create a live key — from the app or with another live key, since a sandbox key cannot mint one — and put it wherever your sandbox key was.
2. Register your production webhook endpoint with the live key. A sandbox key’s endpoints stay visible only to sandbox keys.
3. Check include_test_mode on your webhook endpoints — most production endpoints should have it off.
4. Nothing else changes. The paths, bodies, statuses, and event names are identical.

Related

• Authentication and keys
• Webhooks
• Migrating to Signclad