messages

Messages

Bases: ListableApiResource, FindableApiResource, UpdatableApiResource, DestroyableApiResource

Nylas Messages API

The messages API allows you to send, find, update, and delete messages. You can also use the messages API to schedule messages to be sent at a later time. The Smart Compose API, allowing you to generate email content using machine learning, is also available.

Source code in nylas/resources/messages.py

class Messages(
    ListableApiResource,
    FindableApiResource,
    UpdatableApiResource,
    DestroyableApiResource,
):
    """
    Nylas Messages API

    The messages API allows you to send, find, update, and delete messages.
    You can also use the messages API to schedule messages to be sent at a later time.
    The Smart Compose API, allowing you to generate email content using machine learning, is also available.
    """

    @property
    def smart_compose(self) -> SmartCompose:
        """
        Access the Smart Compose collection of endpoints.

        Returns:
            The Smart Compose collection of endpoints.
        """
        return SmartCompose(self._http_client)

    def list(
        self, identifier: str, query_params: Optional[ListMessagesQueryParams] = None
    ) -> ListResponse[Message]:
        """
        Return all Messages.

        Args:
            identifier: The identifier of the grant to get messages for.
            query_params: The query parameters to filter messages by.

        Returns:
            A list of Messages.
        """
        return super().list(
            path=f"/v3/grants/{identifier}/messages",
            response_type=Message,
            query_params=query_params,
        )

    def find(
        self,
        identifier: str,
        message_id: str,
        query_params: Optional[FindMessageQueryParams] = None,
    ) -> Response[Message]:
        """
        Return a Message.

        Args:
            identifier: The identifier of the grant to get the message for.
            message_id: The identifier of the message to get.
            query_params: The query parameters to include in the request.

        Returns:
            The requested Message.
        """
        return super().find(
            path=f"/v3/grants/{identifier}/messages/{message_id}",
            response_type=Message,
            query_params=query_params,
        )

    def update(
        self,
        identifier: str,
        message_id: str,
        request_body: UpdateMessageRequest,
    ) -> Response[Message]:
        """
        Update a Message.

        Args:
            identifier: The identifier of the grant to update the message for.
            message_id: The identifier of the message to update.
            request_body: The request body to update the message with.

        Returns:
            The updated Message.
        """
        return super().update(
            path=f"/v3/grants/{identifier}/messages/{message_id}",
            response_type=Message,
            request_body=request_body,
        )

    def destroy(self, identifier: str, message_id: str) -> DeleteResponse:
        """
        Delete a Message.

        Args:
            identifier: The identifier of the grant to delete the message for.
            message_id: The identifier of the message to delete.

        Returns:
            The deletion response.
        """
        return super().destroy(
            path=f"/v3/grants/{identifier}/messages/{message_id}",
        )

    def send(
        self, identifier: str, request_body: SendMessageRequest
    ) -> Response[Message]:
        """
        Send a Message.

        Args:
            identifier: The identifier of the grant to send the message for.
            request_body: The request body to send the message with.

        Returns:
            The sent message.
        """
        path = f"/v3/grants/{identifier}/messages/send"
        form_data = None
        json_body = None

        # Use form data only if the attachment size is greater than 3mb
        attachment_size = sum(
            attachment.get("size", 0)
            for attachment in request_body.get("attachments", [])
        )
        if attachment_size >= MAXIMUM_JSON_ATTACHMENT_SIZE:
            form_data = _build_form_request(request_body)
        else:
            # Encode the content of the attachments to base64
            for attachment in request_body.get("attachments", []):
                if issubclass(type(attachment["content"]), io.IOBase):
                    attachment["content"] = encode_stream_to_base64(
                        attachment["content"]
                    )

            json_body = request_body

        json_response = self._http_client._execute(
            method="POST",
            path=path,
            request_body=json_body,
            data=form_data,
        )

        return Response.from_dict(json_response, Message)

    def list_scheduled_messages(
        self, identifier: str
    ) -> Response[List[ScheduledMessage]]:
        """
        Retrieve your scheduled messages.

        Args:
            identifier: The identifier of the grant to delete the message for.

        Returns:
            Response: The list of scheduled messages.
        """
        json_response = self._http_client._execute(
            method="GET",
            path=f"/v3/grants/{identifier}/messages/schedules",
        )

        data = []
        request_id = json_response["request_id"]
        for item in json_response["data"]:
            data.append(ScheduledMessage.from_dict(item))

        return Response(data, request_id)

    def find_scheduled_message(
        self, identifier: str, schedule_id: str
    ) -> Response[ScheduledMessage]:
        """
        Retrieve your scheduled messages.

        Args:
            identifier: The identifier of the grant to delete the message for.
            schedule_id: The id of the scheduled message to retrieve.

        Returns:
            Response: The scheduled message.
        """
        json_response = self._http_client._execute(
            method="GET",
            path=f"/v3/grants/{identifier}/messages/schedules/{schedule_id}",
        )

        return Response.from_dict(json_response, ScheduledMessage)

    def stop_scheduled_message(
        self, identifier: str, schedule_id: str
    ) -> Response[StopScheduledMessageResponse]:
        """
        Stop a scheduled message.

        Args:
            identifier: The identifier of the grant to delete the message for.
            schedule_id: The id of the scheduled message to stop.

        Returns:
            Response: The confirmation of the stopped scheduled message.
        """
        json_response = self._http_client._execute(
            method="DELETE",
            path=f"/v3/grants/{identifier}/messages/schedules/{schedule_id}",
        )

        return Response.from_dict(json_response, StopScheduledMessageResponse)

    def clean_messages(
        self, identifier: str, request_body: CleanMessagesRequest
    ) -> ListResponse[CleanMessagesResponse]:
        """
        Remove extra information from a list of messages.

        Args:
            identifier: The identifier of the grant to clean the message for.
            request_body: The values to clean the message with.

        Returns:
            The list of cleaned messages.
        """
        json_resposne = self._http_client._execute(
            method="PUT",
            path=f"/v3/grants/{identifier}/messages/clean",
            request_body=request_body,
        )

        return ListResponse.from_dict(json_resposne, CleanMessagesResponse)

smart_compose: SmartCompose property

Access the Smart Compose collection of endpoints.

Returns:

Type	Description
SmartCompose	The Smart Compose collection of endpoints.

clean_messages(identifier, request_body)

Remove extra information from a list of messages.

Parameters:

Name	Type	Description	Default
identifier	str	The identifier of the grant to clean the message for.	required
request_body	CleanMessagesRequest	The values to clean the message with.	required

Returns:

Type	Description
ListResponse[CleanMessagesResponse]	The list of cleaned messages.

Source code in nylas/resources/messages.py

def clean_messages(
    self, identifier: str, request_body: CleanMessagesRequest
) -> ListResponse[CleanMessagesResponse]:
    """
    Remove extra information from a list of messages.

    Args:
        identifier: The identifier of the grant to clean the message for.
        request_body: The values to clean the message with.

    Returns:
        The list of cleaned messages.
    """
    json_resposne = self._http_client._execute(
        method="PUT",
        path=f"/v3/grants/{identifier}/messages/clean",
        request_body=request_body,
    )

    return ListResponse.from_dict(json_resposne, CleanMessagesResponse)

destroy(identifier, message_id)

Delete a Message.

Parameters:

Name	Type	Description	Default
identifier	str	The identifier of the grant to delete the message for.	required
message_id	str	The identifier of the message to delete.	required

Returns:

Type	Description
DeleteResponse	The deletion response.

Source code in nylas/resources/messages.py

def destroy(self, identifier: str, message_id: str) -> DeleteResponse:
    """
    Delete a Message.

    Args:
        identifier: The identifier of the grant to delete the message for.
        message_id: The identifier of the message to delete.

    Returns:
        The deletion response.
    """
    return super().destroy(
        path=f"/v3/grants/{identifier}/messages/{message_id}",
    )

find(identifier, message_id, query_params=None)

Return a Message.

Parameters:

Name	Type	Description	Default
identifier	str	The identifier of the grant to get the message for.	required
message_id	str	The identifier of the message to get.	required
query_params	Optional[FindMessageQueryParams]	The query parameters to include in the request.	None

Returns:

Type	Description
Response[Message]	The requested Message.

Source code in nylas/resources/messages.py

def find(
    self,
    identifier: str,
    message_id: str,
    query_params: Optional[FindMessageQueryParams] = None,
) -> Response[Message]:
    """
    Return a Message.

    Args:
        identifier: The identifier of the grant to get the message for.
        message_id: The identifier of the message to get.
        query_params: The query parameters to include in the request.

    Returns:
        The requested Message.
    """
    return super().find(
        path=f"/v3/grants/{identifier}/messages/{message_id}",
        response_type=Message,
        query_params=query_params,
    )

find_scheduled_message(identifier, schedule_id)

Retrieve your scheduled messages.

Parameters:

Name	Type	Description	Default
identifier	str	The identifier of the grant to delete the message for.	required
schedule_id	str	The id of the scheduled message to retrieve.	required

Returns:

Name	Type	Description
Response	Response[ScheduledMessage]	The scheduled message.

Source code in nylas/resources/messages.py

def find_scheduled_message(
    self, identifier: str, schedule_id: str
) -> Response[ScheduledMessage]:
    """
    Retrieve your scheduled messages.

    Args:
        identifier: The identifier of the grant to delete the message for.
        schedule_id: The id of the scheduled message to retrieve.

    Returns:
        Response: The scheduled message.
    """
    json_response = self._http_client._execute(
        method="GET",
        path=f"/v3/grants/{identifier}/messages/schedules/{schedule_id}",
    )

    return Response.from_dict(json_response, ScheduledMessage)

list(identifier, query_params=None)

Return all Messages.

Parameters:

Name	Type	Description	Default
identifier	str	The identifier of the grant to get messages for.	required
query_params	Optional[ListMessagesQueryParams]	The query parameters to filter messages by.	None

Returns:

Type	Description
ListResponse[Message]	A list of Messages.

Source code in nylas/resources/messages.py

def list(
    self, identifier: str, query_params: Optional[ListMessagesQueryParams] = None
) -> ListResponse[Message]:
    """
    Return all Messages.

    Args:
        identifier: The identifier of the grant to get messages for.
        query_params: The query parameters to filter messages by.

    Returns:
        A list of Messages.
    """
    return super().list(
        path=f"/v3/grants/{identifier}/messages",
        response_type=Message,
        query_params=query_params,
    )

list_scheduled_messages(identifier)

Retrieve your scheduled messages.

Parameters:

Name	Type	Description	Default
identifier	str	The identifier of the grant to delete the message for.	required

Returns:

Name	Type	Description
Response	Response[List[ScheduledMessage]]	The list of scheduled messages.

Source code in nylas/resources/messages.py

def list_scheduled_messages(
    self, identifier: str
) -> Response[List[ScheduledMessage]]:
    """
    Retrieve your scheduled messages.

    Args:
        identifier: The identifier of the grant to delete the message for.

    Returns:
        Response: The list of scheduled messages.
    """
    json_response = self._http_client._execute(
        method="GET",
        path=f"/v3/grants/{identifier}/messages/schedules",
    )

    data = []
    request_id = json_response["request_id"]
    for item in json_response["data"]:
        data.append(ScheduledMessage.from_dict(item))

    return Response(data, request_id)

send(identifier, request_body)

Send a Message.

Parameters:

Name	Type	Description	Default
identifier	str	The identifier of the grant to send the message for.	required
request_body	SendMessageRequest	The request body to send the message with.	required

Returns:

Type	Description
Response[Message]	The sent message.

Source code in nylas/resources/messages.py

def send(
    self, identifier: str, request_body: SendMessageRequest
) -> Response[Message]:
    """
    Send a Message.

    Args:
        identifier: The identifier of the grant to send the message for.
        request_body: The request body to send the message with.

    Returns:
        The sent message.
    """
    path = f"/v3/grants/{identifier}/messages/send"
    form_data = None
    json_body = None

    # Use form data only if the attachment size is greater than 3mb
    attachment_size = sum(
        attachment.get("size", 0)
        for attachment in request_body.get("attachments", [])
    )
    if attachment_size >= MAXIMUM_JSON_ATTACHMENT_SIZE:
        form_data = _build_form_request(request_body)
    else:
        # Encode the content of the attachments to base64
        for attachment in request_body.get("attachments", []):
            if issubclass(type(attachment["content"]), io.IOBase):
                attachment["content"] = encode_stream_to_base64(
                    attachment["content"]
                )

        json_body = request_body

    json_response = self._http_client._execute(
        method="POST",
        path=path,
        request_body=json_body,
        data=form_data,
    )

    return Response.from_dict(json_response, Message)

stop_scheduled_message(identifier, schedule_id)

Stop a scheduled message.

Parameters:

Name	Type	Description	Default
identifier	str	The identifier of the grant to delete the message for.	required
schedule_id	str	The id of the scheduled message to stop.	required

Returns:

Name	Type	Description
Response	Response[StopScheduledMessageResponse]	The confirmation of the stopped scheduled message.

Source code in nylas/resources/messages.py

def stop_scheduled_message(
    self, identifier: str, schedule_id: str
) -> Response[StopScheduledMessageResponse]:
    """
    Stop a scheduled message.

    Args:
        identifier: The identifier of the grant to delete the message for.
        schedule_id: The id of the scheduled message to stop.

    Returns:
        Response: The confirmation of the stopped scheduled message.
    """
    json_response = self._http_client._execute(
        method="DELETE",
        path=f"/v3/grants/{identifier}/messages/schedules/{schedule_id}",
    )

    return Response.from_dict(json_response, StopScheduledMessageResponse)

update(identifier, message_id, request_body)

Update a Message.

Parameters:

Name	Type	Description	Default
identifier	str	The identifier of the grant to update the message for.	required
message_id	str	The identifier of the message to update.	required
request_body	UpdateMessageRequest	The request body to update the message with.	required

Returns:

Type	Description
Response[Message]	The updated Message.

Source code in nylas/resources/messages.py

def update(
    self,
    identifier: str,
    message_id: str,
    request_body: UpdateMessageRequest,
) -> Response[Message]:
    """
    Update a Message.

    Args:
        identifier: The identifier of the grant to update the message for.
        message_id: The identifier of the message to update.
        request_body: The request body to update the message with.

    Returns:
        The updated Message.
    """
    return super().update(
        path=f"/v3/grants/{identifier}/messages/{message_id}",
        response_type=Message,
        request_body=request_body,
    )