Outlook Calendar: Create a Recurring Event and List Its Instances
See more Outlook Calendar Examples
Create three daily one-hour appointments beginning tomorrow in UTC, then list the occurrences and exceptions for the next seven days. A recurring event combines a pattern with a range. Save the series-master ID separately from each occurrence ID. To modify one occurrence later, use that occurrence's ID; a change to the master applies to the series. The instances endpoint does not include cancelled occurrences.
UTC avoids ambiguous local clock times in this example. For a recurring appointment at a fixed local time, use a mailbox-supported time zone consistently in the start/end and recurrence range so daylight-saving transitions are interpreted by the calendar service.
Live creation: this posts a real calendar item. The request file is saved before sending, including its transactionId, and a receipt records the returned ID. Reuse the saved payload after an uncertain outcome; use a new filename pair for a deliberately new operation. A saved receipt prevents repeat creation on a later successful run. Keep request/receipt files private, per account, and use one writer. See the basic creation example for the same pattern.
Follow the complete @odata.nextLink, retain the same Prefer header on every page, and treat IDs as case-sensitive strings. The example checks the Graph host and repeated links, and has a 100-page demonstration limit. Save a continuation URL privately if a larger scan must resume.
Delegated permission: Calendars.ReadWrite.
Uses Microsoft Graph v1.0 in the global cloud with a delegated access token saved by the calendar OAuth2 example. Both personal Outlook.com accounts and Microsoft 365 work/school accounts with a mailbox can use this flow. The app registration must support the selected account type. A token for SMTP/IMAP/POP or another API is not a Graph token.
/me means the signed-in user and requires delegated authentication. An unattended Microsoft 365 service instead needs application permissions and administrator consent, and addresses an explicit mailbox through /users/{id-or-userPrincipalName}. That client-credentials flow does not apply to personal Outlook.com accounts. These samples target the global cloud; national clouds use different authority and Graph hosts.
HTTP methods can return false for an HTTP error as well as a connection failure. The code distinguishes those cases and checks the expected status before reading JSON. For 401, refresh the access token or authorize again; for 403, check permissions, mailbox access, and tenant policy. For 429, honor Retry-After before a bounded retry. Do not automatically repeat a write after an uncertain outcome. Keep detailed errors and calendar data private.
Chilkat C# Downloads
bool success = false;
// Assumes Chilkat is unlocked. See Global Unlock Sample.
success = false;
// Obtain a delegated Microsoft Graph token using the calendar authorization example.
// See Authorize Outlook Calendar with OAuth2 and PKCE.
Chilkat.JsonObject token = new Chilkat.JsonObject();
token.Strict = true;
success = token.LoadFile("qa_data/tokens/outlookCalendar.json");
if (success != true) {
Debug.WriteLine("Could not read the private calendar token cache.");
return;
}
if ((token.JsonTypeOf("access_token") != 1) || (token.StringOfEquals("access_token","",true) == true)) {
Debug.WriteLine("Expected a nonempty access_token in the JSON.");
return;
}
Chilkat.Http http = new Chilkat.Http();
http.AuthToken = token.StringOf("access_token");
http.RequireSslCertVerify = true;
http.FollowRedirects = false;
http.ConnectTimeout = 20;
http.ReadTimeout = 30;
http.SetRequestHeader("Accept","application/json");
Chilkat.HttpResponse resp = new Chilkat.HttpResponse();
Chilkat.JsonObject result = new Chilkat.JsonObject();
result.Strict = true;
http.SetRequestHeader("Prefer","outlook.timezone=\"UTC\", IdType=\"ImmutableId\"");
// Live write: creates an appointment in the signed-in user's default calendar.
// Keep one request file per logical operation and account. Do not run concurrent copies.
string requestFile = "qa_data/outlookCalendar/create-recurring-request.json";
string resultFile = "qa_data/outlookCalendar/created-recurring.json";
Chilkat.FileAccess fac = new Chilkat.FileAccess();
success = fac.DirEnsureExists("qa_data/outlookCalendar");
if (success != true) {
Debug.WriteLine("Could not create the private operation directory.");
return;
}
Chilkat.JsonObject body = new Chilkat.JsonObject();
body.Strict = true;
if (fac.FileExists(requestFile) == true) {
success = body.LoadFile(requestFile);
if (success != true) {
Debug.WriteLine("Could not read the saved create request; nothing sent.");
return;
}
// Retry the same saved body and transactionId after an uncertain result.
}
else {
Chilkat.CkDateTime when = new Chilkat.CkDateTime();
success = when.SetFromCurrentSystemTime();
if (success != true) {
Debug.WriteLine("Could not get the time.");
return;
}
success = when.AddDays(1);
if (success != true) {
Debug.WriteLine("Could not calculate tomorrow.");
return;
}
body.UpdateString("subject","Recurring appointment");
body.UpdateString("body.contentType","text");
body.UpdateString("body.content","Sample event details.");
body.UpdateString("start.dateTime",when.GetAsIso8601("YYYY-MM-DDThh:mm:ss",false));
body.UpdateString("start.timeZone","UTC");
success = when.AddSeconds(3600);
if (success != true) {
Debug.WriteLine("Could not calculate the end.");
return;
}
body.UpdateString("end.dateTime",when.GetAsIso8601("YYYY-MM-DDThh:mm:ss",false));
body.UpdateString("end.timeZone","UTC");
body.UpdateString("recurrence.pattern.type","daily");
body.UpdateInt("recurrence.pattern.interval",1);
body.UpdateString("recurrence.range.type","numbered");
body.UpdateInt("recurrence.range.numberOfOccurrences",3);
body.UpdateString("recurrence.range.recurrenceTimeZone","UTC");
Chilkat.StringBuilder recurrenceDate = new Chilkat.StringBuilder();
recurrenceDate.Append(body.StringOf("start.dateTime"));
string startDate = recurrenceDate.GetBefore("T",false);
body.UpdateString("recurrence.range.startDate",startDate);
// No attendees: this is an appointment, so the request does not send invitations.
Chilkat.Crypt2 crypt = new Chilkat.Crypt2();
string transactionId = crypt.GenerateUuid();
if (crypt.LastMethodSuccess != true) {
Debug.WriteLine("Could not create a transaction ID.");
return;
}
body.UpdateString("transactionId",transactionId);
success = body.WriteFile(requestFile);
if (success != true) {
Debug.WriteLine("Could not save the request before sending; nothing sent.");
return;
}
}
if ((body.JsonTypeOf("transactionId") != 1) || (body.StringOfEquals("transactionId","",true) == true)) {
Debug.WriteLine("Expected a nonempty transactionId in the JSON.");
return;
}
// A previous successful run leaves a small receipt. Do not submit it again.
if (fac.FileExists(resultFile) == true) {
Chilkat.JsonObject receipt = new Chilkat.JsonObject();
receipt.Strict = true;
success = receipt.LoadFile(resultFile);
if (success != true) {
Debug.WriteLine("Could not read the existing receipt; nothing sent.");
return;
}
if ((receipt.JsonTypeOf("id") != 1) || (receipt.StringOfEquals("id","",true) == true)) {
Debug.WriteLine("Expected a nonempty id in the JSON.");
return;
}
if (receipt.StringOfEquals("transactionId",body.StringOf("transactionId"),true) != true) {
Debug.WriteLine("The receipt belongs to another operation; nothing sent.");
return;
}
Debug.WriteLine("Already created event ID: " + receipt.StringOf("id"));
return;
}
success = http.HttpJson("POST","https://graph.microsoft.com/v1.0/me/events",body,"application/json",resp);
// A false result can still include an HTTP error response.
if ((success != true) && (resp.StatusCode == 0)) {
Debug.WriteLine("No HTTP response was received. Inspect diagnostics privately; reconcile a write before retrying.");
return;
}
if (resp.StatusCode != 201) {
Debug.WriteLine("Unexpected HTTP status: " + Convert.ToString(resp.StatusCode));
Debug.WriteLine("Request ID: " + resp.GetHeaderField("request-id"));
if (resp.StatusCode == 429) {
Debug.WriteLine("Retry-After: " + resp.GetHeaderField("Retry-After"));
}
if (resp.StatusCode == 401) {
Debug.WriteLine("Refresh the Graph access token or authorize again.");
}
return;
}
success = result.Load(resp.BodyStr);
if (success != true) {
Debug.WriteLine("Expected a well-formed JSON response.");
return;
}
if ((result.JsonTypeOf("id") != 1) || (result.StringOfEquals("id","",true) == true)) {
Debug.WriteLine("Expected a nonempty id in the JSON.");
return;
}
Chilkat.JsonObject saved = new Chilkat.JsonObject();
saved.UpdateString("id",result.StringOf("id"));
saved.UpdateString("transactionId",body.StringOf("transactionId"));
// Display the ID even if saving the receipt fails: the server has already created the event.
Debug.WriteLine("Created event ID: " + result.StringOf("id"));
success = saved.WriteFile(resultFile);
if (success != true) {
Debug.WriteLine("The event was created, but its receipt could not be saved. Reconcile before retrying.");
return;
}
Debug.WriteLine("Start: " + result.StringOf("start.dateTime") + " (" + result.StringOf("start.timeZone") + ")");
Debug.WriteLine("End: " + result.StringOf("end.dateTime") + " (" + result.StringOf("end.timeZone") + ")");
Debug.WriteLine("Event receipt saved.");
// Inspect occurrences only after the series ID has been recorded.
string seriesId = result.StringOf("id");
Chilkat.StringBuilder utcStart = new Chilkat.StringBuilder();
utcStart.Append(body.StringOf("start.dateTime"));
utcStart.Append("Z");
string windowStart = utcStart.GetAsString();
Chilkat.CkDateTime rangeEnd = new Chilkat.CkDateTime();
success = rangeEnd.SetFromTimestamp(windowStart);
if (success != true) {
Debug.WriteLine("Could not parse the saved series start.");
return;
}
success = rangeEnd.AddDays(7);
if (success != true) {
Debug.WriteLine("Could not set the instance range.");
return;
}
string windowEnd = rangeEnd.GetAsTimestamp(false);
Chilkat.StringBuilder endpoint = new Chilkat.StringBuilder();
endpoint.Append("https://graph.microsoft.com/v1.0/me/events/");
endpoint.Append(http.UrlEncode(seriesId));
endpoint.Append("/instances?startDateTime=");
endpoint.Append(http.UrlEncode(windowStart));
endpoint.Append("&endDateTime=");
endpoint.Append(http.UrlEncode(windowEnd));
endpoint.Append("&$select=id,subject,start,end,type,seriesMasterId&$top=50");
string url = endpoint.GetAsString();
Chilkat.StringBuilder nextLink = new Chilkat.StringBuilder();
Chilkat.StringArray seenLinks = new Chilkat.StringArray();
int pageCount = 0;
while ((pageCount < 100)) {
// Use Microsoft's nextLink exactly as returned; do not rebuild skip tokens.
nextLink.Clear();
nextLink.Append(url);
if (nextLink.StartsWith("https://graph.microsoft.com/v1.0/",true) != true) {
Debug.WriteLine("Unexpected pagination host or API version; no request sent.");
return;
}
if (seenLinks.Find(url,0) >= 0) {
Debug.WriteLine("Repeated pagination URL; stopping.");
return;
}
seenLinks.Append(url);
success = http.HttpNoBody("GET",url,resp);
// A false result can still include an HTTP error response.
if ((success != true) && (resp.StatusCode == 0)) {
Debug.WriteLine("No HTTP response was received. Inspect diagnostics privately; reconcile a write before retrying.");
return;
}
if (resp.StatusCode != 200) {
Debug.WriteLine("Unexpected HTTP status: " + Convert.ToString(resp.StatusCode));
Debug.WriteLine("Request ID: " + resp.GetHeaderField("request-id"));
if (resp.StatusCode == 429) {
Debug.WriteLine("Retry-After: " + resp.GetHeaderField("Retry-After"));
}
if (resp.StatusCode == 401) {
Debug.WriteLine("Refresh the Graph access token or authorize again.");
}
return;
}
success = result.Load(resp.BodyStr);
if (success != true) {
Debug.WriteLine("Expected a well-formed JSON response.");
return;
}
if (result.JsonTypeOf("value") != 4) {
Debug.WriteLine("Expected a value array.");
return;
}
int i = 0;
while ((i < result.SizeOfArray("value"))) {
result.I = i;
if ((result.JsonTypeOf("value[i].id") != 1) || (result.StringOfEquals("value[i].id","",true) == true)) {
Debug.WriteLine("Expected a nonempty value[i].id in the JSON.");
return;
}
Debug.WriteLine("Event ID: " + result.StringOf("value[i].id"));
Debug.WriteLine("Subject: " + result.StringOf("value[i].subject"));
Debug.WriteLine("Start: " + result.StringOf("value[i].start.dateTime") + " (" + result.StringOf("value[i].start.timeZone") + ")");
Debug.WriteLine("End: " + result.StringOf("value[i].end.dateTime"));
Debug.WriteLine("Type: " + result.StringOf("value[i].type"));
i = i + 1;
}
pageCount = pageCount + 1;
// Quote the member name because @odata.nextLink contains a literal period.
int nextType = result.JsonTypeOf("\"@odata.nextLink\"");
if ((nextType == -1) || (nextType == 6)) {
Debug.WriteLine("Completed pages: " + Convert.ToString(pageCount));
return;
}
if ((nextType != 1) || (result.StringOfEquals("\"@odata.nextLink\"","",true) == true)) {
Debug.WriteLine("Invalid continuation link; cannot establish completeness.");
return;
}
url = result.StringOf("\"@odata.nextLink\"");
}
Debug.WriteLine("Stopped at the example's 100-page limit. Save the continuation URL privately to resume.");