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 
 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
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
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,
        overrides: RequestOverrides = 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.
            overrides: The request overrides to use for the request.

        Returns:
            The list of Calendars.
        """

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

    def find(
        self, identifier: str, calendar_id: str, overrides: RequestOverrides = None
    ) -> 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.
            overrides: The request overrides to use for the request.

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

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

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

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

    def update(
        self,
        identifier: str,
        calendar_id: str,
        request_body: UpdateCalendarRequest,
        overrides: RequestOverrides = None,
    ) -> 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.
            overrides: The request overrides to use for the request.

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

    def destroy(
        self, identifier: str, calendar_id: str, overrides: RequestOverrides = None
    ) -> 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.
            overrides: The request overrides to use for the request.

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

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

        Args:
            request_body: The request body to send to the API.
            overrides: The request overrides to use for the request.

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

        return Response.from_dict(json_response, GetAvailabilityResponse)

    def get_free_busy(
        self,
        identifier: str,
        request_body: GetFreeBusyRequest,
        overrides: RequestOverrides = None,
    ) -> 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.
            overrides: The request overrides to use for the request.

        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,
            overrides=overrides,
        )

        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, overrides=None)

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
overrides RequestOverrides

The request overrides to use for the request.

 None

Returns:

Type Description
Response[Calendar]

The created Calendar.
Source code in nylas/resources/calendars.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
def create(
    self,
    identifier: str,
    request_body: CreateCalendarRequest,
    overrides: RequestOverrides = None,
) -> Response[Calendar]:
    """
    Create a Calendar.

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

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

destroy(identifier, calendar_id, overrides=None)

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
overrides RequestOverrides

The request overrides to use for the request.

 None

Returns:

Type Description
DeleteResponse

The deletion response.
Source code in nylas/resources/calendars.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
def destroy(
    self, identifier: str, calendar_id: str, overrides: RequestOverrides = None
) -> 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.
        overrides: The request overrides to use for the request.

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

find(identifier, calendar_id, overrides=None)

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
overrides RequestOverrides

The request overrides to use for the request.

 None

Returns:

Type Description
Response[Calendar]

The Calendar.
Source code in nylas/resources/calendars.py 
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def find(
    self, identifier: str, calendar_id: str, overrides: RequestOverrides = None
) -> 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.
        overrides: The request overrides to use for the request.

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

get_availability(request_body, overrides=None)

Get availability for a Calendar.

Parameters:

Name Type Description Default
request_body GetAvailabilityRequest

The request body to send to the API.

 required
overrides RequestOverrides

The request overrides to use for the request.

 None

Returns:

Name Type Description
Response Response[GetAvailabilityResponse]

The availability response from the API.
Source code in nylas/resources/calendars.py 
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
def get_availability(
    self, request_body: GetAvailabilityRequest, overrides: RequestOverrides = None
) -> Response[GetAvailabilityResponse]:
    """
    Get availability for a Calendar.

    Args:
        request_body: The request body to send to the API.
        overrides: The request overrides to use for the request.

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

    return Response.from_dict(json_response, GetAvailabilityResponse)

get_free_busy(identifier, request_body, overrides=None)

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
overrides RequestOverrides

The request overrides to use for the request.

 None

Returns:

Name Type Description
Response Response[List[GetFreeBusyResponse]]

The free/busy response from the API.
Source code in nylas/resources/calendars.py 
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
def get_free_busy(
    self,
    identifier: str,
    request_body: GetFreeBusyRequest,
    overrides: RequestOverrides = None,
) -> 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.
        overrides: The request overrides to use for the request.

    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,
        overrides=overrides,
    )

    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, overrides=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
overrides RequestOverrides

The request overrides to use for the request.

 None

Returns:

Type Description
ListResponse[Calendar]

The list of Calendars.
Source code in nylas/resources/calendars.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
def list(
    self,
    identifier: str,
    query_params: ListCalendarsQueryParams = None,
    overrides: RequestOverrides = 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.
        overrides: The request overrides to use for the request.

    Returns:
        The list of Calendars.
    """

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

update(identifier, calendar_id, request_body, overrides=None)

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
overrides RequestOverrides

The request overrides to use for the request.

 None

Returns:

Type Description
Response[Calendar]

The updated Calendar.
Source code in nylas/resources/calendars.py 
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
def update(
    self,
    identifier: str,
    calendar_id: str,
    request_body: UpdateCalendarRequest,
    overrides: RequestOverrides = None,
) -> 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.
        overrides: The request overrides to use for the request.

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