Skip to content

attachments

Attachments

Bases: FindableApiResource, CreatableApiResource

Nylas Attachments API

The Nylas Attachments API allows you to get metadata ot, and download attachments from messages.

Source code in nylas/resources/attachments.py 
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 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
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
class Attachments(
    FindableApiResource,
    CreatableApiResource,
):
    """
    Nylas Attachments API

    The Nylas Attachments API allows you to get metadata ot, and download attachments from messages.
    """

    def find(
        self,
        identifier: str,
        attachment_id: str,
        query_params: FindAttachmentQueryParams,
        overrides: RequestOverrides = None,
    ) -> NylasResponse[Attachment]:
        """
        Return metadata of an attachment.

        Args:
            identifier: The identifier of the Grant to act upon.
            attachment_id: The id of the attachment to retrieve.
            query_params: The query parameters to include in the request.
            overrides: The request overrides to use for the request.

        Returns:
            The attachment metadata.
        """
        return super().find(
            path=f"/v3/grants/{identifier}/attachments/{attachment_id}",
            response_type=Attachment,
            query_params=query_params,
            overrides=overrides,
        )

    def download(
        self,
        identifier: str,
        attachment_id: str,
        query_params: FindAttachmentQueryParams,
        overrides: RequestOverrides = None,
    ) -> Response:
        """
        Download the attachment data.

        This function returns a raw response object to allow you the ability
        to stream the file contents. The response object should be closed
        after use to ensure the connection is closed.

        Args:
            identifier: The identifier of the Grant to act upon.
            attachment_id: The id of the attachment to download.
            query_params: The query parameters to include in the request.
            overrides: The request overrides to use for the request.

        Returns:
            The Response object containing the file data.

        Example:
            Here is an example of how to use this function when streaming:

            ```python
                response = execute_request_raw_response(url, method, stream=True)
                try:
                    for chunk in response.iter_content(chunk_size=8192):
                        if chunk:
                            # Process each chunk
                            pass
                finally:
                    response.close()  # Ensure the response is closed
            ```
        """
        return self._http_client._execute_download_request(
            path=f"/v3/grants/{identifier}/attachments/{attachment_id}/download",
            query_params=query_params,
            stream=True,
            overrides=overrides,
        )

    def download_bytes(
        self,
        identifier: str,
        attachment_id: str,
        query_params: FindAttachmentQueryParams,
        overrides: RequestOverrides = None,
    ) -> bytes:
        """
        Download the attachment as a byte array.

        Args:
            identifier: The identifier of the Grant to act upon.
            attachment_id: The id of the attachment to download.
            query_params: The query parameters to include in the request.
            overrides: The request overrides to use for the request.

        Returns:
            The raw file data.
        """
        return self._http_client._execute_download_request(
            path=f"/v3/grants/{identifier}/attachments/{attachment_id}/download",
            query_params=query_params,
            stream=False,
            overrides=overrides,
        )

    def create_upload_session(
        self,
        identifier: str,
        request_body: CreateAttachmentUploadSessionRequest,
        overrides: RequestOverrides = None,
    ) -> NylasResponse[AttachmentUploadSession]:
        """
        Create a resumable upload session for a large attachment (up to 150 MB).

        After receiving the session, upload file bytes via HTTP PUT to the returned
        `url` (include the returned `headers`; no Nylas auth header needed), then
        call complete_upload_session() with the returned `attachment_id`.

        Args:
            identifier: The identifier of the Grant to act upon.
            request_body: Session parameters (filename, content_type, optional size).
            overrides: The request overrides to use for the request.

        Returns:
            The upload session, including the pre-signed URL and attachment_id.
        """
        return super().create(
            path=f"/v3/grants/{identifier}/attachment-uploads",
            response_type=AttachmentUploadSession,
            request_body=request_body,
            overrides=overrides,
        )

    def complete_upload_session(
        self,
        identifier: str,
        attachment_id: str,
        overrides: RequestOverrides = None,
    ) -> NylasResponse[AttachmentUploadSessionComplete]:
        """
        Complete an upload session after file bytes have been PUT to the pre-signed URL.

        Use the `attachment_id` from the completed session when referencing the
        attachment in a subsequent messages.send() or drafts.create() call.

        Args:
            identifier: The identifier of the Grant to act upon.
            attachment_id: The upload session ID returned by create_upload_session().
            overrides: The request overrides to use for the request.

        Returns:
            The completed session status.
        """
        return super().create(
            path=f"/v3/grants/{identifier}/attachment-uploads/{attachment_id}/complete",
            response_type=AttachmentUploadSessionComplete,
            request_body={},
            overrides=overrides,
        )

complete_upload_session(identifier, attachment_id, overrides=None)

Complete an upload session after file bytes have been PUT to the pre-signed URL.

Use the attachment_id from the completed session when referencing the attachment in a subsequent messages.send() or drafts.create() call.

Parameters:

Name Type Description Default
identifier str

The identifier of the Grant to act upon.

 required
attachment_id str

The upload session ID returned by create_upload_session().

 required
overrides RequestOverrides

The request overrides to use for the request.

 None

Returns:

Type Description
Response[AttachmentUploadSessionComplete]

The completed session status.
Source code in nylas/resources/attachments.py 
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
def complete_upload_session(
    self,
    identifier: str,
    attachment_id: str,
    overrides: RequestOverrides = None,
) -> NylasResponse[AttachmentUploadSessionComplete]:
    """
    Complete an upload session after file bytes have been PUT to the pre-signed URL.

    Use the `attachment_id` from the completed session when referencing the
    attachment in a subsequent messages.send() or drafts.create() call.

    Args:
        identifier: The identifier of the Grant to act upon.
        attachment_id: The upload session ID returned by create_upload_session().
        overrides: The request overrides to use for the request.

    Returns:
        The completed session status.
    """
    return super().create(
        path=f"/v3/grants/{identifier}/attachment-uploads/{attachment_id}/complete",
        response_type=AttachmentUploadSessionComplete,
        request_body={},
        overrides=overrides,
    )

create_upload_session(identifier, request_body, overrides=None)

Create a resumable upload session for a large attachment (up to 150 MB).

After receiving the session, upload file bytes via HTTP PUT to the returned url (include the returned headers; no Nylas auth header needed), then call complete_upload_session() with the returned attachment_id.

Parameters:

Name Type Description Default
identifier str

The identifier of the Grant to act upon.

 required
request_body CreateAttachmentUploadSessionRequest

Session parameters (filename, content_type, optional size).

 required
overrides RequestOverrides

The request overrides to use for the request.

 None

Returns:

Type Description
Response[AttachmentUploadSession]

The upload session, including the pre-signed URL and attachment_id.
Source code in nylas/resources/attachments.py 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
def create_upload_session(
    self,
    identifier: str,
    request_body: CreateAttachmentUploadSessionRequest,
    overrides: RequestOverrides = None,
) -> NylasResponse[AttachmentUploadSession]:
    """
    Create a resumable upload session for a large attachment (up to 150 MB).

    After receiving the session, upload file bytes via HTTP PUT to the returned
    `url` (include the returned `headers`; no Nylas auth header needed), then
    call complete_upload_session() with the returned `attachment_id`.

    Args:
        identifier: The identifier of the Grant to act upon.
        request_body: Session parameters (filename, content_type, optional size).
        overrides: The request overrides to use for the request.

    Returns:
        The upload session, including the pre-signed URL and attachment_id.
    """
    return super().create(
        path=f"/v3/grants/{identifier}/attachment-uploads",
        response_type=AttachmentUploadSession,
        request_body=request_body,
        overrides=overrides,
    )

download(identifier, attachment_id, query_params, overrides=None)

Download the attachment data.

This function returns a raw response object to allow you the ability to stream the file contents. The response object should be closed after use to ensure the connection is closed.

Parameters:

Name Type Description Default
identifier str

The identifier of the Grant to act upon.

 required
attachment_id str

The id of the attachment to download.

 required
query_params FindAttachmentQueryParams

The query parameters to include in the request.

 required
overrides RequestOverrides

The request overrides to use for the request.

 None

Returns:

Type Description
Response

The Response object containing the file data.
Example

Here is an example of how to use this function when streaming:

    response = execute_request_raw_response(url, method, stream=True)
    try:
        for chunk in response.iter_content(chunk_size=8192):
            if chunk:
                # Process each chunk
                pass
    finally:
        response.close()  # Ensure the response is closed
Source code in nylas/resources/attachments.py 
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
def download(
    self,
    identifier: str,
    attachment_id: str,
    query_params: FindAttachmentQueryParams,
    overrides: RequestOverrides = None,
) -> Response:
    """
    Download the attachment data.

    This function returns a raw response object to allow you the ability
    to stream the file contents. The response object should be closed
    after use to ensure the connection is closed.

    Args:
        identifier: The identifier of the Grant to act upon.
        attachment_id: The id of the attachment to download.
        query_params: The query parameters to include in the request.
        overrides: The request overrides to use for the request.

    Returns:
        The Response object containing the file data.

    Example:
        Here is an example of how to use this function when streaming:

        ```python
            response = execute_request_raw_response(url, method, stream=True)
            try:
                for chunk in response.iter_content(chunk_size=8192):
                    if chunk:
                        # Process each chunk
                        pass
            finally:
                response.close()  # Ensure the response is closed
        ```
    """
    return self._http_client._execute_download_request(
        path=f"/v3/grants/{identifier}/attachments/{attachment_id}/download",
        query_params=query_params,
        stream=True,
        overrides=overrides,
    )

download_bytes(identifier, attachment_id, query_params, overrides=None)

Download the attachment as a byte array.

Parameters:

Name Type Description Default
identifier str

The identifier of the Grant to act upon.

 required
attachment_id str

The id of the attachment to download.

 required
query_params FindAttachmentQueryParams

The query parameters to include in the request.

 required
overrides RequestOverrides

The request overrides to use for the request.

 None

Returns:

Type Description
bytes

The raw file data.
Source code in nylas/resources/attachments.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def download_bytes(
    self,
    identifier: str,
    attachment_id: str,
    query_params: FindAttachmentQueryParams,
    overrides: RequestOverrides = None,
) -> bytes:
    """
    Download the attachment as a byte array.

    Args:
        identifier: The identifier of the Grant to act upon.
        attachment_id: The id of the attachment to download.
        query_params: The query parameters to include in the request.
        overrides: The request overrides to use for the request.

    Returns:
        The raw file data.
    """
    return self._http_client._execute_download_request(
        path=f"/v3/grants/{identifier}/attachments/{attachment_id}/download",
        query_params=query_params,
        stream=False,
        overrides=overrides,
    )

find(identifier, attachment_id, query_params, overrides=None)

Return metadata of an attachment.

Parameters:

Name Type Description Default
identifier str

The identifier of the Grant to act upon.

 required
attachment_id str

The id of the attachment to retrieve.

 required
query_params FindAttachmentQueryParams

The query parameters to include in the request.

 required
overrides RequestOverrides

The request overrides to use for the request.

 None

Returns:

Type Description
Response[Attachment]

The attachment metadata.
Source code in nylas/resources/attachments.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
def find(
    self,
    identifier: str,
    attachment_id: str,
    query_params: FindAttachmentQueryParams,
    overrides: RequestOverrides = None,
) -> NylasResponse[Attachment]:
    """
    Return metadata of an attachment.

    Args:
        identifier: The identifier of the Grant to act upon.
        attachment_id: The id of the attachment to retrieve.
        query_params: The query parameters to include in the request.
        overrides: The request overrides to use for the request.

    Returns:
        The attachment metadata.
    """
    return super().find(
        path=f"/v3/grants/{identifier}/attachments/{attachment_id}",
        response_type=Attachment,
        query_params=query_params,
        overrides=overrides,
    )