Skip to main content

Private messaging key

Mailchain uses a keyring to derive key pairs for different operations and create messaging keys for each registered address. This guide shows you how to obtain the private messaging key for a registered address in your Mailchain keyring and use it within an application with the Mailchain SDK.

info

Private and public messaging keys are only used for messaging. They are not wallet keys, so cannot be used to transact or wallet signing.

info

Public messaging keys are designed to be shared freely. Messaging keys are available publicly and looked up using an address.

danger

Private messaging keys must be kept securely. If you suspect your private messaging key has been compromised, re-register your wallet or protocol address to generate a new private messaging key.

Get private messaging key​

With an address specific messaging key, you can send messages directly from an address without needing access to your Secret Recovery Phrase.

You can retrieve a private messaging key of any the accounts registered to your Mailchain user account. Examples of account addresses include:

  • Mailchain user - e.g. [email protected]
  • Registered protocol address = e.g. 0xbb56FbD7A2caC3e4C17936027102344127b7a112@ethereum.mailchain.com
  • Registered protocol address with name service = e.g. [email protected]
  • Any other supported Mailchain address format

You can get access your private messaging keys via the web app or through code.

From web​

  1. Make sure you are logged in to your Mailchain account.

  2. Head to the accounts section in the settings.

  3. Click View messaging key get the messaging key for the corresponding account. You will need to enter your password to reveal the private messaging key.

From code​

The code below code shows how to retrieve your private messaging key for a registered address from your Mailchain keyring.

  1. First install the packages needed.

    npm install @mailchain/sdk @mailchain/keyring

  2. Next, you can use the code below, which uses your Mailchain account Secret Recovery Phrase to create your keyring, then retrieve the private messaging key for your registered address.

    Behind the scenes it:

    • Checks the address is registered and gets latest public messaging key by resolving the address.
    • Gets latest nonce for the address.
    • Checks messaging key from the resolved address matches keyring messaging key.
    import { getPrivateMessagingKey, privateMessagingKeyToHex, publicMessagingKeyToHex } from '@mailchain/sdk/internal';
    import { KeyRing } from '@mailchain/keyring';

    const keyRing = KeyRing.fromSecretRecoveryPhrase('....'); // securely supply 24 word secret recovery phrase

    // Address to get private messaging key for. Can be Mailchain, protocol or name service address.
    // The address must be registered with the account secret recovery phrase.
    const address = '[email protected]';

    const { data: privateMessagingKey, error: getPrivateMessagingKeyError } = await getPrivateMessagingKey(
    	address,
    	keyRing,
    );

    if (getPrivateMessagingKeyError) {
    	throw getPrivateMessagingKeyError;
    }

    // The private messaging key for the address MUST be kept secure.
    console.log(`Private messaging key for ${address} - ${privateMessagingKeyToHex(privateMessagingKey)}`);
    // The public messaging key for the address can be shared.
    console.log(`Public messaging key for ${address} - ${publicMessagingKeyToHex(privateMessagingKey.publicKey)}`);

Load existing key​

You may prefer to use individual messaging keys directly instead of using your Mailchain Secret Recovery Phrase in your application.

Mailchain uses keys in byte format in the SDK. To use a hex encoded key (i.e. one retrieved from the web or using the code above), follow these steps.

Use privateMessagingKeyFromHex to create your messaging key from your retrieved key bytes.

  1. Install the packages needed:

    npm install @mailchain/sdk

  2. The code below shows how to create a private messaging key from hex.

    import { privateMessagingKeyFromHex, privateMessagingKeyToHex, publicMessagingKeyToHex } from '@mailchain/sdk/internal';

    const recoveredPrivateMessagingKey = privateMessagingKeyFromHex('...'); // securely supply private messaging key hex bytes

    // The private messaging key for the address MUST be kept secure.
    console.log(`Private messaging - ${privateMessagingKeyToHex(recoveredPrivateMessagingKey)}`);
    // The public messaging key for the address can be shared.
    console.log(`Public messaging - ${publicMessagingKeyToHex(recoveredPrivateMessagingKey.publicKey)}`);

    Public messaging keys can also be created from hex.

    import { publicMessagingKeyFromHex, publicMessagingKeyToHex } from '@mailchain/sdk/internal';

    const recoveredPublicMessagingKey = publicMessagingKeyFromHex('...');

    // The public messaging key for the address can be shared.
    console.log(`Public messaging - ${publicMessagingKeyToHex(recoveredPublicMessagingKey)}`);

Check address messaging key​

You can check the private messaging key matches the public messaging key for an address stored on the key registry.

  1. Install the packages needed:

    npm install @mailchain/sdk

  2. The code below shows how to create a private messaging key from hex.

    import { resolveAddress, privateMessagingKeyFromHex, publicMessagingKeyToHex } from '@mailchain/sdk/internal';

    const recoveredPrivateMessagingKey = privateMessagingKeyFromHex('...'); // securely supply private messaging key hex bytes
    const address = '0xbb56FbD7A2caC3e4C17936027102344127b7a112@ethereum.mailchain.com';

    const { data: resolvedAddress, error: resolveAddressError } = await resolveAddress(address);
    if (resolveAddressError) {
    	const { type, message } = resolveAddressError;
    	console.warn(`ERROR check address - ${address} - ${type} - ${message}`);
    }

    const resolvedPublicKey = publicMessagingKeyToHex(resolvedAddress.messagingKey);
    const providedPublicKey = publicMessagingKeyToHex(recoveredPrivateMessagingKey.publicKey);

    if (resolvedPublicKey !== providedPublicKey) {
    	throw new Error(`Public messaging key does not match resolved address key, check the private key is correct. `);
    }

    console.log(`${address} messaging key matches latest address registry entry.`);

If the code errors then it means the private key is not valid for the address. Since the latest key is required for sending it's possible the messaging key has been rotated. Get the latest messaging key from code or the web app.