Skip to content

calendars

Calendars

Bases: ListableApiResource, FindableApiResource, CreatableApiResource, UpdatableApiResource, DestroyableApiResource

Nylas Calendar API

The Nylas calendar API allows you to create new calendars or manage existing ones, as well as getting free/busy information for a calendar and getting availability for a calendar.

A calendar can be accessed by one, or several people, and can contain events.

Source code in nylas/resources/calendars.py 
 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
178
179
180
class Calendars(
    ListableApiResource,
    FindableApiResource,
    CreatableApiResource,
    UpdatableApiResource,
    DestroyableApiResource,
):
    """
    Nylas Calendar API

    The Nylas calendar API allows you to create new calendars or manage existing ones, as well as getting
    free/busy information for a calendar and getting availability for a calendar.

    A calendar can be accessed by one, or several people, and can contain events.
    """

    def list(
        self, identifier: str, query_params: ListCalendarsQueryParams = None
    ) -> ListResponse[Calendar]:
        """
        Return all Calendars.

        Args:
            identifier: The identifier of the Grant to act upon.
            query_params: The query parameters to include in the request.

        Returns:
            The list of Calendars.
        """

        return super().list(
            path=f"/v3/grants/{identifier}/calendars",
            query_params=query_params,
            response_type=Calendar,
        )

    def find(self, identifier: str, calendar_id: str) -> Response[Calendar]:
        """
        Return a Calendar.

        Args:
            identifier: The identifier of the Grant to act upon.
            calendar_id: The ID of the Calendar to retrieve.
                Use "primary" to refer to the primary Calendar associated with the Grant.

        Returns:
            The Calendar.
        """
        return super().find(
            path=f"/v3/grants/{identifier}/calendars/{calendar_id}",
            response_type=Calendar,
        )

    def create(
        self, identifier: str, request_body: CreateCalendarRequest
    ) -> Response[Calendar]:
        """
        Create a Calendar.

        Args:
            identifier: The identifier of the Grant to act upon.
            request_body: The values to create the Calendar with.

        Returns:
            The created Calendar.
        """
        return super().create(
            path=f"/v3/grants/{identifier}/calendars",
            response_type=Calendar,
            request_body=request_body,
        )

    def update(
        self, identifier: str, calendar_id: str, request_body: UpdateCalendarRequest
    ) -> Response[Calendar]:
        """
        Update a Calendar.

        Args:
            identifier: The identifier of the Grant to act upon.
            calendar_id: The ID of the Calendar to update.
                Use "primary" to refer to the primary Calendar associated with the Grant.
            request_body: The values to update the Calendar with.

        Returns:
            The updated Calendar.
        """
        return super().update(
            path=f"/v3/grants/{identifier}/calendars/{calendar_id}",
            response_type=Calendar,
            request_body=request_body,
        )

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

        Args:
            identifier: The identifier of the Grant to act upon.
            calendar_id: The ID of the Calendar to delete.
                Use "primary" to refer to the primary Calendar associated with the Grant.

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

    def get_availability(
        self, request_body: GetAvailabilityRequest
    ) -> Response[GetAvailabilityResponse]:
        """
        Get availability for a Calendar.

        Args:
            request_body: The request body to send to the API.

        Returns:
            Response: The availability response from the API.
        """
        json_response = self._http_client._execute(
            method="POST",
            path="/v3/calendars/availability",
            request_body=request_body,
        )

        return Response.from_dict(json_response, GetAvailabilityResponse)

    def get_free_busy(
        self, identifier: str, request_body: GetFreeBusyRequest
    ) -> Response[List[GetFreeBusyResponse]]:
        """
        Get free/busy info for a Calendar.

        Args:
            identifier: The grant ID or email account to get free/busy for.
            request_body: The request body to send to the API.

        Returns:
            Response: The free/busy response from the API.
        """
        json_response = self._http_client._execute(
            method="POST",
            path=f"/v3/grants/{identifier}/calendars/free-busy",
            request_body=request_body,
        )

        data = []
        request_id = json_response["request_id"]
        for item in json_response["data"]:
            if item.get("object") == "error":
                data.append(FreeBusyError.from_dict(item))
            else:
                data.append(FreeBusy.from_dict(item))

        return Response(data, request_id)

create(identifier, request_body)

Create a Calendar.

Parameters:

Name Type Description Default
identifier str

The identifier of the Grant to act upon.

 required
request_body CreateCalendarRequest

The values to create the Calendar with.

 required

Returns:

Type Description
Response[Calendar]

The created Calendar.
Source code in nylas/resources/calendars.py 
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
def create(
    self, identifier: str, request_body: CreateCalendarRequest
) -> Response[Calendar]:
    """
    Create a Calendar.

    Args:
        identifier: The identifier of the Grant to act upon.
        request_body: The values to create the Calendar with.

    Returns:
        The created Calendar.
    """
    return super().create(
        path=f"/v3/grants/{identifier}/calendars",
        response_type=Calendar,
        request_body=request_body,
    )

destroy(identifier, calendar_id)

Delete a Calendar.

Parameters:

Name Type Description Default
identifier str

The identifier of the Grant to act upon.

 required
calendar_id str

The ID of the Calendar to delete. Use "primary" to refer to the primary Calendar associated with the Grant.

 required

Returns:

Type Description
DeleteResponse

The deletion response.
Source code in nylas/resources/calendars.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
def destroy(self, identifier: str, calendar_id: str) -> DeleteResponse:
    """
    Delete a Calendar.

    Args:
        identifier: The identifier of the Grant to act upon.
        calendar_id: The ID of the Calendar to delete.
            Use "primary" to refer to the primary Calendar associated with the Grant.

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

find(identifier, calendar_id)

Return a Calendar.

Parameters:

Name Type Description Default
identifier str

The identifier of the Grant to act upon.

 required
calendar_id str

The ID of the Calendar to retrieve. Use "primary" to refer to the primary Calendar associated with the Grant.

 required

Returns:

Type Description
Response[Calendar]

The Calendar.
Source code in nylas/resources/calendars.py 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
def find(self, identifier: str, calendar_id: str) -> Response[Calendar]:
    """
    Return a Calendar.

    Args:
        identifier: The identifier of the Grant to act upon.
        calendar_id: The ID of the Calendar to retrieve.
            Use "primary" to refer to the primary Calendar associated with the Grant.

    Returns:
        The Calendar.
    """
    return super().find(
        path=f"/v3/grants/{identifier}/calendars/{calendar_id}",
        response_type=Calendar,
    )

get_availability(request_body)

Get availability for a Calendar.

Parameters:

Name Type Description Default
request_body GetAvailabilityRequest

The request body to send to the API.

 required

Returns:

Name Type Description
Response Response[GetAvailabilityResponse]

The availability response from the API.
Source code in nylas/resources/calendars.py 
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
def get_availability(
    self, request_body: GetAvailabilityRequest
) -> Response[GetAvailabilityResponse]:
    """
    Get availability for a Calendar.

    Args:
        request_body: The request body to send to the API.

    Returns:
        Response: The availability response from the API.
    """
    json_response = self._http_client._execute(
        method="POST",
        path="/v3/calendars/availability",
        request_body=request_body,
    )

    return Response.from_dict(json_response, GetAvailabilityResponse)

get_free_busy(identifier, request_body)

Get free/busy info for a Calendar.

Parameters:

Name Type Description Default
identifier str

The grant ID or email account to get free/busy for.

 required
request_body GetFreeBusyRequest

The request body to send to the API.

 required

Returns:

Name Type Description
Response Response[List[GetFreeBusyResponse]]

The free/busy response from the API.
Source code in nylas/resources/calendars.py 
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
178
179
180
def get_free_busy(
    self, identifier: str, request_body: GetFreeBusyRequest
) -> Response[List[GetFreeBusyResponse]]:
    """
    Get free/busy info for a Calendar.

    Args:
        identifier: The grant ID or email account to get free/busy for.
        request_body: The request body to send to the API.

    Returns:
        Response: The free/busy response from the API.
    """
    json_response = self._http_client._execute(
        method="POST",
        path=f"/v3/grants/{identifier}/calendars/free-busy",
        request_body=request_body,
    )

    data = []
    request_id = json_response["request_id"]
    for item in json_response["data"]:
        if item.get("object") == "error":
            data.append(FreeBusyError.from_dict(item))
        else:
            data.append(FreeBusy.from_dict(item))

    return Response(data, request_id)

list(identifier, query_params=None)

Return all Calendars.

Parameters:

Name Type Description Default
identifier str

The identifier of the Grant to act upon.

 required
query_params ListCalendarsQueryParams

The query parameters to include in the request.

 None

Returns:

Type Description
ListResponse[Calendar]

The list of Calendars.
Source code in nylas/resources/calendars.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
def list(
    self, identifier: str, query_params: ListCalendarsQueryParams = None
) -> ListResponse[Calendar]:
    """
    Return all Calendars.

    Args:
        identifier: The identifier of the Grant to act upon.
        query_params: The query parameters to include in the request.

    Returns:
        The list of Calendars.
    """

    return super().list(
        path=f"/v3/grants/{identifier}/calendars",
        query_params=query_params,
        response_type=Calendar,
    )

update(identifier, calendar_id, request_body)

Update a Calendar.

Parameters:

Name Type Description Default
identifier str

The identifier of the Grant to act upon.

 required
calendar_id str

The ID of the Calendar to update. Use "primary" to refer to the primary Calendar associated with the Grant.

 required
request_body UpdateCalendarRequest

The values to update the Calendar with.

 required

Returns:

Type Description
Response[Calendar]

The updated Calendar.
Source code in nylas/resources/calendars.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
def update(
    self, identifier: str, calendar_id: str, request_body: UpdateCalendarRequest
) -> Response[Calendar]:
    """
    Update a Calendar.

    Args:
        identifier: The identifier of the Grant to act upon.
        calendar_id: The ID of the Calendar to update.
            Use "primary" to refer to the primary Calendar associated with the Grant.
        request_body: The values to update the Calendar with.

    Returns:
        The updated Calendar.
    """
    return super().update(
        path=f"/v3/grants/{identifier}/calendars/{calendar_id}",
        response_type=Calendar,
        request_body=request_body,
    )