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](https://developers.google.com/workspace/gmail/reactions/format#part-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](https://unicode.org/reports/tr51/).

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](https://unicode.org/reports/tr51/), 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](https://support.google.com/mail/answer/14080429).