Skip to content

messages

Fields = Literal['standard', 'include_headers', 'include_tracking_options', 'raw_mime'] 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[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], 'select': 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 which headers to include in the response. - "standard" (default): Returns the standard message payload. - "include_headers": Returns messages and their custom headers. - "include_tracking_options": Returns messages and their tracking settings. - "raw_mime": Returns the grant_id, object, id, and raw_mime fields for each message.

search_query_native

A native provider search query for Google or Microsoft.

select

Comma-separated list of fields to return in the response. This allows you to receive only the portion of object data that you're interested in.

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
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
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
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
@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 which headers to include in the response. - "standard" (default): Returns the standard message payload. - "include_headers": Returns messages and their custom headers. - "include_tracking_options": Returns messages and their tracking settings. - "raw_mime": Returns the grant_id, object, id, and raw_mime fields for each message.

select NotRequired[str]

Comma-separated list of fields to return in the response. This allows you to receive only the portion of object data that you're interested in.

Source code in nylas/models/messages.py
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
class FindMessageQueryParams(TypedDict):
    """
    Query parameters for finding a message.

    Attributes:
        fields: Specify which headers to include in the response.
            - "standard" (default): Returns the standard message payload.
            - "include_headers": Returns messages and their custom headers.
            - "include_tracking_options": Returns messages and their tracking settings.
            - "raw_mime": Returns the grant_id, object, id, and raw_mime fields for each message.
        select: Comma-separated list of fields to return in the response.
            This allows you to receive only the portion of object data that you're interested in.
    """

    fields: NotRequired[Fields]
    select: NotRequired[str]

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.

tracking_options Optional[TrackingOptions]

The tracking options for the message.

raw_mime Optional[str]

A Base64url-encoded string containing the message data (including the body content).

Source code in nylas/models/messages.py
 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
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
@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.
        tracking_options: The tracking options for the message.
        raw_mime: A Base64url-encoded string containing the message data (including the body content).
    """

    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
    metadata: Optional[Dict[str, Any]] = None
    tracking_options: Optional[TrackingOptions] = None
    raw_mime: Optional[str] = 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
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
@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
200
201
202
203
204
205
206
207
208
209
210
211
212
@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
232
233
234
235
236
237
238
239
240
241
242
@dataclass_json
@dataclass
class StopScheduledMessageResponse:
    """
    The response from stopping a scheduled message.

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

    message: str

TrackingOptions dataclass

Message tracking options.

Attributes:

Name Type Description
opens Optional[bool]

When true, shows that message open tracking is enabled.

thread_replies Optional[bool]

When true, shows that thread replied tracking is enabled.

links Optional[bool]

When true, shows that link clicked tracking is enabled.

label Optional[str]

A label describing the message tracking purpose.

Source code in nylas/models/messages.py
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
@dataclass_json
@dataclass
class TrackingOptions:
    """
    Message tracking options.

    Attributes:
        opens: When true, shows that message open tracking is enabled.
        thread_replies: When true, shows that thread replied tracking is enabled.
        links: When true, shows that link clicked tracking is enabled.
        label: A label describing the message tracking purpose.
    """

    opens: Optional[bool] = None
    thread_replies: Optional[bool] = None
    links: Optional[bool] = None
    label: Optional[str] = None

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
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
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]]