Connect Google, Outlook, and Apple Calendar to Timeful

Calendar integration lets participants skip the tedious drag-to-mark step. Once a calendar account is connected, Timeful reads existing events from your calendar and automatically fills in the availability grid — marking you as busy wherever you have conflicting appointments. Timeful only ever reads calendar data; it never creates, modifies, or deletes events without your explicit action.

Supported Calendar Providers

Google Calendar

Connect any Google Workspace or personal Gmail account. Supports multiple Google accounts simultaneously.

Microsoft Outlook / 365

Connect Outlook.com, Hotmail, or Microsoft 365 organizational accounts via Microsoft Graph.

Apple Calendar

Connect iCloud calendars via CalDAV using your Apple ID email and an app-specific password.

The calendar type is stored as a CalendarType string on each CalendarAccount record in the User document:

// From server/models/calendar.go
const (
    AppleCalendarType   CalendarType = "apple"
    GoogleCalendarType  CalendarType = "google"
    OutlookCalendarType CalendarType = "outlook"
)

How It Works

Authorize your calendar account

Click Add Calendar on the event page or in your account settings. Timeful redirects you to the provider’s OAuth consent screen (or prompts for CalDAV credentials for Apple).

Timeful fetches your events

After authorization, Timeful calls the calendar API read-only to retrieve your events for the date range covered by the poll. Events are stored as CalendarEvent objects in memory — they are never persisted to the Timeful database.

Availability grid is auto-filled

Timeful marks every time slot occupied by a calendar event as busy, pre-filling the grid on your behalf. You can review and adjust before submitting.

Toggle sub-calendars

If your account has multiple sub-calendars (e.g., “Work”, “Personal”, “Birthdays”), you can toggle each one on or off so only relevant calendars contribute to your availability.

OAuth Scopes and Permissions

Timeful requests the minimum read-only permissions required. No write access is ever requested.

Google Calendar
Microsoft Outlook / 365
Apple Calendar

The following OAuth 2.0 scopes are requested when a user connects a Google account:

Scope	Purpose
`https://www.googleapis.com/auth/calendar.events.readonly`	Read calendar events to detect conflicts
`https://www.googleapis.com/auth/calendar.calendarlist.readonly`	List available sub-calendars for the toggle UI
`https://www.googleapis.com/auth/contacts.readonly`	Suggest contacts when adding attendees to a poll

These are configured in your Google Cloud project’s OAuth consent screen. See Self-Hosting Configuration for step-by-step setup.

The following Microsoft Graph delegated permissions are requested:

Permission	Purpose
`offline_access`	Obtain a refresh token so Timeful can re-authenticate without requiring repeated logins
`User.Read`	Read the user’s profile (name and email) to populate the `CalendarAccount` record
`Calendars.Read`	Read calendar events to detect conflicts

These permissions are configured in your Azure App Registration. Admin consent is optional but recommended for organizational Microsoft 365 deployments — without it, each user is prompted for individual consent on first use.See Self-Hosting Configuration for Azure App Registration setup instructions.

Apple Calendar uses CalDAV rather than OAuth. Users provide:

Their Apple ID email address
An app-specific password generated at appleid.apple.com (Apple does not allow direct Apple ID passwords for third-party CalDAV access)

Credentials are stored encrypted in MongoDB using the ENCRYPTION_KEY from your .env file. The AppleCalendarAuth struct holds these credentials server-side and is never exposed in API responses (all auth fields are tagged json:"-"):

// From server/models/calendar.go
type AppleCalendarAuth struct {
    Email    string `json:"-" bson:"email,omitempty"`
    Password string `json:"-" bson:"password,omitempty"`
}

Multiple Calendar Accounts

Users can link multiple calendar accounts — including multiple Google accounts, an Outlook account, and an Apple account — all at the same time. Each account is stored as a separate entry in the CalendarAccounts map on the User document, keyed by {email}_{calendarType}:

// From server/models/user.go
// CalendarAccounts is a mapping from {`email_CALENDARTYPE` => CalendarAccount}
CalendarAccounts map[string]CalendarAccount `json:"calendarAccounts" bson:"calendarAccounts,omitempty"`

For example, a user with two Google accounts and one Outlook account would have three entries:

alice@gmail.com_google
alice@columbia.edu_google
alice@outlook.com_outlook

The account the user first signed in with is tracked separately as primaryAccountKey.

Sub-Calendar Toggling

Within each linked account, Timeful discovers all sub-calendars (e.g., Google’s “Work”, “Personal”, “US Holidays”) and lists them in the calendar settings panel. Each SubCalendar entry has an enabled flag:

// From server/models/calendar.go
type SubCalendar struct {
    Name    string `json:"name" bson:"name,omitempty"`
    Enabled *bool  `json:"enabled" bson:"enabled,omitempty"`
}

Participants can disable sub-calendars that shouldn’t count against their availability (e.g., turn off a “Birthdays” calendar so birthday reminders don’t block time slots).

Calendar Options

Additional autofill behavior is controlled by CalendarOptions on the User document and updated via PATCH /api/user/calendar-options:

// From server/models/calendar.go
type CalendarOptions struct {
    BufferTime   BufferTimeOptions   `json:"bufferTime" bson:"bufferTime"`
    WorkingHours WorkingHoursOptions `json:"workingHours" bson:"workingHours"`
}

type BufferTimeOptions struct {
    Enabled bool `json:"enabled" bson:"enabled"`
    Time    int  `json:"time" bson:"time"` // minutes
}

type WorkingHoursOptions struct {
    Enabled   bool    `json:"enabled" bson:"enabled"`
    StartTime float32 `json:"startTime" bson:"startTime"` // hour of day, e.g. 9.0
    EndTime   float32 `json:"endTime" bson:"endTime"`     // hour of day, e.g. 17.0
}

Option	Description
Buffer time	Add N minutes of padding before and after each calendar event when calculating availability, so back-to-back meetings leave breathing room.
Working hours	Only count availability within a defined start/end hour window each day, regardless of what the calendar shows outside those hours.

Setting Up OAuth for Self-Hosted Deployments

Google OAuth Setup
Microsoft OAuth Setup

To enable Google Calendar integration on your self-hosted instance:

Go to Google Cloud Console and create or select a project.
Enable Google Calendar API and Google People API for the project.
Navigate to APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID.
Set the application type to Web application.
Add the authorized redirect URI: https://yourdomain.com/api/auth/google/callback

Copy the Client ID and Client Secret into your .env file:

CLIENT_ID=your_google_client_id
CLIENT_SECRET=your_google_client_secret

Set BASE_URL=https://yourdomain.com so the callback URL matches.

For full details, see Self-Hosting Configuration.

To enable Outlook / Microsoft 365 integration on your self-hosted instance:

Go to Azure Portal → Azure Active Directory → App registrations → New registration.
Set the supported account types to Accounts in any organizational directory and personal Microsoft accounts.
Add the redirect URI (Web platform): https://yourdomain.com/auth
After registration, copy the Application (client) ID to MICROSOFT_CLIENT_ID.
Under Certificates & secrets, create a new client secret and copy the value to MICROSOFT_CLIENT_SECRET.
Under API permissions, add the following Microsoft Graph delegated permissions:
- offline_access
- User.Read
- Calendars.Read
Optionally, click Grant admin consent if you are a Microsoft 365 admin and want to skip per-user consent prompts.

Set the env vars in your .env file:

MICROSOFT_CLIENT_ID=your_azure_app_client_id
MICROSOFT_CLIENT_SECRET=your_azure_client_secret

For full details, see Self-Hosting Configuration.

Calendar integration is optional. Without Google or Microsoft OAuth credentials configured, users can still create and respond to polls anonymously — they simply won’t be able to auto-fill availability from their calendars.

Availability Groups

Use live calendar data to show real-time team availability without creating a new poll each time.

Self-Hosting Configuration

Full reference for all environment variables including OAuth credentials.

Getting Started

Self-Hosting

Features

Deployment Guides

Operations

Connect Google, Outlook, and Apple Calendar to Timeful

Supported Calendar Providers

Google Calendar

Microsoft Outlook / 365

Apple Calendar

How It Works

OAuth Scopes and Permissions

Multiple Calendar Accounts

Sub-Calendar Toggling

Calendar Options

Setting Up OAuth for Self-Hosted Deployments

Availability Groups

Self-Hosting Configuration

Build docs developers (and LLMs) love

Getting Started

Self-Hosting

Features

Deployment Guides

Operations

Documentation Index

​Supported Calendar Providers

Google Calendar

Microsoft Outlook / 365

Apple Calendar

​How It Works

​OAuth Scopes and Permissions

​Multiple Calendar Accounts

​Sub-Calendar Toggling

​Calendar Options

​Setting Up OAuth for Self-Hosted Deployments

Availability Groups

Self-Hosting Configuration

Build docs developers (and LLMs) love

Supported Calendar Providers

How It Works

OAuth Scopes and Permissions

Multiple Calendar Accounts

Sub-Calendar Toggling

Calendar Options

Setting Up OAuth for Self-Hosted Deployments