Skip to content
docs
Browse the docsQuickstart

Get started

Quickstart

Get a key, make an inbox, use the address, wait for the verification code and clean up, with every request and answer shown in cURL, TypeScript, the CLI and Python.

Five minutes, one inbox, one code. Each step shows the request in four languages; pick one and every sample on the page follows.

1. Get a credential

The API takes a bearer token on every /v1 request. There are two kinds:

  • An API key (sk_live_...) for your own scripts, tests and CI. Make one in the app under API keys, or run dna auth login. API keys need a Pro or Business plan.
  • An OAuth access token (dna_at_...) when you build an app or agent that acts for other people. Any plan can connect this way. See Authentication.

Keep the key out of your code: the SDK and the CLI read DISSOLVE_API_KEY from the environment.

Shell
export DISSOLVE_API_KEY=sk_live_...

Check it works with the one call that needs no scope:

curl https://api.dissolve.email/v1/connection \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
JSON
{ "kind": "user", "clientId": null, "scopes": ["*"], "requestsPerMinute": 100, "resource": null }

2. Make an inbox

POST/v1/inboxesinboxes:write

With no body the address is random. On Pro and Business, customName picks the part before the @.

curl -X POST https://api.dissolve.email/v1/inboxes \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customName": "signup-test"}'
JSON
{
  "id": "V1StGXR8Z5jdHi6BmyT2k",
  "address": "signup-test@dissolve.email",
  "domain": "dissolve.email",
  "expiresAt": "2026-11-19T10:30:00.000Z",
  "createdAt": "2026-11-19T10:00:00.000Z",
  "customName": "signup-test",
  "isReserved": false,
  "forwardTo": null
}

Keep the id: every other call names the inbox by it, not by its address. The inbox expires at expiresAt (30 minutes on Pro). Inboxes covers extending it.

3. Use the address

Type address into the sign-up form of the site you are testing, or hand it to your test runner. Mail from anyone is accepted.

4. Wait for the code

GET/v1/inboxes/{id}/codemessages:read

The code call waits until a message with a verification code or magic link arrives, then answers with it. timeout is in seconds and capped by your plan (Pro 30, Business 120). from keeps out mail from other senders.

curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/code?timeout=30&from=github.com" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
JSON
{
  "found": true,
  "type": "code",
  "value": "482913",
  "confidence": 0.95,
  "message": {
    "id": "Qm8wZ1kX0pLr7aYtV3nBc",
    "fromAddress": "noreply@github.com",
    "fromName": "GitHub",
    "subject": "Your GitHub launch code",
    "receivedAt": "2026-11-19T10:02:11.000Z"
  }
}

found: false means nothing arrived in time: check the address was entered, then call again. Codes and waiting explains type, confidence and since.

5. Read the message

GET/v1/inboxes/{id}/messages/{messageId}messages:read
curl https://api.dissolve.email/v1/inboxes/$INBOX_ID/messages/$MESSAGE_ID \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

6. Clean up

Inboxes delete themselves when they expire. To go sooner:

DELETE/v1/inboxes/{id}inboxes:write
curl -X DELETE https://api.dissolve.email/v1/inboxes/$INBOX_ID \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Next

Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown