How to generate a new key pair and send a message

1. Install Java

If you don't have a Java runtime installed yet, go to java.com to download one for your platform.

2. Download the Java API Tool

3. Unzip the file

On Mac/Linux, run the following command in a terminal window: 
unzip threema-msgapi-sdk-java-2.1.0.zip
or
On Windows, right-click on the threema-msgapi-sdk-java-2.1.0.zip file and select “Extract All...”. A dialog box opens; enter a location and click “Extract”.

4. Generate a keypair by running the tool

IMPORTANT!

Create a backup (or preferably multiple backups) of your private key! If you lose it, your custom Threema ID will be unusable. We have no way to recover lost private keys for you, and it is also not possible to assign a new key to an existing ID.

This means that after requesting an E2E Gateway ID with a public key, if the corresponding private key is lost, nobody will ever be able to use this Gateway ID again!

Open a shell (on Windows open the command line) and go to the directory where you have extracted the ZIP.
Create a new private and public key by typing the following command: 
java -jar threema-msgapi-tool.jar -g privateKey.txt publicKey.txt
A new key pair will be generated. The private key will be saved in privateKey.txt and the public key in publicKey.txt. Both keys are formatted in hexadecimal with a prefix that indicates the key type.

5. Request custom Threema ID and submit key

Log in to your profile on the Threema Gateway website, click on "ID" in the navigation bar and then "Request Threema ID".
Choose End-to-End mode, enter the desired ID, and copy & paste the public key from the publicKey.txt file.

6. Wait for review

Wait until your custom Threema ID has been reviewed and accepted. As this is a manual process, it may take several days.

When your ID has been accepted, you will receive an API secret for authentication with the service.

7. Send a message

For the example below, let's say you want to send a message to the ID ECHOECHO*. Your custom ID is *MYAPIID and the API secret is df4oUM7eYei3kEAV.

Before you can encrypt and send your message, you need to retrieve the recipient's public key. Type the following command to do that: 
java -jar threema-msgapi-tool.jar -l -k ECHOECHO "*MYAPIID" df4oUM7eYei3kEAV
The tool will print the public key of the ID ECHOECHO: 
public:4a6a1b34dcef15d43cb74de2fd36091be99fbbaf126d099d47d83d919712c72b
You can store this public key so you don't have to look it up every time you want to send a message, and you can also verify it independently by comparing it with the contents of the recipient's public QR code.
Now encrypt and send your message by typing the following command: 
echo "This is my message." | java -jar threema-msgapi-tool.jar -S ECHOECHO "*MYAPIID" df4oUM7eYei3kEAV privateKey.txt
Your private key will be read from the file that you generated earlier on. The public key of the recipient can be passed directly on the command line.
* Please note: the ECHOECHO ID does not return messages from API IDs, so you will not get anything back.