# Integrate Tomba Finder with Steampipe

## Overview

The Tomba Steampipe plugin allows you to query email intelligence data using SQL. This plugin provides access to Tomba.io's powerful email finder, verifier, and enrichment APIs through familiar SQL syntax.

### Key Features

- 🔍 **Email Discovery**: Find email addresses from names and domains
- **Email Verification**: Verify email deliverability and validity
- 🌐 **Domain Intelligence**: Search entire domains for email patterns
- 📊 **Data Enrichment**: Get detailed information about contacts and companies
- 🔗 **SQL Interface**: Query using standard SQL syntax
- ⚡ **Real-time Data**: No ETL required - query live data directly

### Use Cases

- **Lead Generation**: Find and verify prospect email addresses
- **Data Enrichment**: Complete missing contact information in your database
- **Email Validation**: Bulk verify email lists for marketing campaigns
- **Competitive Intelligence**: Research competitor team structures
- **Sales Prospecting**: Build targeted contact lists with verified emails
- **Security Auditing**: Monitor your domain for exposed email addresses

## Quick Start

### Prerequisites

- [Steampipe](https://steampipe.io/downloads) installed
- [Tomba.io account](https://tomba.io/register) with API access
- Tomba API credentials (Key and Secret)

### Install and Query

```bash
# Install the plugin
steampipe plugin install tomba-io/tomba

# Start Steampipe
steampipe query

# Query email enrichment
select email, first_name, last_name, position, score
from tomba_enrich
where email = 'm@wordpress.org';
```

## Installation

### Install Plugin

```bash
steampipe plugin install tomba-io/tomba
```

### Verify Installation

```bash
steampipe plugin list | grep tomba
```

## Configuration

### Basic Configuration

Create or edit the configuration file at `~/.steampipe/config/tomba.spc`:

```hcl
connection "tomba" {
  plugin = "tomba-io/tomba"

  # Tomba API credentials
  key    = "ta_xxxx"
  secret = "ts_xxxx-6f90-4856-9017-b12b5079adc9"
}
```

### Environment Variables

Alternatively, set environment variables:

```bash
export TOMBA_KEY=ta_xxxx
export TOMBA_SECRET=ts_xxxx-6f90-4856-9017-b12b5079adc9
```

### Configuration Options

| Option    | Environment Variable | Description                              | Required |
| --------- | -------------------- | ---------------------------------------- | -------- |
| `key`     | `TOMBA_KEY`          | Your Tomba API key                       | Yes      |
| `secret`  | `TOMBA_SECRET`       | Your Tomba API secret                    | Yes      |
| `timeout` | `TOMBA_TIMEOUT`      | Request timeout in seconds (default: 60) | ❌ No    |
| `retries` | `TOMBA_RETRIES`      | Number of retry attempts (default: 3)    | ❌ No    |

### Getting API Credentials

1. Sign up for a [Tomba.io account](https://tomba.io/register)
2. Navigate to the [API section](https://app.tomba.io/api)
3. Copy your API Key and Secret
4. Configure the plugin with your credentials

## Tables

The Tomba plugin provides the following tables:

| Table                                           | Description                                     |
| ----------------------------------------------- | ----------------------------------------------- |
| [`tomba_enrich`](#tomba_enrich)                 | Enrich email addresses with contact information |
| [`tomba_email_finder`](#tomba_email_finder)     | Find email addresses from names and domains     |
| [`tomba_email_verifier`](#tomba_email_verifier) | Verify email address deliverability             |
| [`tomba_domain_search`](#tomba_domain_search)   | Search domains for all email addresses          |
| [`tomba_company_finder`](#tomba_company_finder) | Get company information and statistics          |
| [`tomba_sources`](#tomba_sources)               | Find sources where emails appear online         |

### Table Schemas

#### `tomba_enrich`

Enrich email addresses with detailed contact information.

**Key Columns:**

- `email` (text) - Email address to enrich
- `first_name` (text) - Contact's first name
- `last_name` (text) - Contact's last name
- `full_name` (text) - Contact's full name
- `position` (text) - Job title/position
- `company` (text) - Company name
- `country` (text) - Country location
- `score` (integer) - Confidence score (0-100)
- `sources` (jsonb) - Array of sources where email was found

#### `tomba_email_finder`

Find email addresses using first name, last name, and domain.

**Key Columns:**

- `domain` (text) - Company domain (required)
- `first_name` (text) - Person's first name (required)
- `last_name` (text) - Person's last name (required)
- `email` (text) - Found email address
- `score` (integer) - Confidence score
- `position` (text) - Job position
- `department` (text) - Department
- `sources` (jsonb) - Sources where found

#### `tomba_email_verifier`

Verify email address deliverability and validity.

**Key Columns:**

- `email` (text) - Email address to verify (required)
- `status` (text) - Verification status (valid/invalid/risky)
- `result` (text) - Detailed verification result
- `score` (integer) - Deliverability score
- `disposable` (boolean) - Is disposable email
- `webmail` (boolean) - Is webmail provider
- `role` (boolean) - Is role-based email
- `free` (boolean) - Is free email provider

#### `tomba_domain_search`

Search entire domains for email addresses and patterns.

**Key Columns:**

- `domain` (text) - Domain to search (required)
- `email` (text) - Found email address
- `first_name` (text) - Contact first name
- `last_name` (text) - Contact last name
- `position` (text) - Job position
- `department` (text) - Department
- `seniority` (text) - Seniority level
- `sources` (jsonb) - Sources array

#### `tomba_company_finder`

Get comprehensive company information and statistics.

**Key Columns:**

- `domain` (text) - Company domain (required)
- `organization` (text) - Company name
- `description` (text) - Company description
- `industry` (text) - Industry sector
- `country` (text) - Company location
- `size` (text) - Company size range
- `founded` (integer) - Founded year
- `website_url` (text) - Company website
- `total_emails` (integer) - Total email count

#### `tomba_sources`

Find sources where email addresses appear online.

**Key Columns:**

- `email` (text) - Email address to search (required)
- `uri` (text) - Source URL
- `website_url` (text) - Website domain
- `extracted_on` (timestamp) - When email was extracted
- `last_seen_on` (timestamp) - Last seen date
- `still_on_page` (boolean) - Still appears on page

## Examples

### Email Enrichment

```sql
-- Enrich a single email address
select
  email,
  first_name,
  last_name,
  position,
  company,
  score
from tomba_enrich
where email = 'contact@example.com';
```

### Bulk Email Verification

```sql
-- Verify multiple email addresses
select
  email,
  status,
  score,
  disposable,
  webmail
from tomba_email_verifier
where email in (
  'user1@example.com',
  'user2@example.com',
  'user3@example.com'
);
```

### Find Decision Makers

```sql
-- Find executives at a company
select
  email,
  full_name,
  position,
  department
from tomba_domain_search
where domain = 'techcompany.com'
  and (
    position ilike '%CEO%' or
    position ilike '%CTO%' or
    position ilike '%VP%' or
    position ilike '%Director%'
  );
```

### Email Discovery Pipeline

```sql
-- Find and verify emails in one query
with found_emails as (
  select
    domain,
    first_name,
    last_name,
    email,
    score as finder_score
  from tomba_email_finder
  where domain = 'startup.com'
    and first_name = 'John'
    and last_name = 'Smith'
)
select
  f.email,
  f.first_name,
  f.last_name,
  f.finder_score,
  v.status as verification_status,
  v.score as verification_score,
  v.disposable
from found_emails f
left join tomba_email_verifier v on f.email = v.email;
```

### Company Intelligence Report

```sql
-- Get comprehensive company overview
select
  c.organization,
  c.industry,
  c.size,
  c.total_emails,
  count(d.email) as found_emails,
  count(case when d.position ilike '%manager%' or
                  d.position ilike '%director%' or
                  d.position ilike '%vp%'
             then 1 end) as leadership_count
from tomba_company_finder c
left join tomba_domain_search d on c.domain = d.domain
where c.domain = 'bigcorp.com'
group by c.organization, c.industry, c.size, c.total_emails;
```

### Lead Scoring System

```sql
-- Create lead quality scores
select
  e.email,
  e.first_name,
  e.last_name,
  e.position,
  v.score as email_score,
  case
    when v.score >= 90 then 'High Quality'
    when v.score >= 70 then 'Good Quality'
    when v.score >= 50 then 'Medium Quality'
    else 'Low Quality'
  end as lead_grade,
  case
    when e.position ilike '%CEO%' or e.position ilike '%founder%' then 50
    when e.position ilike '%VP%' or e.position ilike '%director%' then 40
    when e.position ilike '%manager%' then 30
    else 10
  end as position_score,
  (v.score * 0.7 +
   case
     when e.position ilike '%CEO%' or e.position ilike '%founder%' then 50
     when e.position ilike '%VP%' or e.position ilike '%director%' then 40
     when e.position ilike '%manager%' then 30
     else 10
   end * 0.3) as composite_score
from tomba_enrich e
join tomba_email_verifier v on e.email = v.email
where e.email in ('lead1@company.com', 'lead2@company.com')
order by composite_score desc;
```

### Domain Monitoring

```sql
-- Monitor competitor domains for new hires
select
  domain,
  email,
  first_name,
  last_name,
  position,
  department,
  extract(month from current_date) as current_month
from tomba_domain_search
where domain in ('competitor1.com', 'competitor2.com')
  and department in ('Engineering', 'Sales', 'Marketing')
order by domain, department, position;
```

## Development

### Prerequisites for Development

- [Go](https://golang.org/doc/install) 1.19 or higher
- [Steampipe](https://steampipe.io/downloads) installed
- [Tomba.io](https://tomba.io) API credentials

### Clone and Build

```bash
# Clone the repository
git clone https://github.com/tomba-io/steampipe-plugin-tomba.git
cd steampipe-plugin-tomba

# Build the plugin
make

# Install the plugin locally
make install
```

### Testing

```bash
# Run tests
make test

# Test specific table
go test ./tomba -run TestTableTombaEnrich

# Integration tests (requires API credentials)
make test-integration
```

### Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Add tests for new functionality
4. Commit your changes (`git commit -m 'Add amazing feature'`)
5. Push to the branch (`git push origin feature/amazing-feature`)
6. Open a Pull Request

### Development Guidelines

- Follow [Steampipe plugin development guidelines](https://steampipe.io/docs/develop/writing-plugins)
- Add comprehensive tests for new tables and columns
- Update documentation for any changes
- Ensure proper error handling and logging
- Follow Go best practices and formatting

## Support

### Documentation & Resources

- 📚 [Plugin Documentation](https://hub.steampipe.io/plugins/tomba-io/tomba)
- 📖 [Table Reference](https://hub.steampipe.io/plugins/tomba-io/tomba/tables)
- 🔧 [Steampipe Documentation](https://steampipe.io/docs)
- 🌐 [Tomba.io API Documentation](https://docs.tomba.io/)

### Community & Support

- 💬 [Steampipe Slack Community](https://steampipe.io/community/join)
- 🐛 [GitHub Issues](https://github.com/tomba-io/steampipe-plugin-tomba/issues)
- 📧 [Tomba Support](mailto:support@tomba.io)
- 💡 [Feature Requests](https://github.com/tomba-io/steampipe-plugin-tomba/discussions)

### Getting Help

1. Check the [FAQ](docs/FAQ.md) for common questions
2. Search existing [issues](https://github.com/tomba-io/steampipe-plugin-tomba/issues)
3. Join the [Steampipe community](https://steampipe.io/community/join)
4. Create a new issue with detailed information

## Acknowledgments

- Thanks to the [Steampipe](https://steampipe.io) team for creating an amazing platform