Email Discovery

Connect a user's Gmail account to automatically discover bills from their inbox. BillerAPI scans incoming emails, identifies billers, and extracts bill data.

Related guide: Link a Biller Account

The Email Message object

Attributes

Field	Type	Description
id*	string	Unique message identifier
user_id*	string	The user who owns this message
from*	string	Sender email address
subject	string	Email subject line
biller_id	string	Matched biller ID (if identified)
biller_name	string	Matched biller name (if identified)
bill_amount	number	Extracted bill amount (if found)
due_date	string	Extracted due date (if found)
received_at	string	ISO 8601 timestamp when the email was received

Example Email Message object

JSON

{
  "id": "msg_abc123",
  "user_id": "user_456",
  "from": "billing@electric-company.com",
  "subject": "Your April bill is ready",
  "biller_id": "test_electric_company",
  "biller_name": "Test Electric Company",
  "bill_amount": 142.50,
  "due_date": "2026-04-15",
  "received_at": "2026-04-01T08:30:00Z"
}

POST/emails/gmail/oauth-url

Generate a Gmail OAuth URL to initiate the email connection flow. No authentication required. Redirect the user to the returned URL to begin Gmail authorization.

Request Body

Field	Type	Description
user_id*	string	Your internal user identifier
client_id*	string	Your BillerAPI client ID
redirect_uri	string	URL to redirect after OAuth (defaults to your configured redirect URI)

Response

{
  "oauth_url": "https://accounts.google.com/o/oauth2/v2/auth?..."
}

curl -X POST https://sandbox.api.billerapi.com/emails/gmail/oauth-url \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_456",
    "client_id": "client_xyz",
    "redirect_uri": "https://your-app.com/callback"
  }'

POST/emails/gmail/connect

Complete the Gmail connection after the user has authorized via OAuth. Call this endpoint after receiving the OAuth callback.

Request Body

Field	Type	Description
user_id*	string	Your internal user identifier
client_id*	string	Your BillerAPI client ID

Response

{
  "connected": true,
  "email": "user@gmail.com",
  "user_id": "user_456"
}

curl -X POST https://sandbox.api.billerapi.com/emails/gmail/connect \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_456",
    "client_id": "client_xyz"
  }'

GET/emails/messages

List discovered email messages for a user. Returns emails that have been scanned and matched to billers, with extracted bill data when available.

Query Parameters

Field	Type	Description
userId*	string	Filter by user ID
startDate	string	ISO 8601 start date filter
endDate	string	ISO 8601 end date filter
limit	integer	Maximum results to return (default: 20, max: 100)
cursor	string	Pagination cursor from previous response

Response

{
  "messages": [EmailMessage],
  "cursor": "eyJsYXN0X2lkIjoibXNnXzEyMyJ9"
}

curl "https://sandbox.api.billerapi.com/emails/messages?userId=user_456&limit=20" \
  -H "X-Client-ID: your_client_id" \
  -H "X-Client-Secret: your_client_secret"