Testing & sandbox

Test mode on the hosted platform

Your organization can have a test twin: a separate, free organization with test API keys, webhooks flagged livemode: false, vendor sandboxes and simulators, watermarked documents and [TEST] emails. Start with Test mode. Everything an API key does is real in the organization it belongs to: a production key acts on production data, a test key on test data only.

The rest of this page covers the local stack and the behavior of the signature sandbox and the simulated registered mail vendor, which test mode also uses.

Local stack

The MyCLM repository runs the whole platform locally (see its README): API on http://localhost:3100, app on http://<provider>.localhost:5173, and Mailpit on http://localhost:8025, which catches every email: invitations, signing links, signing codes and SMS (sent as emails prefixed with [SMS]).

export MLT_API_URL=http://localhost:3100

Create an API key in the local app exactly as in the Quickstart. The token URL points to the local identity provider (http://<provider>.auth.localhost:8090/oauth/v2/token).

Signature sandbox

Signature goes through the vendor Yousign. In test mode and on a local stack it uses a Yousign sandbox (test account), so no signature has legal value:

1. Create a signature request (the vendor is yousign).
2. Open the signing email in Mailpit, follow the link, request the code and sign.
3. The vendor confirms each signature to MyCLM by webhook: you receive signature.signed then signature.completed, and GET …/document?variant=signed returns the signed PDF.

On a local stack, the sandbox credentials come from the environment of the API (YOUSIGN_SANDBOX_API_KEY and YOUSIGN_SANDBOX_WEBHOOK_SECRET). Without a test account, signature is unavailable: there is no simulator.

Simulated registered mail vendor

With the local registered mail vendor, the recipient email decides the outcome, so you can test every branch:

Recipient email contains	Outcome
(anything else)	sent → deposited after ~20 s → delivered after ~60 s
refus	refused
neglig or neglect	neglected
bounce	bounced (webhook registered_mail.failed)
change	The recipient asks for another address (recipientUpdates), answer it with the API
fail	Refused at submission: failed, retryable

Example: marie.refus@example.fr ends refused. Proofs matching each status are generated and downloadable.

Webhooks in development

Events of a test organization carry livemode: false (see Test mode). Subscription URLs must be HTTPS. Locally, expose your endpoint through an HTTPS tunnel (ngrok, Cloudflare Tunnel…) and use Send a test event on the subscription to receive a signed webhook.test event on demand. The delivery log of the subscription shows each attempt, the status code and an excerpt of your response, and lets you replay any delivery.

Checklist before production

• Test and production kept apart: production key and webhook endpoint configured in the production organization, and events with livemode: false never acted upon as real.
• Credentials in a secrets manager, API key with an expiry date and an IP allowlist.
• Tokens cached until expires_in.
• 429 and 5xx retried with backoff, other errors surfaced (see Errors).
• Webhook signatures verified on the raw body, events deduplicated by id, 2xx answered within 10 seconds.