+ * When this function returns TRUE, notmuch_message_results_get will
+ * return a valid object. Whereas when this function returns FALSE,
+ * notmuch_message_results_get will return NULL.
+ *
+ * See the documentation of notmuch_query_search_messages for example
+ * code showing how to iterate over a notmuch_message_results_t
+ * object.
+ */
+notmuch_bool_t
+notmuch_message_results_has_more (notmuch_message_results_t *results);
+
+/* Get the current result from 'results' as a notmuch_message_t.
+ *
+ * Note: The returned message belongs to 'results' and has a lifetime
+ * identical to it (and the query to which it belongs).
+ *
+ * See the documentation of notmuch_query_search_messages for example
+ * code showing how to iterate over a notmuch_message_results_t
+ * object.
+ *
+ * If an out-of-memory situation occurs, this function will return
+ * NULL.
+ */
+notmuch_message_t *
+notmuch_message_results_get (notmuch_message_results_t *results);
+
+/* Advance the 'results' iterator to the next result.
+ *
+ * See the documentation of notmuch_query_search_messages for example
+ * code showing how to iterate over a notmuch_message_results_t
+ * object.
+ */
+void
+notmuch_message_results_advance (notmuch_message_results_t *results);
+
+/* Destroy a notmuch_message_results_t object.
+ *
+ * It's not strictly necessary to call this function. All memory from
+ * the notmuch_message_results_t object will be reclaimed when the
+ * containg query object is destroyed.
+ */
+void
+notmuch_message_results_destroy (notmuch_message_results_t *results);
+
+/* Get the message ID of 'message'.
+ *
+ * The returned string belongs to 'message' and as such, should not be
+ * modified by the caller and will only be valid for as long as the
+ * message is valid, (which is until the query from which it derived
+ * is destroyed).
+ *
+ * This function will not return NULL since Notmuch ensures that every
+ * message has a unique message ID, (Notmuch will generate an ID for a
+ * message if the original file does not contain one).
+ */
+const char *
+notmuch_message_get_message_id (notmuch_message_t *message);
+
+/* Get the thread ID of 'message'.
+ *
+ * The returned string belongs to 'message' and as such, should not be
+ * modified by the caller and will only be valid for as long as the
+ * message is valid, (for example, until the user calls
+ * notmuch_message_destroy on 'message' or until a query from which it
+ * derived is destroyed).
+ *
+ * This function will not return NULL since Notmuch ensures that every
+ * message belongs to a single thread.
+ */
+const char *
+notmuch_message_get_thread_id (notmuch_message_t *message);
+
+/* Get the filename for the email corresponding to 'message'.
+ *
+ * The returned filename is relative to the base of the database from
+ * which 'message' was obtained. See notmuch_database_get_path() .
+ * The returned string belongs to the message so should not be
+ * modified or freed by the caller (nor should it be referenced after
+ * the message is destroyed). */
+const char *
+notmuch_message_get_filename (notmuch_message_t *message);
+
+/* Get the tags for 'message', returning a notmuch_tags_t object which
+ * can be used to iterate over all tags.
+ *
+ * The tags object is owned by the message and as such, will only be
+ * valid for as long as the message is valid, (which is until the
+ * query from which it derived is destroyed).