Email and calendar APIs give applications access to some of the most sensitive systems in any organization. Responsible use starts before the first API call: requesting only the OAuth scopes a workflow actually needs, handling tokens securely across their full lifecycle, building monitoring and revocation into the integration from day one, and designing multi-tenant architectures that prevent one customer’s data from touching another’s. This article explains how to do each of those things in practice.
Why communications APIs carry a higher responsibility bar
Most APIs expose structured data with relatively clear boundaries. An email and calendar API is different. A connected inbox may contain legal correspondence, financial negotiations, HR communications, authentication emails, customer records, and operational decision-making artifacts — all accessible under the same set of granted permissions.
That sensitivity is not a reason to avoid building on communications APIs. It is a reason to build on them carefully. The access model, token handling, data retention policy, and monitoring architecture that a developer puts in place at the start of an integration determines the risk profile of everything that runs on top of it.
This article covers the six decisions that most directly determine whether a communications API integration is responsible in practice.
1. Request only the OAuth scopes you actually need
Least-privilege access is the most important design decision in a communications API integration. It is also the decision most frequently deferred or ignored during development — and the one with the largest consequences when something goes wrong.
The core principle: An integration should request only the OAuth scopes it currently uses, for the specific data types it needs, in the directions (read, write, send) it genuinely requires. No speculative scope requests for features that might be built later. No full-account access when folder-level access would work.
Why this matters in practice:
If an integration with full inbox read/write access has a credential compromise, the attacker has access to the full inbox. If the same integration had been scoped to read-only access on a specific label, the compromise is bounded.
If an integration with contact write access has a bug that corrupts data, it can damage contact records across the entire account. If it only had contact read access, the damage cannot occur.
Scope selection by workflow type:
Workflow
Minimum required scope
Scopes that should not be requested
Show calendar availability
Calendar read, free/busy
Full inbox, contacts, send
Book a meeting
Calendar read/write
Full inbox access, contacts write
Sync contacts to a CRM
Contacts read
Email read, calendar write, send
Email summarization
Email read (specific folder/label)
Send, contacts, calendar write
Send outbound notifications
Send only
Read, contacts, calendar
Inbound email classification
Email read (specific inbox)
Send, contacts, calendar
AI inbox assistant (read + draft)
Email read, draft
Send (require separate user approval to send)
AI inbox assistant (autonomous send)
Email read, send
Contacts write, calendar (if not needed)
For Nylas integrations specifically: Nylas’s OAuth model supports granular scope selection. Request scopes that match your current workflow, not a superset. If your integration evolves to need additional scopes, add them explicitly rather than requesting broad access upfront.
Common scope mistakes:
Requesting full account access during development and shipping it to production without narrowing
Requesting write access when read-only is sufficient, because write seemed useful for future features
Requesting email access for an integration that only needs calendar data
Requesting contacts access for an integration that only needs to read email from a specific label
Not reviewing scope grants when workflow requirements change
2. Manage tokens securely across their full lifecycle
OAuth access tokens are credentials. They should be treated with the same care as passwords — stored securely, transmitted only over encrypted connections, scoped to the minimum necessary, and revoked promptly when access is no longer needed.
Token storage:
Store OAuth tokens server-side, encrypted at rest. Never store tokens in client-side code, browser localStorage, plaintext environment variables, or application logs.
Use a secrets management service (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager, or equivalent) for token storage in production environments.
Rotate encryption keys for stored tokens on a defined schedule.
Token transmission:
Always use HTTPS. Never pass tokens in URL query parameters, where they appear in server logs and browser history.
Use short-lived access tokens and refresh tokens rather than long-lived access tokens wherever the provider supports it.
Token refresh:
Implement refresh token logic before access tokens expire, not after they fail. Silent refresh prevents users from needing to re-authenticate due to timing gaps.
Handle refresh failures gracefully: surface the failure to the user with a re-authentication prompt rather than silently failing or logging an error.
Log refresh events — not the token content, but the event (account ID, timestamp, success/failure) — for audit purposes.
Token revocation:
When a user disconnects their account, revoke the OAuth token immediately through the provider’s revocation endpoint. Do not rely on passive expiration.
Include token revocation in the offboarding flow, not as a deferred cleanup task.
Verify that revocation succeeded. Revocation API calls can fail; confirmation logging is important.
For multi-tenant applications:
Store tokens indexed by tenant and user. Never allow a query or bug to return a token belonging to a different tenant.
Audit token access patterns. An application that successfully retrieves a token for the wrong tenant has a misconfiguration that may not surface as an error.
3. Design for multi-tenant isolation from day one
Most applications built on communications APIs serve multiple customers. The failure mode specific to multi-tenant communications integrations is cross-tenant data exposure: a bug, misconfiguration, or access control error that allows one customer’s email or calendar data to be returned or processed in the context of another customer’s session.
Architecture principles for multi-tenant isolation:
Isolate at the data layer. Every query to email or calendar data should include a tenant identifier in the WHERE clause or equivalent. Design the schema so that a query without a tenant filter returns nothing — not everything.
Use separate OAuth tokens per user, per tenant. An integration where a single service account token is used to access all users’ email data (impersonation model) carries much higher cross-tenant risk than an integration where each user’s data is accessed only through that user’s own OAuth token.
Validate tenant ownership before every API call. Before making an API call to read or modify a user’s email or calendar data, verify that the requesting session has legitimate access to that account in the current tenant context. This should be a hard check, not a soft one.
Separate credential storage by tenant. Do not store all OAuth tokens in a single table without tenant-level partitioning and access controls. If your credential store does not enforce tenant boundaries at the query level, a single bug can expose all tokens.
Test cross-tenant isolation explicitly. Include tests that verify a request in tenant A cannot retrieve data belonging to tenant B, even with valid authentication. This is not covered by normal unit tests.
4. Monitor for misuse and unexpected behavior
Communications systems are high-value targets for misuse because they operate inside trusted environments. An integration that can read email, send messages, or access calendar data will be tested by attackers if it is exposed to the internet. It will also behave unexpectedly under edge cases that development testing does not cover.
What to monitor
Authentication events. Log every OAuth token exchange, refresh, and revocation with account identifier and timestamp. Anomalies in authentication patterns — sudden bursts of token refreshes, unusual times of day, token use from unexpected IP ranges — are early signals of credential misuse.
API call volume by account. Establish a baseline for normal API call volume per connected account. Spikes significantly above baseline — especially for email send or calendar write operations — warrant investigation.
Scope usage vs. scope grants. Log which OAuth scopes are actually exercised per account. If an integration requests email read and send but 90% of accounts only ever trigger reads, the send scope may be over-granted for most users.
Error patterns. A sudden spike in permission-denied errors may indicate a scope change, a token revocation, or a provider policy change that requires integration updates.
Downstream action volume. For integrations with automation components, monitor the volume of downstream actions triggered per account per unit time. Automated workflows that suddenly generate 10x their normal action volume may indicate a misconfiguration, a malicious input, or a prompt injection attack.
AI-generated action audit trail. For integrations with AI-assisted features, log every AI-generated action with the triggering event, the model output that caused it, and the action taken. AI-generated and user-generated actions should be distinguishable in logs.
What to log
Every log entry for communications API activity should include at minimum: account identifier, tenant identifier, timestamp, operation type (read/write/send/revoke), scope used, and success/failure. Log the event, not the content — do not log email body text, calendar event details, or contact information in application logs.
5. Build misuse prevention into workflow design
Communications API integrations are targets for several categories of misuse that developers should design against from the start rather than address reactively.
Phishing and impersonation via send permissions. An integration with email send access can be used to send phishing emails that appear to come from legitimate users. Mitigations:
Require explicit user approval for each outbound message outside defined automation patterns
Implement rate limits on automated outbound sending
Log every email sent through the integration with sender, recipient, and timestamp
Alert on sending patterns that deviate significantly from established baselines
Prompt injection for AI-enabled integrations. An AI feature that reads email content may be vulnerable to prompt injection attacks — malicious instructions embedded in email messages that attempt to manipulate the AI into taking unintended actions. Mitigations:
Treat all email content as untrusted input, regardless of sender
Separate the content-reading layer from the action-execution layer
Enforce action limits at the API level — not by instructing the model to decline
Log every AI-generated action with its triggering content
Excessive automation from misconfigured rules. A routing or classification rule that misidentifies message types can trigger unintended automation at scale. A webhook that fires on every message can generate action volumes far beyond what a manual review process can catch. Mitigations:
Implement rate limits and circuit breakers on automated workflows
Surface anomalous action volumes to administrators
Define and enforce maximum automation rates per account
Service account misuse. Integrations using a single service account to access multiple users’ data (rather than per-user OAuth tokens) create a high-value single point of compromise. If service accounts are necessary, scope them to the minimum access required and monitor their usage closely.
Stale access. Tokens that remain active after a user has left an organization, revoked consent, or disconnected the integration represent ongoing unauthorized access. Mitigations:
Implement webhook listeners or periodic checks for account closure or consent revocation events
Audit active token grants quarterly and revoke tokens for accounts that are no longer active
Include token revocation in offboarding automation
6. Establish a data retention and deletion policy before launch
Communications API integrations often persist email, calendar, or contact data in their own databases for performance, analytics, or feature purposes. The organization needs a documented policy for that data before the integration goes live — not after a regulatory inquiry or a user deletion request.
Define retention before you build. Decide how long email content, calendar events, contact records, and metadata will be retained in your systems. Match that decision to your privacy policy, your DPA commitments with customers, and any applicable regulatory requirements.
Build deletion into the product. A user should be able to delete their data from your application, not only from the provider’s system. If a user disconnects their email account, your application should delete or anonymize any data it retained from that account. This deletion should be immediate, not batched.
Separate what you store from what you access. Not everything the API makes accessible should be stored. If your application only needs email subjects and timestamps for a feature, do not store message bodies. Storing less reduces breach surface, reduces deletion complexity, and reduces regulatory exposure.
Document your subprocessors. If your application passes email or calendar data to third-party services — AI providers, analytics platforms, data enrichment services — document those relationships in your privacy policy and DPA. Users have a reasonable expectation that the vendor they connected to is not silently sharing their communications with additional parties.
How Nylas supports responsible API use
Nylas provides the infrastructure for communications API integrations and maintains its own governance practices around how platform data is handled. Several Nylas-specific capabilities directly support responsible integration design:
Granular OAuth scope support. Nylas’s OAuth model supports scoped permission requests, allowing integrations to request access limited to specific data types rather than full account access. Developers should request minimum necessary scopes through the Nylas OAuth configuration for each application.
Data minimization. Nylas applies data minimization principles to its own processing. Nylas does not use customer data to train general-purpose machine learning models.
Webhook support for event-driven architecture. Nylas supports webhook subscriptions for email, calendar, and contact events, enabling integrations to respond to specific events rather than polling broadly — which reduces unnecessary data access and supports more precise scope scoping.
Token management infrastructure. Nylas handles OAuth token exchange, storage, and refresh at the platform level, reducing the surface area developers need to implement and manage securely.
Professional Services Program. Nylas supports customers through architecture review, OAuth configuration, and webhook design — including review of permission scoping and data handling practices.
Responsible integration design is a shared responsibility. Nylas provides the platform controls; developers and organizations are responsible for how permissions are requested, how tokens are stored, how data is retained, and how workflows are monitored within their applications.
Developer checklist: responsible communications API integration
Before shipping a communications API integration to production, verify:
OAuth and permissions
Every OAuth scope requested is actively used by the current integration
Write and send scopes are requested only when the integration genuinely requires them
Full-account access scopes are not used when narrower scopes would work
Scopes have been reviewed and narrowed since development began
Token security
Tokens are stored server-side, encrypted, in a secrets management system
Tokens are never passed in URL query parameters or stored in client-side code
Token refresh logic is implemented proactively, not reactively
Token revocation is triggered immediately when a user disconnects
Revocation success is verified and logged
Multi-tenant isolation
Every data query includes a tenant identifier filter
Token storage is partitioned by tenant with access controls enforced at the query level
Cross-tenant isolation is covered by explicit automated tests
No service account has access to multiple tenants’ data without specific authorization
Monitoring and logging
Authentication events (token exchange, refresh, revocation) are logged
API call volume is monitored per account with alerts for anomalies
AI-generated and user-generated actions are distinguishable in logs
Downstream action volume is monitored with circuit breakers for spikes
No email content, calendar details, or contact information appears in application logs
Data retention
A documented retention policy exists before launch
User data deletion is immediate and complete when a user disconnects
The application does not store data categories it does not need for current functionality
Third-party services that receive communications data are documented in the privacy policy
Misuse prevention
Rate limits are applied to automated outbound sending
Email content is treated as untrusted input for any AI-enabled processing
Anomalous automation volume triggers an alert before it propagates
Stale token audit is scheduled and automated
Closing
Responsible use of email and calendar APIs is not a governance document you write after an integration is live. It is a set of design decisions made before the first line of production code: which scopes to request, how to store tokens, how to isolate tenants, what to log, and what to delete.
Those decisions are easier to make correctly at the start than to retrofit into a running integration. An integration that requests minimum necessary scopes, handles tokens securely, isolates tenants at the data layer, and revokes access on disconnect is not harder to build than one that doesn’t. It just requires making those decisions explicitly rather than defaulting to whatever is easiest.
Nylas is available to support architecture review, OAuth configuration, and integration design for teams building on communications APIs.
Frequently asked questions
What OAuth scopes should I request for a basic email integration?
Request only what your current workflow uses. If your integration reads email subjects and metadata to classify messages, request email read with the smallest folder scope that works — not full inbox access, not send, not contacts. If you need to send a response, add the send scope explicitly rather than requesting it speculatively. Revisit scope requests before each production release.
How should I store OAuth tokens for email and calendar integrations?
Server-side, encrypted at rest, in a secrets management system. Never in client-side code, browser storage, environment variable plaintext, or application logs. Use short-lived access tokens with refresh tokens. Revoke tokens immediately when users disconnect, and verify that revocation succeeded.
What is the most common security mistake in multi-tenant email integrations?
Missing tenant isolation at the data layer. A query that can return email data without a tenant filter is a cross-tenant data exposure waiting to happen. Every query to email, calendar, or contact data should include a tenant identifier as a required filter, not an optional one. Test this explicitly — it is not covered by standard unit tests.
What should I log for a communications API integration?
Log authentication events (token exchange, refresh, revocation) with account and tenant identifier. Log API operation types (read, write, send) with timestamp and success/failure. Log AI-generated actions with their triggering event and model output. Do not log email content, calendar details, or contact information — log the event, not the data.
How do I handle OAuth token revocation when a user disconnects?
Trigger revocation immediately through the provider’s revocation endpoint when the user initiates disconnection — not as a background task or scheduled cleanup. Verify that the revocation API call succeeded, and log the outcome. Also delete or anonymize any email, calendar, or contact data your application retained from that account.
What is prompt injection and how does it affect email integrations with AI features?
Prompt injection is an attack in which malicious instructions embedded in email content attempt to manipulate an AI system into taking unintended actions. For email integrations that use AI to read and process messages, this means incoming emails are an attack surface. Treat all email content as untrusted input, separate content reading from action execution, and enforce action limits at the API level rather than relying on the model to decline inappropriate instructions.
Does Nylas use customer data to train AI models?
No. Nylas does not use customer data to train general-purpose machine learning models and does not develop or operate proprietary foundation models.
What is the difference between requesting email read and requesting full mailbox access?
Email read with a specific folder or label scope limits the integration to only the messages in that scope. Full mailbox access — or broad inbox access — gives the integration visibility into every email in the connected account. Most integrations do not need full mailbox access, and the scope request should match actual workflow requirements. If a compliance review or security audit asks why an integration has full mailbox access, “we might need it someday” is not a sufficient justification.
How should I think about data retention for communications data my integration stores?
Retain only what you need for current functionality, for as long as you need it, and delete it completely when the user disconnects or requests deletion. Document your retention policy before launch. If your integration stores email subjects, calendar event titles, or contact names, those are personal data under GDPR and equivalent frameworks — they require a legal basis for processing, a defined retention period, and a deletion path. Address these before you ship, not when a regulator asks.
What monitoring should I set up for a communications API integration?
At minimum: authentication event logs (token exchange, refresh, revocation), API call volume per account with anomaly alerts, automated action volume with circuit breakers, and an audit trail that distinguishes AI-generated actions from user-generated actions. For integrations with send access, monitor outbound volume closely. For integrations with AI features, log every AI-generated action with its triggering content.
Email and Contacts API 
Calendar API & Scheduler 
Notetaker API 
Agent Accounts 
Sales & CRM 
Recruiting & ATS 
Healthcare
Financial
Legal
Real Estate
Education
Field Services
Docs
SDKs
Guides
Integrations
API status
Changelog
Support
Enterprise
