Skip to content

messages

Fields = Literal['standard', 'include_headers'] module-attribute

Literal representing which headers to include with a message.

ListMessagesQueryParams = TypedDict('ListMessagesQueryParams', {None: get_type_hints(ListQueryParams), 'subject': NotRequired[str], 'any_email': NotRequired[List[str]], 'from': NotRequired[List[str]], 'to': NotRequired[List[str]], 'cc': NotRequired[List[str]], 'bcc': NotRequired[List[str]], 'in': NotRequired[List[str]], 'unread': NotRequired[bool], 'starred': NotRequired[bool], 'thread_id': NotRequired[str], 'received_before': NotRequired[int], 'received_after': NotRequired[int], 'has_attachment': NotRequired[bool], 'fields': NotRequired[Fields], 'search_query_native': NotRequired[str]}) module-attribute

Query parameters for listing messages.

Attributes:

Name Type Description
subject

Return messages with matching subject.
any_email

Return messages that have been sent or received by this comma-separated list of email addresses.
from

Return messages sent from this email address.
to

Return messages sent to this email address.
cc

Return messages cc'd to this email address.
bcc

Return messages bcc'd to this email address.
in

Return messages in this specific folder or label, specified by ID.
unread

Filter messages by unread status.
starred

Filter messages by starred status.
thread_id

Filter messages by thread_id.
received_before

Return messages with received dates before received_before.
received_after

Return messages with received dates after received_after.
has_attachment

Filter messages by whether they have an attachment.
fields

Specify "include_headers" to include headers in the response. "standard" is the default.
search_query_native

A native provider search query for Google or Microsoft.
limit NotRequired[int]

The maximum number of objects to return. This field defaults to 50. The maximum allowed value is 200.
page_token NotRequired[str]

An identifier that specifies which page of data to return. This value should be taken from a ListResponse object's next_cursor parameter.

CleanMessagesRequest

Bases: TypedDict

Request to clean a list of messages.

Attributes:

Name Type Description
message_id List[str]

IDs of the email messages to clean.
ignore_links NotRequired[bool]

If true, removes link-related tags () from the email message while keeping the text.
ignore_images NotRequired[bool]

If true, removes images from the email message.
images_as_markdown NotRequired[bool]

If true, converts images in the email message to Markdown.
ignore_tables NotRequired[bool]

If true, removes table-related tags (

, ) from the email message while keeping rows.

, ,
remove_conclusion_phrases NotRequired[bool]

If true, removes phrases such as "Best" and "Regards" in the email message signature.
Source code in nylas/models/messages.py 
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
class CleanMessagesRequest(TypedDict):
    """
    Request to clean a list of messages.

    Attributes:
        message_id: IDs of the email messages to clean.
        ignore_links: If true, removes link-related tags (<a>) from the email message while keeping the text.
        ignore_images: If true, removes images from the email message.
        images_as_markdown: If true, converts images in the email message to Markdown.
        ignore_tables: If true, removes table-related tags (<table>, <th>, <td>, <tr>) from the email message while
            keeping rows.
        remove_conclusion_phrases: If true, removes phrases such as "Best" and "Regards" in the email message signature.
    """

    message_id: List[str]
    ignore_links: NotRequired[bool]
    ignore_images: NotRequired[bool]
    images_as_markdown: NotRequired[bool]
    ignore_tables: NotRequired[bool]
    remove_conclusion_phrases: NotRequired[bool]

CleanMessagesResponse dataclass

Bases: Message

Message object with the cleaned HTML message body.

Attributes:

Name Type Description
id str

Globally unique object identifier.
grant_id str

The grant that this message belongs to.
from_ List[EmailName]

The sender of the message.
date int

The date the message was received.
object int

The type of object.
thread_id Optional[str]

The thread that this message belongs to.
subject Optional[str]

The subject of the message.
to Optional[List[EmailName]]

The recipients of the message.
cc Optional[List[EmailName]]

The CC recipients of the message.
bcc Optional[List[EmailName]]

The BCC recipients of the message.
reply_to Optional[List[EmailName]]

The reply-to recipients of the message.
unread Optional[bool]

Whether the message is unread.
starred Optional[bool]

Whether the message is starred.
snippet Optional[str]

A snippet of the message body.
body Optional[str]

The body of the message.
attachments Optional[List[Attachment]]

The attachments on the message.
folders Optional[List[str]]

The folders that the message is in.
created_at Optional[int]

Unix timestamp of when the message was created.
conversation str

The cleaned HTML message body.
Source code in nylas/models/messages.py 
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
@dataclass_json
@dataclass
class CleanMessagesResponse(Message):
    """
    Message object with the cleaned HTML message body.

    Attributes:
        id (str): Globally unique object identifier.
        grant_id (str): The grant that this message belongs to.
        from_ (List[EmailName]): The sender of the message.
        date (int): The date the message was received.
        object: The type of object.
        thread_id (Optional[str]): The thread that this message belongs to.
        subject (Optional[str]): The subject of the message.
        to (Optional[List[EmailName]]): The recipients of the message.
        cc (Optional[List[EmailName]]): The CC recipients of the message.
        bcc (Optional[List[EmailName]]): The BCC recipients of the message.
        reply_to (Optional[List[EmailName]]): The reply-to recipients of the message.
        unread (Optional[bool]): Whether the message is unread.
        starred (Optional[bool]): Whether the message is starred.
        snippet (Optional[str]): A snippet of the message body.
        body (Optional[str]): The body of the message.
        attachments (Optional[List[Attachment]]): The attachments on the message.
        folders (Optional[List[str]]): The folders that the message is in.
        created_at (Optional[int]): Unix timestamp of when the message was created.
        conversation (str): The cleaned HTML message body.
    """

    conversation: str = ""

FindMessageQueryParams

Bases: TypedDict

Query parameters for finding a message.

Attributes:

Name Type Description
fields NotRequired[Fields]

Specify "include_headers" to include headers in the response. "standard" is the default.
Source code in nylas/models/messages.py 
134
135
136
137
138
139
140
141
142
class FindMessageQueryParams(TypedDict):
    """
    Query parameters for finding a message.

    Attributes:
        fields: Specify "include_headers" to include headers in the response. "standard" is the default.
    """

    fields: NotRequired[Fields]

Message dataclass

A Message object.

Attributes:

Name Type Description
id Optional[str]

Globally unique object identifier.
grant_id str

The grant that this message belongs to.
thread_id Optional[str]

The thread that this message belongs to.
subject Optional[str]

The subject of the message.
from_ Optional[List[EmailName]]

The sender of the message.
object str

The type of object.
to Optional[List[EmailName]]

The recipients of the message.
cc Optional[List[EmailName]]

The CC recipients of the message.
bcc Optional[List[EmailName]]

The BCC recipients of the message.
reply_to Optional[List[EmailName]]

The reply-to recipients of the message.
date Optional[int]

The date the message was received.
unread Optional[bool]

Whether the message is unread.
starred Optional[bool]

Whether the message is starred.
snippet Optional[str]

A snippet of the message body.
body Optional[str]

The body of the message.
attachments Optional[List[Attachment]]

The attachments on the message.
folders Optional[List[str]]

The folders that the message is in.
headers Optional[List[MessageHeader]]

The headers of the message.
created_at Optional[int]

Unix timestamp of when the message was created.
schedule_id Optional[str]

The ID of the scheduled email message. Nylas returns the schedule_id if send_at is set.
send_at Optional[int]

Unix timestamp of when the message will be sent, if scheduled.
Source code in nylas/models/messages.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
@dataclass_json
@dataclass
class Message:
    """
    A Message object.

    Attributes:
        id: Globally unique object identifier.
        grant_id: The grant that this message belongs to.
        thread_id: The thread that this message belongs to.
        subject: The subject of the message.
        from_: The sender of the message.
        object: The type of object.
        to: The recipients of the message.
        cc: The CC recipients of the message.
        bcc: The BCC recipients of the message.
        reply_to: The reply-to recipients of the message.
        date: The date the message was received.
        unread: Whether the message is unread.
        starred: Whether the message is starred.
        snippet: A snippet of the message body.
        body: The body of the message.
        attachments: The attachments on the message.
        folders: The folders that the message is in.
        headers: The headers of the message.
        created_at: Unix timestamp of when the message was created.
        schedule_id: The ID of the scheduled email message. Nylas returns the schedule_id if send_at is set.
        send_at: Unix timestamp of when the message will be sent, if scheduled.
    """

    grant_id: str
    from_: Optional[List[EmailName]] = field(
        default=None, metadata=config(field_name="from")
    )
    object: str = "message"
    id: Optional[str] = None
    body: Optional[str] = None
    thread_id: Optional[str] = None
    subject: Optional[str] = None
    snippet: Optional[str] = None
    to: Optional[List[EmailName]] = None
    bcc: Optional[List[EmailName]] = None
    cc: Optional[List[EmailName]] = None
    reply_to: Optional[List[EmailName]] = None
    attachments: Optional[List[Attachment]] = None
    folders: Optional[List[str]] = None
    headers: Optional[List[MessageHeader]] = None
    unread: Optional[bool] = None
    starred: Optional[bool] = None
    created_at: Optional[int] = None
    date: Optional[int] = None
    schedule_id: Optional[str] = None
    send_at: Optional[int] = None

MessageHeader dataclass

A message header.

Attributes:

Name Type Description
name str

The header name.
value str

The header value.
Source code in nylas/models/messages.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
@dataclass_json
@dataclass
class MessageHeader:
    """
    A message header.

    Attributes:
        name: The header name.
        value: The header value.
    """

    name: str
    value: str

ScheduledMessage dataclass

A scheduled message.

Attributes:

Name Type Description
schedule_id str

The unique identifier for the scheduled message.
status ScheduledMessageStatus

The status of the scheduled message.
close_time Optional[int]

The time the message was sent or failed to send, in epoch time.
Source code in nylas/models/messages.py 
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
@dataclass_json
@dataclass
class ScheduledMessage:
    """
    A scheduled message.

    Attributes:
        schedule_id: The unique identifier for the scheduled message.
        status: The status of the scheduled message.
        close_time: The time the message was sent or failed to send, in epoch time.
    """

    schedule_id: str
    status: ScheduledMessageStatus
    close_time: Optional[int] = None

ScheduledMessageStatus dataclass

The status of a scheduled message.

Attributes:

Name Type Description
code str

The status code the describes the state of the scheduled message.
description str

A description of the status of the scheduled message.
Source code in nylas/models/messages.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
@dataclass_json
@dataclass
class ScheduledMessageStatus:
    """
    The status of a scheduled message.

    Attributes:
        code: The status code the describes the state of the scheduled message.
        description: A description of the status of the scheduled message.
    """

    code: str
    description: str

StopScheduledMessageResponse dataclass

The response from stopping a scheduled message.

Attributes:

Name Type Description
message str

A message describing the result of the request.
Source code in nylas/models/messages.py 
194
195
196
197
198
199
200
201
202
203
204
@dataclass_json
@dataclass
class StopScheduledMessageResponse:
    """
    The response from stopping a scheduled message.

    Attributes:
        message: A message describing the result of the request.
    """

    message: str

UpdateMessageRequest

Bases: TypedDict

Request payload for updating a message.

Attributes:

Name Type Description
starred NotRequired[bool]

The message's starred status
unread NotRequired[bool]

The message's unread status
folders NotRequired[List[str]]

The message's folders
metadata NotRequired[Dict[str, Any]]

A list of key-value pairs storing additional data
Source code in nylas/models/messages.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
class UpdateMessageRequest(TypedDict):
    """
    Request payload for updating a message.

    Attributes:
        starred: The message's starred status
        unread: The message's unread status
        folders: The message's folders
        metadata: A list of key-value pairs storing additional data
    """

    unread: NotRequired[bool]
    starred: NotRequired[bool]
    folders: NotRequired[List[str]]
    metadata: NotRequired[Dict[str, Any]]