Getting Started
Already signed up? This guide takes you from your first mailbox connection to viewing transactions in the app and from your terminal.
Transactions reads bank and payment notification emails from a mailbox you connect, extracts supported transaction details, and makes them available under Parsed Emails, Transactions, and Accounts. Creating a mailbox connection here links an existing email account; it does not create a new email address.
1. Prepare your email account
Choose the email account that receives your bank and payment alerts. Open its inbox and check that those emails are present. You will need its email address, incoming IMAP server settings, and an app password.
IMAP lets Transactions read emails from your provider. An app password is a separate credential generated by your email provider for this connection. It is different from both your Transactions sign-in password and the API secret you will create for the CLI.
Follow your provider's guide first, then return here:
| Your email provider | Setup guide |
|---|---|
| Gmail or Google Workspace | Create a Google app password and get IMAP details |
| Yahoo Mail | Generate a Yahoo app password |
| iCloud Mail | Create an Apple app-specific password |
| Outlook.com, Hotmail, or Microsoft 365 | Check the current connection limitation |
| Another provider or a company email address | Find your IMAP settings |
The current mailbox form uses password-based IMAP and has no Google or Microsoft OAuth sign-in. Check the provider guide before trying to connect a managed work account.
2. Connect a mailbox
- Open Transactions and select the organization where you want the transactions to appear.
- Go to Settings → Mailboxes.
- Select Connect mailbox.
- Complete the form using your provider's instructions:
| Field | What to enter |
|---|---|
| Provider | Gmail for Google accounts; Other (IMAP) for Yahoo, iCloud, or another compatible provider. Read the Outlook guide before choosing Outlook. |
| Email address | The full address of the mailbox receiving your alerts. The app also uses this as the IMAP login username. |
| IMAP host | Your provider's incoming server hostname, without https://. |
| Port | 993 for the providers covered here. |
| App password | The password generated for this connection by your provider. |
| Folder | Start with INBOX. Only this folder is scanned. If rules move alerts elsewhere, use that folder's exact IMAP name. |
| Use TLS | Leave on for port 993. This encrypts the connection to the mail server. |
| Poll frequency | Start with Hourly. You can choose every 15 minutes, every 30 minutes, hourly, every 6 hours, or daily. |
| Emails per poll | Start with 50; the allowed range is 1–200. See the busy mailbox note below. |
- Select Connect mailbox and wait for the connection check.
The app checks the login and folder before saving. On success, the mailbox shows Connected and a message confirms that the last 31 days of email are being fetched. Your mailbox credential is stored encrypted.
If the connection check fails, correct the fields in the dialog and try again. See connection troubleshooting.
3. Check your first import
Importing and parsing happen in the background, so results may not appear immediately.
- Open Parsed Emails to see imported supported alerts.
- Open Transactions to review extracted transactions.
- Open Accounts to review accounts identified from the alerts.
- Return to Settings → Mailboxes to check Status and Last polled. Refresh the page to see updates.
Connected confirms mailbox access; it does not mean every email has become a transaction. Unsupported senders and email formats may not produce transactions. A new connection can show never under Last polled until a regular or manual poll runs, even while its initial date-range import is processing.
Select Poll now to queue a check for recent emails. To import older alerts, select Fetch dates, choose From and To dates (both included), then select Fetch these dates. Date-range fetching skips already-fetched emails.
For a busy inbox, regular polling checks only the newest number of emails set in Emails per poll, including non-bank mail. If more messages arrive between polls than that limit, older alerts can be missed. Increase the limit or polling frequency under the mailbox's Settings, and use Fetch dates to recover the affected period.
4. Set up the CLI
Follow Set Up the CLI to install fob-txn, create an API key, and connect it to this organization. The CLI reads the data imported by the app; your computer does not need to stay on for mailbox polling.
Once configured, try:
fob-txn whoami
fob-txn accounts list
fob-txn transactions list --limit 5
You are ready when the mailbox is connected, supported alerts appear in the app, and whoami identifies the intended organization. An empty mailbox can connect successfully and show no transactions until supported alerts arrive.
Manage a connection later
Use the mailbox's Settings button to change polling frequency and email limit. To change its password, host, or folder, Disconnect it and connect it again with the new details; the current settings dialog only edits polling options. Disconnecting stops polling and removes the stored credential while keeping already-parsed emails. Revoke the old app password at your provider when you no longer need it.