How offduty uses the Gmail API, and why we chose it

Offduty's core function is deceptively simple: hold your emails, then release them on a schedule. Under the hood, we use the Gmail API to do this, and we made deliberate choices about how to use it.

The label approach

Gmail has a feature called labels. Every message can have one or more labels applied to it. The default inbox view shows messages that have the INBOX label. If a message doesn't have the INBOX label, it doesn't appear in your inbox.

Offduty exploits this behaviour to hold email:

1. When you start offduty, we create a private label in your Gmail account called Offduty-Hold.
2. When a new message arrives in your inbox, we apply the Offduty-Hold label and remove the INBOX label.
3. At your scheduled delivery time, we remove the Offduty-Hold label and re-apply the INBOX label.

The message is never deleted. It never leaves your account. It simply isn't visible in your inbox between those two operations.

What we access

To do this, we use Google OAuth and request the gmail.modify scope. This scope allows us to:

• Read messages (to check which ones are new)
• Modify labels on messages (to apply and remove the hold label)
• Create labels (to set up the Offduty-Hold label)

We do not access your message content beyond what's necessary to identify new arrivals. We don't read the body of your emails. We don't store messages on our servers.

Your emails live in your Gmail account. They stay there. We only touch the labels.

Why the Gmail API?

The alternative approaches (email forwarding, IMAP proxies, or custom mail servers) all require either reading your message content or routing your email through a third-party system.

We didn't want to do either. The Gmail API lets us apply labels at the source, inside your own account, without copying or routing anything. It's the most privacy-preserving approach available.

OAuth and security

When you sign in to offduty, Google's OAuth screen shows you exactly what permissions we're requesting. You can revoke access at any time from your Google account's security settings. If you do, offduty immediately loses access to your Gmail.

We store your OAuth tokens in an encrypted database and use them only to perform the label operations described above. We don't share them with third parties.

If you have questions about how we handle your data, our Privacy Policy covers everything in detail.