reCAPTCHA Mailhide API

If your website displays the email address of your users, you may be increasing the amount of spam they get by allowing email harvesters to find a path to their inbox. Some websites use obfuscation methods such as "johndoe at example dot com", however many email harvesters have been designed to circumvent such tricks. reCAPTCHA Mailhide protects the user's email address by encrypting it. In order to decrypt the email address, a user must solve a reCAPTCHA to prove that they are a human. reCAPTCHA Mailhide provides a method by which you can obtain an encryption key for your own use.

Obtaining a key

To obtain an encryption key, you can go to the key generation service. This will compute a "public key", which much like a username identifies who you are to the Mailhide server, and a "private key" which allows you to encrypt email addresses.

Encrypting an email address

To send an email address to reCAPTCHA Mailhide, you must first encrypt it with your private key. The private key is a 128 bit AES key. The encryption works as follows:

  1. Pad the email address to 16 bytes, as required by AES. We use a padding scheme that works as follows:

    def pad_string (str, block_size):
       numpad = block_size - (len (str) % block_size)
       return str + numpad * chr (numpad)

    First, we find out how many padding chars will be needed, a number between 1 and 16 inclusive. Then we append that number as many times as needed. For example, the string: is padded to\x03\x03\x03 where \x03 is the byte 3. \x03 was chosen because 3 padding chars were needed to pad the string.

  2. AES encrypt the string. The private key is your AES encryption key. AES CBC mode is used with an initialization vector of 16 null bytes (in theory, using a common IV would allow an attacker to know if emails encrypted with the same key have a common 16 byte prefix. However, in order to decode both emails, the attacker still must solve a CAPTCHA. On the other hand an IV would make URLs significantly longer).

    As an example, if you have the key deadbeefdeadbeefdeadbeefdeadbeef, you would get the following encryptions:

    • E-mail:
      Padded version:\x03\x03\x03
      Encrypted data:
      c0 11 bb 9c e8 27 b4 aa 96 78 3a 45 f6 e7 15 35

    • E-mail:
      Padded version:{\x0d 13 times}
      Encrypted data:
      c2 15 88 aa 4d 2b e2 ea d9 fb 74 bb cb bb 92 71
      e0 bd fc 40 9d de 1a 40 1b 2e f5 13 6a 34 1e 92

    If you have the openssl package, you can generate your own test data by doing:

    echo -n "" | openssl enc  -aes-128-cbc -e -K
    deadbeefdeadbeefdeadbeefdeadbeef -iv
    00000000000000000000000000000000 | hexdump -C
  3. Base 64 encode the string. In order to safely put the encrypted string in a URL, it must be base 64 encrypted. We use a special base 64 encoding that is safe for URLs. Rather than using +, we use -, and rather than using / we use _. In Python, this is implemented as urlsafe_b64 encode.

    As an example, with the same key as in part 2, you would get the following encodings:

    • E-mail:
      Encrypted data:
      c0 11 bb 9c e8 27 b4 aa 96 78 3a 45 f6 e7 15 35
      Base 64 encoding:

    • E-mail:
      Encrypted data:
      c2 15 88 aa 4d 2b e2 ea d9 fb 74 bb cb bb 92 71
      e0 bd fc 40 9d de 1a 40 1b 2e f5 13 6a 34 1e 92
      Base 64 encoding:

Creating a Mailhide URL

Once you've encrypted an email address, you can create a Mailhide URL for it. The Mailhide decoder is located at You pass two items on the query string to this script:

Parameter Purpose
k (public key) Your public key, as given by the api key generation service
c (encrypted email) The encrypted email address, as created in the previous section

The final product should look something like this:

Displaying the Mailhide URL

We recommend that you display email addresses protected with mail hide in one of the following styles:

  • joh<a href="...">...</a>
    This is when you have only the email address, and not the name. It lets the viewer have a general idea of who's email they are seeing. In fact, the user may know who the email owner is just from this information and not need to decode the email address

    The hyperlink is only applied to the ... to make it clear that the email address isn't actually valid.

    It is important not to reveal too much of the email address when operating in this mode. We recommend showing 2 character of the username if the username is 1-4 characters, 3 characters if the username is 5-6 and 4 characters for longer emails.

  • <a href="...">John Doe</a>
    This method provides extra security because an attacker can't see any part of  the email address.

When displaying a hyperlink to Mailhide, the following code is preferred:

<a href=""
onclick="'', '',
return false;" title="Reveal this e-mail address">...</a>

This opens up a popup window if the user has JavaScript making sure the user doesn't lose their place on your website.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.