Actual Links — Email Linking: iOS Developer Guide

This guide covers everything you need to integrate email linking into your iOS app: how it works, authentication, retrieval, configuration, and references.

How It Works

1. Authenticate — The user connects their email account through your app using IMAP. Credentials are stored on-device only and are never sent to or stored on Actual servers.
2. Extract — The SDK searches the user’s inbox for receipt emails from supported merchants and returns structured purchase data.
3. Enrich (optional) — If Product Intelligence is enabled, extracted line items are matched against the product catalog for UPC, brand, and category.

Supported Email Providers

The SDK supports linking multiple IMAP accounts simultaneously.

Choose Your Integration Approach

Installation

Email linking uses the BlinkEReceipt extension SDK (separate from the base SDK).

CocoaPods:

pod 'BlinkEReceipt'

pod 'BlinkEReceipt'

Swift Package Manager:

https://github.com/BlinkReceipt/blinkereceipt-ios

https://github.com/BlinkReceipt/blinkereceipt-ios

Prerequisites: Xcode 12+, iOS 11.0+ deployment target.

→ BlinkEReceipt iOS (GitHub)

License Keys

You need two keys: a license key and a Product Intelligence key. Set both in your AppDelegate:

import BlinkReceipt
import BlinkEReceipt

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    BRScanManager.shared().licenseKey = "YOUR-LICENSE-KEY"
    BRScanManager.shared().prodIntelKey = "YOUR-PROD-INTEL-KEY"
    return true
}

import BlinkReceipt
import BlinkEReceipt

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    BRScanManager.shared().licenseKey = "YOUR-LICENSE-KEY"
    BRScanManager.shared().prodIntelKey = "YOUR-PROD-INTEL-KEY"
    return true
}

IMAP Authentication (Gmail, Yahoo, AOL)

IMAP authentication requires the user’s email address and an App Password (not their regular account password). The SDK automates App Password creation for all supported providers.

Step 1: Collect Credentials

Build your own UI to collect the user’s email and regular account password, then create an IMAP account object:

BRIMAPAccount *imapAcct = [[BRIMAPAccount alloc] initWithProvider:BREReceiptProviderYahoo
                                                            email:userEmail
                                                         password:userPassword];

BRIMAPAccount *imapAcct = [[BRIMAPAccount alloc] initWithProvider:BREReceiptProviderYahoo
                                                            email:userEmail
                                                         password:userPassword];

Step 2: Run IMAP Setup

The SDK logs into the user’s account and attempts to create an App Password automatically. For Gmail, it checks whether Less Secure Apps is already enabled:

[[BREReceiptManager shared] setupIMAPForAccount:imapAcct
                                 viewController:self
                                 withCompletion:^(BRSetupIMAPResult result) {

    if (result == BRSetupIMAPResultCreatedAppPassword) {
        NSLog(@"Successfully created app password.");
    } else if (result == BRSetupIMAPResultEnabledLSA) {
        NSLog(@"Successfully enabled Gmail Less Secure Apps.");
    }
}];

[[BREReceiptManager shared] setupIMAPForAccount:imapAcct
                                 viewController:self
                                 withCompletion:^(BRSetupIMAPResult result) {

    if (result == BRSetupIMAPResultCreatedAppPassword) {
        NSLog(@"Successfully created app password.");
    } else if (result == BRSetupIMAPResultEnabledLSA) {
        NSLog(@"Successfully enabled Gmail Less Secure Apps.");
    }
}];

Step 3: Verify the Connection

Once setup succeeds, verify the IMAP connection:

[[BREReceiptManager shared] verifyImapAccount:imapAcct
                               withCompletion:^(BOOL success, NSError *error) {

    if (success) {
        // Credentials verified
    } else {
        // Failed to verify credentials
    }
}];

[[BREReceiptManager shared] verifyImapAccount:imapAcct
                               withCompletion:^(BOOL success, NSError *error) {

    if (success) {
        // Credentials verified
    } else {
        // Failed to verify credentials
    }
}];

Already Have an App Password?

If users have already generated an App Password, skip the automated setup and link directly:

[[BREReceiptManager shared] linkIMAPAccountWithoutSetup:imapAcct
                                         withCompletion:^(BRSetupIMAPResult result) {
    // Handle result
}];

[[BREReceiptManager shared] linkIMAPAccountWithoutSetup:imapAcct
                                         withCompletion:^(BRSetupIMAPResult result) {
    // Handle result
}];

Retrieving Email Receipts

Local Retrieval

Use when the user is actively in the app and you want immediate results. The SDK connects directly to the email provider, searches the inbox, and returns results:

[[BREReceiptManager shared] getEReceiptsWithCompletion:^(NSArray<BRScanResults *> *receipts,
                                                          BREmailAccount *account,
                                                          NSError *error) {
    if (error == nil) {
        NSLog(@"Found %lu new e-receipt orders", (unsigned long)receipts.count);
    } else {
        NSLog(@"Error retrieving e-receipts");
    }
}];

[[BREReceiptManager shared] getEReceiptsWithCompletion:^(NSArray<BRScanResults *> *receipts,
                                                          BREmailAccount *account,
                                                          NSError *error) {
    if (error == nil) {
        NSLog(@"Found %lu new e-receipt orders", (unsigned long)receipts.count);
    } else {
        NSLog(@"Error retrieving e-receipts");
    }
}];

Limitation: If the user exits the app during processing, no results are received. Use remote retrieval for background processing.

Remote Retrieval (Recommended)

Authentication stays on-device, but the inbox search happens server-side. Results are posted to your configured webhook endpoint:

[[BREReceiptManager shared] startRemoteEReceiptScrapeForAccount:account
                                                 withCompletion:^(NSString *jobId, NSError *error) {
    if (error == nil) {
        // Job successfully queued — results will be posted to your webhook
    } else {
        // Job failed to queue
    }
}];

[[BREReceiptManager shared] startRemoteEReceiptScrapeForAccount:account
                                                 withCompletion:^(NSString *jobId, NSError *error) {
    if (error == nil) {
        // Job successfully queued — results will be posted to your webhook
    } else {
        // Job failed to queue
    }
}];

Server-side configuration required:

 eReceipts Configuration API (SwaggerHub) → Webhook Documentation

Search Window Configuration

Control how far back to search in the user’s email:

Signing Out

To disconnect a linked email account:

[[BREReceiptManager shared] signOutFromAccount:account
                                withCompletion:^(NSError *error) {
    // Account disconnected
}];

[[BREReceiptManager shared] signOutFromAccount:account
                                withCompletion:^(NSError *error) {
    // Account disconnected
}];

For OAuth providers, this signs out and invalidates the access token. For IMAP providers, this removes stored credentials.

Email Receipt Data

Email receipts return the same core fields as paper receipts (merchant, date, total, line items) plus additional fields:

For the full list of returned fields, see the Data Reference →.

Supported Merchant Emails

The list of merchant email senders that Actual processes is publicly available and updated regularly.

 Supported Merchant Emails

Emails from senders not on this list are not processed or stored.

Error Handling

Testing Recommendations

• Test each supported provider (Gmail, Yahoo, AOL) end to end
• Test with accounts that have varying volumes of receipt emails
• Test the remote scraping flow including webhook delivery
• Verify cutoff date behavior
• Test account unlinking and re-authentication
• Test aggregation with orders that generate multiple emails

Implementation Timeline

Key Classes & References

Related

• Actual Links — Email Linking: Android Developer Guide
• Actual Links — Account Linking: iOS Developer Guide