---
title: "openemail.encryption"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://openemail.uk/docs/sdk/reference/encryption"
area: "SDK"
category: "Reference"
---

# openemail.encryption

Every method in this namespace: its signature, its parameters, what it returns and an example.

## Methods

The OpenPGP public keys that let senders seal mail to your addresses: list the ones you published, publish or rotate one, and look up the keys of recipients before sealing a message.

### `encryption.listKeys()`

List your published encryption keys

```ts
listKeys(options?: RequestScope): Promise<Array<EncryptionKeyResource>>
```

Resolves every OpenPGP public key published for an address in this workspace, newest first, the Encryption page of the app. Retired keys are included, with `revokedAt` and `revokedReason` set, and the live key of each address has `revokedAt` null.

Published keys belong to a person. A key reads and publishes the keys of the workspace owner, and an access token those of the person who connected the app. A key limited to particular addresses lists only the keys of those addresses.

Scopes: `emails:read`.

**Parameters**

- `options.signal` (`AbortSignal`): Cancels the request.
- `options.apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

`Array<EncryptionKeyResource>`, each with `id`, `address`, `fingerprint`, `publicKey`, `algorithm`, `createdAt`, `revokedAt` and `revokedReason`.

**Example**

```ts
const keys = await openemail.encryption.listKeys()

for (const key of keys) console.log(key.address, key.fingerprint, key.revokedAt === null ? 'live' : 'retired')
```

**Notes**

- Only public keys travel through the API. The private key stays on the device that made it.

Also available in: API [`GET /encryption/keys`](https://openemail.uk/docs/api/reference/encryption#get-encryption-keys); CLI [`openemail encryption list-keys`](https://openemail.uk/docs/cli/reference/encryption#encryption-list-keys).

### `encryption.publishKey()`

Publish a public key for one of your addresses

```ts
publishKey(body: EncryptionKeyPublish, options?: RequestScope): Promise<EncryptionKeyResource>
```

Publishes an armored OpenPGP public key for one of your addresses, so that senders can seal mail to it, as Publish on the Encryption page does. The address has to be an address of this workspace on a verified domain, switched on, and one you may use.

An address keeps one live key. To rotate, pass the fingerprint of the live key as `replaces`: it is retired as the new key is published. Mail already sealed to the old key stays readable only with the old private key.

Published keys belong to a person. A key reads and publishes the keys of the workspace owner, and an access token those of the person who connected the app.

Scopes: `emails:read`.

**Parameters**

- `body.address` (`string`, required): The address the key is for.
- `body.publicKey` (`string`, required): The armored OpenPGP PUBLIC KEY BLOCK, up to 64 KB.
- `body.fingerprint` (`string`, required): The fingerprint of the key, 40 upper-case hexadecimal characters.
- `body.algorithm` (`string`): The algorithm of the key, such as `ed25519`, for display only.
- `body.replaces` (`string`): The fingerprint of the live key this one replaces, to rotate it.
- `options.signal` (`AbortSignal`): Cancels the request.
- `options.apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

`EncryptionKeyResource` for the key, now live.

**Example**

```ts
const key = await openemail.encryption.publishKey({
    address: 'ana@acme.com',
    publicKey: armored,
    fingerprint: '3F2A9C1B7E4D5F60A1B2C3D4E5F60718293A4B5C'
})

console.log(key.id)
```

**Notes**

- With an OAuth access token it asks for a verification code: until the app has verified one, it is refused with 403 `step_up_required`. An API key is never asked.
- A second key while one is live, without `replaces`, is 409 `key_already_published`, and so is a key that was published for the address before. An address on a domain that is not verified yet is 409 `domain_not_verified`, and an address you may not use is 403 `address_not_allowed`.
- The SDK does not retry it.

Also available in: API [`POST /encryption/keys`](https://openemail.uk/docs/api/reference/encryption#post-encryption-keys); CLI [`openemail encryption publish-key`](https://openemail.uk/docs/cli/reference/encryption#encryption-publish-key).

### `encryption.lookupKeys()`

Find the keys to seal mail to

```ts
lookupKeys(options: EncryptionKeyLookupOptions): Promise<Array<EncryptionKeyLookupResource>>
```

Resolves the live public keys published for each recipient address, the lookup the composer makes before it seals a message. An address with no key comes back with `keys` empty, so mail to it cannot be sealed. Only keys published by somebody who can read the address count.

Scopes: `emails:send`.

**Parameters**

- `options.addresses` (`Array<string>`, required): Recipient addresses, at most 51, sent comma-separated.
- `options.signal` (`AbortSignal`): Cancels the request.
- `options.apiKey` (`string`): Overrides the client's API key for this call only.

**Returns**

`Array<EncryptionKeyLookupResource>`, one per address, each with `address` and `keys`, every key with `fingerprint`, `publicKey` and `createdAt`.

**Example**

```ts
const found = await openemail.encryption.lookupKeys({ addresses: ['ana@acme.com', 'bob@example.org'] })

const sealable = found.every((entry) => entry.keys.length > 0)
```

**Notes**

- A display name in angle brackets is read as its address.

Also available in: API [`GET /encryption/keys/lookup`](https://openemail.uk/docs/api/reference/encryption#get-encryption-keys-lookup); CLI [`openemail encryption lookup-keys`](https://openemail.uk/docs/cli/reference/encryption#encryption-lookup-keys).