Email Linking

Capture structured purchase data directly from digital receipts in users’ email accounts.

How It Works

Users connect their email account through your app. Actual identifies receipt emails from supported merchant senders, extracts purchase data, and returns it as structured JSON.

Only receipt emails from known merchant senders are accessed. No other emails are read, processed, or stored. The list of supported merchant senders is publicly available at:

ADD LIST HERE

Users can disconnect their email account at any time, which immediately revokes access.

What We Extract

• Merchant name
• Order number and order date
• Itemized products with prices, quantities, and shipping status
• Subtotal, tax, and total
• Delivery date and order status
• Payment method

Email-specific fields not found on paper receipts include:

• Order number
• Per-item shipping status
• Raw email HTML (if needed for your workflow)

See Data Reference for the complete list of fields.

Supported Email Providers

Email linking works with any IMAP-enabled provider, including:

• Gmail (IMAP with App Password)
• Outlook / Hotmail (IMAP)
• Yahoo (IMAP)
• AOL (IMAP)
• Other IMAP-enabled providers

Users authenticate using App Passwords generated in their email provider settings.

Integration Options

Actual offers four approaches to capturing digital receipts. Three use authenticated email linking, and one provides a lightweight forwarding alternative.

1. On-Device Authentication + Server Extraction (Recommended)

Users authenticate their email account through the SDK. Extraction runs asynchronously on Actual’s servers, and results are delivered to your server via webhook.

How it works

• User authenticates in-app
• SDK triggers an extraction job on Actual’s servers
• Actual scans the inbox for receipt emails from supported merchants
• Emails are processed in batches (up to 10 per batch)
• Each job returns a job ID for tracking
• Structured results are delivered to your callback URL

What you get

• One-time authentication, ongoing background processing
• No dependency on the app remaining open
• Job-based processing with status tracking
• Server-to-server webhook delivery
• Configurable historical lookback (default: 14 days)

Best for: Most implementations requiring scalable background processing.

2. On-Device Extraction via SDK

Extraction runs directly on the device in real time while the app is in the foreground.

How it works

• User authenticates in-app
• SDK connects to the email provider via IMAP
• Receipt emails are identified and extracted in real time
• Structured results are returned immediately to the app

What you get

• Real-time extraction
• Email content never leaves the device
• Immediate in-app results
• Configurable historical lookback (default: 14 days)

Important consideration: If the user exits the app, extraction stops. For large inboxes, this can limit results.

Best for: Privacy-sensitive implementations or workflows requiring immediate feedback.

3. Server-Only Integration

Send email content you already collect directly to Actual’s API for extraction.

How it works

• You collect email data independently (archives, ingestion pipelines, forwarding systems)
• Send email content to Actual’s extraction API
• A job ID is returned
• Results are delivered via webhook or polling

What you get

• No SDK required
• Supports historical data processing
• Job-based tracking and monitoring

Best for: Systems that already ingest email data independently.

4. Email Forwarding (Lightweight Alternative)

Users forward receipt emails to a dedicated inbox that is automatically forwarded to Actual for extraction.

How it works

• You create a dedicated inbox (e.g., receipts@yourcompany.com)
• Users forward receipt emails manually or via email rules
• Your inbox auto-forwards to Actual’s processing inbox
• Emails are processed every 2 minutes
• Results are accessible via API

What you get

• Simplest setup
• No SDK or authentication flow required
• API access to extracted results

Important consideration:
Only forwarded emails are processed. There is no automatic inbox scanning or historical lookback.

Best for: Pilot programs, lightweight integrations, or manual workflows.

Linking vs Forwarding — Quick Comparison

Email Linking

• Automatically scans inboxes for supported receipt emails
• Supports historical lookback
• Background syncing
• Designed for high-volume, ongoing capture
• Requires SDK or server integration

Email Forwarding

• Users manually forward receipts
• No historical inbox scanning
• Minimal technical setup
• Designed for low-volume or early-stage use cases

Choosing an Approach

Feature	Email Linking	Email Forwarding
Automatic inbox scanning	Yes	No
Historical receipts	Yes (configurable)	No
Background processing	Yes	Yes
SDK required	Yes (most flows)	No
User effort	One-time authentication	Manual forwarding
Scale	High	Low to moderate

Setup & Configuration

Email linking requires:

• Your standard SDK license key
• A Product Intelligence key

For SDK-based approaches, configure:

Merchant Coverage

Select which supported merchant senders to monitor. Actual maintains a default list that can be customized.

Historical Lookback

Define how far back to search for receipts:

• Rolling window (default: 14 days)
• Specific date ranges
• Per-merchant configuration

Result Delivery

For server-side extraction, designate a callback URL where completed job results are delivered.

How Jobs Work (Server-Based Approaches)

Extraction runs as asynchronous jobs.

Job initiation

Triggered by app startup, user action (e.g., “Sync” button), or scheduled background process.

Batching

Emails are processed in batches for stability and provider limits.

Job tracking

Each job returns a unique ID for monitoring progress or checking status.

No processing limits

There is no cap on number of jobs or volume of emails processed.

User Experience

Authentication

Users authenticate using their email address and an App Password generated in their email provider settings.

The SDK guides users through the App Password creation process where required.

Multiple Accounts

Users can link multiple email accounts simultaneously, subject to provider limitations.

What Users Should Know

• Only receipt emails from supported merchants are accessed
• Personal emails are never read, processed, or stored
• Full email contents are not retained
• Credentials are never stored on Actual’s servers
• Access can be revoked at any time

Ongoing UX Considerations

• Sync status indicators
• Re-authentication prompts (if credentials change)
• Linked account management screens
• Value reinforcement (receipts captured, rewards earned, savings surfaced)

What We Support

Supported Providers

Provider	Authentication	Notes
Gmail	IMAP (App Password)	Requires 2FA enabled
Outlook / Hotmail	IMAP	App Password
Yahoo	IMAP	App Password
AOL	IMAP	App Password
Other IMAP	IMAP	Custom configuration supported

Supported Merchants

Receipt extraction runs against a curated list of merchant email senders.

Current coverage is available at:

ADD HERE

Coverage includes major retailers across grocery, mass retail, pharmacy, restaurants, delivery services, and online marketplaces.

Email Formats

Supported formats include:

• HTML emails
• Plain text emails
• Embedded receipt content
• PDF attachments

Item-level availability varies by merchant.

Performance – Need to validate

Metric	Expectation
Initial server sync	5–10 minutes (volume dependent)
Ongoing sync	30 seconds – 2 minutes
Forwarding processing cadence	Every 2 minutes
Batch size	Up to 10 emails per batch
Default lookback	14 days

Some historical processing may span multiple sessions for stability.

Privacy & Security

• Read-only email access
• Data minimization based on supported merchant sender list
• No credential storage on servers
• No full email storage
• TLS encryption in transit
• User-controlled access revocation
• App Password authentication for IMAP

Next Steps

• Confirm SDK license key and Product Intelligence access
• Choose your integration approach
• Align on merchant coverage, lookback period, and result delivery
• Hand off to engineering for implementation