> For the complete documentation index, see [llms.txt](https://wiki.4thtech.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.4thtech.io/developers/sdk/quickstart.md).

# SDK quickstart

Send your first encrypted mail with the 4thTech SDK 0.5.x: build the clients, listen for new mail, send.

{% hint style="info" %}
**Status: Production-ready, stable.** The 4thTech SDK and the BlockMail & BlockChat white-label apps are supported; no new features are planned. Last release: SDK 0.5.13 (25 Nov 2025).
{% endhint %}

This quickstart targets SDK 0.5.x (`@4thtech-sdk/ethereum` 0.5.13). It runs in a browser, because encrypted mail needs the [Encryptor](https://wiki.4thtech.io/products/encryptor.md) extension. Use a testnet while you try it out.

## Before you start

* A browser wallet with some testnet funds on a [supported network](https://wiki.4thtech.io/developers/sdk/networks.md) that has OCC v1 contracts.
* The Encryptor extension installed, unlocked and set up, for both the sender and the receiver. The receiver's public key must be published; the [white-label app](https://wiki.4thtech.io/products/white-label/encryption.md) does this for you, or use `Encryptor.storePublicKey()`.
* A storage provider: a PollinationX endpoint and token. See [Storage](https://wiki.4thtech.io/products/white-label/storage.md).

## 1. Install

```bash
npm install @4thtech-sdk/ethereum @4thtech-sdk/encryption @4thtech-sdk/encryptor @4thtech-sdk/storage @4thtech-sdk/types viem
```

## 2. Create a wallet client

The SDK needs an object that implements `WalletClient`. This one uses `viem` with an injected browser wallet.

```ts
import { createWalletClient, custom } from 'viem';
import { gnosisChiado } from '@4thtech-sdk/ethereum';
import type { Address, EthereumTransactionRequest, WalletClient } from '@4thtech-sdk/types';

const chain = gnosisChiado; // a testnet from @4thtech-sdk/ethereum
const viemClient = createWalletClient({ chain, transport: custom(window.ethereum) });
const [account] = await viemClient.requestAddresses();

const walletClient: WalletClient = {
  chain,
  getAddress: async (): Promise<Address> => account,
  sendTransaction: (request: EthereumTransactionRequest) =>
    viemClient.sendTransaction({ account, chain, ...request }),
};
```

`sendTransaction` must return the transaction hash. The user confirms it in their wallet.

## 3. Create the storage provider, Encryptor and encryption handler

```ts
import { PollinationX } from '@4thtech-sdk/storage';
import { EncryptorExtensionConnector } from '@4thtech-sdk/encryptor';
import { EncryptionHandler, EncryptorAesEncryption } from '@4thtech-sdk/encryption';
import { Encryptor } from '@4thtech-sdk/ethereum';

const remoteStorageProvider = new PollinationX('<your-pollinationx-url>', '<your-pollinationx-token>');

const encryptor = new Encryptor({
  encryptorExtension: new EncryptorExtensionConnector(),
  walletClient,
});

const encryptorAesEncryption = new EncryptorAesEncryption(encryptor);
const encryptionHandler = new EncryptionHandler({
  encryptionImplementations: [encryptorAesEncryption],
});
```

## 4. Create the Mail client

```ts
import { Mail } from '@4thtech-sdk/ethereum';

const mail = new Mail({
  walletClient,
  remoteStorageProvider,
  appId: '<your-app-id>', // optional; defaults to the zero app ID
  encryptionHandler,
});
```

## 5. Listen for new mail

```ts
const myAddress = await walletClient.getAddress();

const stopWatching = mail.onNew(null, myAddress, (envelope) => {
  console.log(envelope.sender, envelope.content.subject);
});
// later: stopWatching();
```

## 6. Send an encrypted mail

```ts
import type { Envelope } from '@4thtech-sdk/types';

const envelope: Envelope = {
  content: {
    subject: 'Hello',
    body: 'My first encrypted mail.',
  },
  receiver: '<receiver-address>',
};

await encryptorAesEncryption.initialize(envelope.receiver);

const txHash = await mail.send({
  envelope,
  encryption: encryptorAesEncryption,
  onStateChange: (state) => console.log(state),
});
```

`initialize` fetches the receiver's public key and computes the shared secret, so it fails if the receiver has not published one. `send` stores the encrypted envelope, then asks the wallet to sign the transaction.

## What happens next

```mermaid
sequenceDiagram
  participant App as Your app
  participant W as WalletClient
  participant S as Storage provider
  participant M as Mail client
  participant N as Network
  App->>W: create a wallet client for the chosen network
  App->>S: create the storage provider
  App->>M: new Mail(walletClient, remoteStorageProvider, appId, encryptionHandler)
  App->>M: onNew(null, receiver, callback)
  App->>M: send(envelope, encryption)
  M->>S: store encrypted attachments and envelope
  M->>W: sendTransaction (link, checksum)
  W->>N: user signs and submits
  N-->>M: new-mail event
  M-->>App: callback(receivedEnvelope)
```

*Figure: The call sequence of the quickstart: build the clients, listen for new mail, then send one encrypted mail.*

The receiver's `onNew` callback fires with a `ReceivedEnvelope`, decrypted by the `EncryptionHandler`. See [`send`](https://wiki.4thtech.io/developers/sdk/ethereum/mail/send.md), [`onNew`](https://wiki.4thtech.io/developers/sdk/ethereum/mail/onnew.md) and [`fetchPaginated`](https://wiki.4thtech.io/developers/sdk/ethereum/mail/fetchpaginated.md) for the full options, and [SDK architecture](https://wiki.4thtech.io/developers/sdk/architecture.md) for the call sequence.
