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 rundna 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.
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"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve();
console.log(await client.v1.connection());dna auth status
dna accountimport os, requests
HEADERS = {"Authorization": f"Bearer {os.environ['DISSOLVE_API_KEY']}"}
print(requests.get("https://api.dissolve.email/v1/connection", headers=HEADERS).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"}'const inbox = await client.v1.createInbox({ customName: 'signup-test' });# The CLI makes agent identities: an inbox with a password.
dna create --label signup-test --jsoninbox = requests.post(
"https://api.dissolve.email/v1/inboxes",
json={"customName": "signup-test"},
headers=HEADERS,
).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"const code = await client.v1.waitForCode(inbox.id, { timeout: 30, from: 'github.com' });
if (code.found) console.log(code.value);dna verify "$ID" --timeout 30 --from github.com --quietcode = requests.get(
f"https://api.dissolve.email/v1/inboxes/{inbox['id']}/code",
params={"timeout": 30, "from": "github.com"},
headers=HEADERS,
timeout=60,
).json()
print(code["value"] if code["found"] else "nothing yet"){
"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"const message = await client.v1.getMessage(inbox.id, code.message!.id);
console.log(message.subject, message.bodyText);dna message "$ID" "$MESSAGE_ID"message = requests.get(
f"https://api.dissolve.email/v1/inboxes/{inbox['id']}/messages/{code['message']['id']}",
headers=HEADERS,
).json()
print(message["subject"])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"await client.v1.deleteInbox(inbox.id);dna delete "$ID"requests.delete(f"https://api.dissolve.email/v1/inboxes/{inbox['id']}", headers=HEADERS)Next
- Agent identities: an inbox with a password and a fictional persona, for sign-ups.
- Webhooks: be told about new mail instead of waiting for it.
- MCP server: let Claude, Cursor or ChatGPT do all of this by themselves.
- Rate limits and plans: what each plan allows.
Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown