# 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.

Source: https://docs.dissolve.email/quickstart

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](https://app.dissolve.email/dashboard/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](/authentication).

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

```bash
export DISSOLVE_API_KEY=sk_live_...
```

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

```bash cURL
curl https://api.dissolve.email/v1/connection \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve();
console.log(await client.v1.connection());
```

```bash CLI
dna auth status
dna account
```

```python Python
import os, requests

HEADERS = {"Authorization": f"Bearer {os.environ['DISSOLVE_API_KEY']}"}
print(requests.get("https://api.dissolve.email/v1/connection", headers=HEADERS).json())
```

```json
{ "kind": "user", "clientId": null, "scopes": ["*"], "requestsPerMinute": 100, "resource": null }
```

## 2. Make an inbox

`POST /v1/inboxes` (scope `inboxes:write`)

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

```bash cURL
curl -X POST https://api.dissolve.email/v1/inboxes \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customName": "signup-test"}'
```

```ts TypeScript
const inbox = await client.v1.createInbox({ customName: 'signup-test' });
```

```bash CLI
# The CLI makes agent identities: an inbox with a password.
dna create --label signup-test --json
```

```python Python
inbox = requests.post(
    "https://api.dissolve.email/v1/inboxes",
    json={"customName": "signup-test"},
    headers=HEADERS,
).json()
```

```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](/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}/code` (scope `messages: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.

```bash cURL
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/code?timeout=30&from=github.com" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
const code = await client.v1.waitForCode(inbox.id, { timeout: 30, from: 'github.com' });
if (code.found) console.log(code.value);
```

```bash CLI
dna verify "$ID" --timeout 30 --from github.com --quiet
```

```python Python
code = 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")
```

```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](/verification) explains `type`, `confidence` and `since`.

## 5. Read the message

`GET /v1/inboxes/{id}/messages/{messageId}` (scope `messages:read`)

```bash cURL
curl https://api.dissolve.email/v1/inboxes/$INBOX_ID/messages/$MESSAGE_ID \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
const message = await client.v1.getMessage(inbox.id, code.message!.id);
console.log(message.subject, message.bodyText);
```

```bash CLI
dna message "$ID" "$MESSAGE_ID"
```

```python Python
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}` (scope `inboxes:write`)

```bash cURL
curl -X DELETE https://api.dissolve.email/v1/inboxes/$INBOX_ID \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
await client.v1.deleteInbox(inbox.id);
```

```bash CLI
dna delete "$ID"
```

```python Python
requests.delete(f"https://api.dissolve.email/v1/inboxes/{inbox['id']}", headers=HEADERS)
```

## Next

- [Agent identities](/agent): an inbox with a password and a fictional persona, for sign-ups.
- [Webhooks](/webhooks): be told about new mail instead of waiting for it.
- [MCP server](/mcp): let Claude, Cursor or ChatGPT do all of this by themselves.
- [Rate limits and plans](/rate-limits): what each plan allows.
