The Gmail API uses
to group email replies with their original message into a single conversation or
thread. This allows you to retrieve all messages in a conversation, in order,
making it easier to have context for a message or to refine search results.
Like messages, threads may also have labels applied to them. However, unlike messages, threads cannot be created, only deleted. Messages can, however, be inserted into a thread.
Threads provide a simple way of retrieving messages in a conversation in order.
By listing a set of threads you can choose to group messages by conversation
and provide additional context. You can retrieve a list of threads using the
threads.list method, or retrieve
a specific thread with
threads.get. You can also
filter threads using the same query parameters as
Message resource. If any
message in a thread matches the query, that thread is returned in the result.
The code sample below demonstrates how to use both methods in a sample that
displays the most chatty threads in your inbox. The
fetches all thread IDs, then
threads.get grabs all messages in each thread.
For those with 3 or more replies, we extract the
Subject line and display the
non-empty ones plus the number of messages in the thread. You'll also find this
code sample featured in the corresponding DevByte video.
def show_chatty_threads(service, user_id='me'): threads = service.users().threads().list(userId=user_id).execute().get('threads', ) for thread in threads: tdata = service.users().threads().get(userId=user_id, id=thread['id']).execute() nmsgs = len(tdata['messages']) if nmsgs > 2: # skip if <3 msgs in thread msg = tdata['messages']['payload'] subject = '' for header in msg['headers']: if header['name'] == 'Subject': subject = header['value'] break if subject: # skip if no Subject line print('- %s (%d msgs)' % (subject, nmsgs))
Adding drafts and messages to threads
If you are sending or migrating messages that are a response to another email or part of a conversation, your application should add that message to the related thread. This makes it easier for Gmail users who are participating in the conversation to keep the message in context.
In order to be part of a thread, a message or draft must meet the following criteria:
- The requested
threadIdmust be specified on the
Draft.Messageyou supply with your request.
In-Reply-Toheaders must be set in compliance with the RFC 2822 standard.
Subjectheaders must match.