Email reactions

Email reactions let users respond to email messages in a fun, friction-free way using emoji.

Format

An email reaction is a regular MIME-formatted email with a special part that indicates that it's a reaction.

Overall message format

The email must have a body part with Content-Type: text/vnd.google.email-reaction+json, formatted as described in the definition.

A body part is either:

  • The top-level part of the message. This means that the Content-Type header of the email is text/vnd.google.email-reaction+json.
  • A sub-part of a multipart MIME part that has a Content-Type of text/vnd.google.email-reaction+json and a Content-Disposition that's not attachment.

The reaction email should also have regular text/plain and text/html parts so that email clients that don't support email reactions still display a response. Gmail recommends putting the text/vnd.google.email-reaction+json part between the text/plain and text/html parts. This is because some email clients always display the last part regardless of whether they actually understand its MIME type. Likewise, some email clients only display the first part.

The email should also have an In-Reply-To header containing the message ID of the message to which the reaction applies. This must be a single message ID.

text/vnd.google.email-reaction+json part definition

This MIME part is in JSON format. It has two fields:

  • version: An integer representing the version of the email reaction format that this part conforms to. This must be 1.
  • emoji: A string representing exactly one emoji symbol as defined by the Unicode Technical Standard 51.

If the Content-Transfer-Encoding is a binary format, then the JSON must use UTF-8 character encoding. Otherwise, the Content-Transfer-Encoding can be any standard encoding.

Gmail's interpretation of text/vnd.google.email-reaction+json

When Gmail receives a message that looks like a reaction, it validates the reaction part and applies special display treatment to that message.

Validation

Gmail validates all messages with a text/vnd.google.email-reaction+json part that it receives. If the part is malformed, it's considered invalid and the message is not treated as a reaction.

In particular:

  1. Gmail parses the JSON and checks its validity. If the JSON is malformed, Gmail considers the part invalid.

  2. Gmail checks the version field. The version must be exactly 1. It must be an integer; it cannot be a string. As the format evolves, other versions might be accepted. If the version is unknown or missing, Gmail considers the part invalid.

  3. Gmail checks the emoji field. The contents must be exactly one of the emoji specified by version 15 or higher of the Unicode Technical Standard 51, including any referenced extensions, such as skin tone. As the emoji standard evolves, Gmail commits to supporting at least the latest version minus

    1. Gmail likely supports the latest version except for the window required to implement any newly released standard. If the field is missing, empty, or doesn't contain exactly one emoji, then Gmail considers the part invalid.

Display

For messages with valid email reaction parts, Gmail displays the emoji in the emoji field near the message specified by the In-Reply-To header. This might also include a count of how many reactions are received with that emoji; it might also show the sender of that reaction or other UI treatments. If the In-Reply-To header is missing or a message with the given ID cannot be found in the conversation thread, Gmail displays the reaction message as a regular email. Gmail might not find the message if the user deleted it, the thread is too long, or for other reasons.

When displaying invalid email reaction messages, Gmail displays the text/html part if it exists. Otherwise, it uses the text/plain part. If no body part with either of those exists, Gmail displays an empty message.

Limits

Gmail recommends that clients looking to support email reactions apply limits to prevent reactions from overwhelming users. In particular:

  • Messages from mailing lists shouldn't support reactions.
  • Messages with too many recipients shouldn't support reactions (such as more than 20 distinct recipients in the combined To and CC fields).
  • Messages where the recipient isn't in the To or CC fields shouldn't support reactions.
  • Messages that already have many reactions shouldn't support reactions (such as more than 20 reactions per user for any single message).

These and other limits are also described under the "Unable to send emoji reactions" section of Reply to emails with emoji reactions.