# Pipedream Integration

## Overview

Connect Tomba.io with 2,000+ apps on Pipedream to build serverless workflows with code-level control. Pipedream is a developer-first integration platform that lets you build powerful automations with Node.js code or pre-built actions.

## Prerequisites

- Active Tomba.io account with API credentials
- Pipedream account (free or paid)

## Setup & Authentication

### Connecting Tomba.io to Pipedream

1. In your workflow, search for **Tomba** in the action/trigger selector
2. Click **Connect Account**
3. Enter your Tomba.io credentials:
    - **API Key**: Your Tomba.io API key
    - **Secret Key**: Your Tomba.io secret key
4. Click **Save**

**Getting Your API Credentials:**

1. Log in to your [Tomba.io dashboard](https://app.tomba.io)
2. Navigate to [API Keys](https://app.tomba.io/api)
3. Copy your API Key and Secret Key

## Available Actions

### Email Finder

Find professional email addresses using a person's name and company domain.

**Input:**

- **Domain** (required) - Company domain (e.g., `tomba.io`)
- **First Name** (required) - Person's first name
- **Last Name** (required) - Person's last name

**Output:**

- Email address
- Verification status
- Score (accuracy confidence)
- Position
- Department
- Social profiles

**Example Code:**

```javascript
import { axios } from "@pipedream/platform";
export default defineComponent({
    props: {
        tomba: {
            type: "app",
            app: "tomba",
        },
    },
    async run({ steps, $ }) {
        return await axios($, {
            url: `https://api.tomba.io/v1/email-finder`,
            params: {
                domain: "tomba.io",
                first_name: "Mohamed",
                last_name: "Ben rebia",
            },
            headers: {
                "X-Tomba-Key": `${this.tomba.$auth.api_key}`,
                "X-Tomba-Secret": `${this.tomba.$auth.secret_key}`,
            },
        });
    },
});
```

### Email Verifier

Verify if an email address is valid and deliverable.

**Input:**

- **Email** (required) - Email address to verify

**Output:**

- Email status (valid/invalid)
- Result (deliverable/undeliverable/risky)
- Score (0-100)
- SMTP check results
- Accept-all detection
- Disposable email detection

**Example Code:**

```javascript
import { axios } from "@pipedream/platform";
export default defineComponent({
    props: {
        tomba: {
            type: "app",
            app: "tomba",
        },
    },
    async run({ steps, $ }) {
        return await axios($, {
            url: `https://api.tomba.io/v1/email-verifier`,
            params: {
                email: "mohamed@tomba.io",
            },
            headers: {
                "X-Tomba-Key": `${this.tomba.$auth.api_key}`,
                "X-Tomba-Secret": `${this.tomba.$auth.secret_key}`,
            },
        });
    },
});
```

### Domain Search

Search for all email addresses associated with a domain.

**Input:**

- **Domain** (required) - Company domain
- **Page** (optional) - Page number for pagination
- **Limit** (optional) - Results per page (max: 100)
- **Department** (optional) - Filter by department

**Output:**

- Array of email addresses
- Full names and positions
- Departments
- Social profiles
- Total count

**Example Code:**

```javascript
import { axios } from "@pipedream/platform";
export default defineComponent({
    props: {
        tomba: {
            type: "app",
            app: "tomba",
        },
    },
    async run({ steps, $ }) {
        return await axios($, {
            url: `https://api.tomba.io/v1/domain-search`,
            params: {
                domain: "tomba.io",
                page: 1,
                limit: 10,
            },
            headers: {
                "X-Tomba-Key": `${this.tomba.$auth.api_key}`,
                "X-Tomba-Secret": `${this.tomba.$auth.secret_key}`,
            },
        });
    },
});
```

### Email Count

Get the total number of email addresses for a domain.

**Input:**

- **Domain** (required) - Company domain

**Output:**

- Total email count
- Personal emails count
- Generic emails count

### LinkedIn Email Finder

Find email addresses from LinkedIn profile URLs.

**Input:**

- **LinkedIn URL** (required) - LinkedIn profile URL

**Output:**

- Email address
- Full name
- Position
- Company
- Verification status

### Enrichment

Enrich company or contact data using email or domain.

**Input:**

- **Email** (optional) - Email address to enrich
- **Domain** (optional) - Domain to enrich

**Output:**

- Full profile data
- Company information
- Social profiles
- Technologies used
- Employee count

### Phone Finder

Find phone numbers associated with a domain, email, or LinkedIn URL.

**Input:**

- **Domain** (optional) - Company domain
- **Email** (optional) - Email address
- **LinkedIn URL** (optional) - LinkedIn profile URL

**Output:**

- Phone number(s)
- Phone type (mobile/work)
- Country code
- Verified status

## Example Workflows

### Lead Enrichment Pipeline

**Trigger:** HTTP Webhook (receives lead data)

**Steps:**

1. **Parse webhook data** - Extract name, company, domain
2. **Tomba - Email Finder** - Find email using name + domain
3. **Tomba - Email Verifier** - Verify the found email
4. **Tomba - Enrichment** - Get additional profile data
5. **Filter** - Only continue if email is deliverable
6. **Send to CRM** - Create lead in Salesforce/HubSpot
7. **Slack notification** - Alert sales team

**Code Example:**

```javascript
export default defineComponent({
    async run({ steps, $ }) {
        const lead = steps.trigger.event.body;

        // Find email
        const emailResult = await axios($, {
            url: `https://api.tomba.io/v1/email-finder`,
            params: {
                domain: lead.domain,
                first_name: lead.firstName,
                last_name: lead.lastName,
            },
            headers: {
                "X-Tomba-Key": this.tomba.$auth.api_key,
                "X-Tomba-Secret": this.tomba.$auth.secret_key,
            },
        });

        // Verify email
        const verifyResult = await axios($, {
            url: `https://api.tomba.io/v1/email-verifier`,
            params: {
                email: emailResult.data.email,
            },
            headers: {
                "X-Tomba-Key": this.tomba.$auth.api_key,
                "X-Tomba-Secret": this.tomba.$auth.secret_key,
            },
        });

        // Return enriched lead data
        return {
            ...lead,
            email: emailResult.data.email,
            verification: verifyResult.data,
        };
    },
});
```

### Email Validation Service

**Trigger:** New row in Google Sheets

**Steps:**

1. **For each row** - Iterate through email list
2. **Tomba - Email Verifier** - Verify each email
3. **Transform data** - Format verification results
4. **Update Google Sheets** - Write verification status
5. **Filter invalid** - Separate invalid emails
6. **Send summary email** - Report validation results

### Company Research Automation

**Trigger:** New company added to CRM

**Steps:**

1. **Extract domain** - Get company website domain
2. **Tomba - Domain Search** - Find all company emails
3. **Tomba - Email Count** - Get total email count
4. **Loop through emails** - Process each found email
5. **Tomba - Enrichment** - Enrich each contact
6. **Store in Database** - Save to PostgreSQL/Airtable
7. **Generate report** - Create company research document

## Advanced Features

### Custom Code Steps

Pipedream allows you to write custom Node.js code for complex logic:

```javascript
export default defineComponent({
    async run({ steps, $ }) {
        const tombaResults = steps.tomba_email_finder.$return_value;

        // Custom validation logic
        if (tombaResults.data.score > 90) {
            // High confidence - proceed with outreach
            return { action: "send_email", email: tombaResults.data.email };
        } else if (tombaResults.data.score > 70) {
            // Medium confidence - manual review
            return { action: "review", email: tombaResults.data.email };
        } else {
            // Low confidence - skip
            return { action: "skip" };
        }
    },
});
```

### Error Handling

Add try-catch blocks for robust workflows:

```javascript
export default defineComponent({
    async run({ steps, $ }) {
        try {
            const result = await axios($, {
                url: `https://api.tomba.io/v1/email-finder`,
                params: steps.trigger.event.body,
                headers: {
                    "X-Tomba-Key": this.tomba.$auth.api_key,
                    "X-Tomba-Secret": this.tomba.$auth.secret_key,
                },
            });
            return result;
        } catch (error) {
            // Log error and return gracefully
            console.error("Tomba API Error:", error);
            return { error: error.message, status: "failed" };
        }
    },
});
```

### Batch Processing

Process multiple items efficiently:

```javascript
export default defineComponent({
    async run({ steps, $ }) {
        const leads = steps.trigger.event.body.leads;

        // Process in batches of 10
        const batchSize = 10;
        const results = [];

        for (let i = 0; i < leads.length; i += batchSize) {
            const batch = leads.slice(i, i + batchSize);

            const promises = batch.map((lead) =>
                axios($, {
                    url: `https://api.tomba.io/v1/email-finder`,
                    params: {
                        domain: lead.domain,
                        first_name: lead.firstName,
                        last_name: lead.lastName,
                    },
                    headers: {
                        "X-Tomba-Key": this.tomba.$auth.api_key,
                        "X-Tomba-Secret": this.tomba.$auth.secret_key,
                    },
                }),
            );

            const batchResults = await Promise.all(promises);
            results.push(...batchResults);

            // Rate limiting - wait between batches
            await new Promise((resolve) => setTimeout(resolve, 1000));
        }

        return results;
    },
});
```

## Troubleshooting

### Authentication Issues

**Problem:** "Authentication failed" or 401 errors

**Solutions:**

- Verify API credentials in [Tomba.io dashboard](https://app.tomba.io/api)
- Reconnect the Tomba account in Pipedream
- Check that your Tomba.io account is active
- Ensure API keys haven't been regenerated

### Rate Limiting

**Problem:** 429 "Too Many Requests" errors

**Solutions:**

- Add delays between API calls using `setTimeout`
- Implement exponential backoff
- Check your [Tomba.io plan limits](https://tomba.io/pricing)
- Use batch processing with rate limiting

**Example with delay:**

```javascript
// Add delay between requests
await new Promise((resolve) => setTimeout(resolve, 1000));
```

### No Data Returned

**Problem:** Empty results from Tomba API

**Solutions:**

- Verify input parameters are correct
- Check that the email/domain exists in Tomba's database
- Review workflow execution logs in Pipedream
- Test the API call directly using curl or Postman

### Workflow Execution Errors

**Problem:** Workflow fails mid-execution

**Solutions:**

- Add error handling with try-catch blocks
- Use conditional steps to handle missing data
- Enable "Continue on error" for non-critical steps
- Check Pipedream's execution history for detailed logs

## Best Practices

1. **Use Environment Variables** - Store sensitive data in Pipedream secrets
2. **Implement Retries** - Add retry logic for failed API calls
3. **Validate Inputs** - Check data before sending to Tomba API
4. **Log Important Events** - Use `console.log()` for debugging
5. **Test Workflows** - Use Pipedream's testing feature before deploying
6. **Monitor Usage** - Track your Tomba.io API usage regularly
7. **Handle Edge Cases** - Account for missing or invalid data
8. **Optimize Performance** - Use parallel processing where possible

## Pipedream Features

### Event Sources

Pipedream can listen to events from various sources:

- HTTP webhooks
- Cron schedules
- Email (incoming)
- RSS feeds
- App events (new row in sheets, new email, etc.)

### Data Stores

Store data between workflow runs:

```javascript
// Store email verification results
await require("@pipedream/platform").axios($, {
    method: "POST",
    url: this.$checkpoint,
    data: {
        email: steps.tomba_verify.$return_value.data.email,
        status: steps.tomba_verify.$return_value.data.result,
        timestamp: Date.now(),
    },
});
```

### SQL Queries

Query databases directly in workflows:

```javascript
import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();
await prisma.lead.create({
    data: {
        email: steps.tomba_finder.$return_value.data.email,
        verified: true,
    },
});
```

## API Rate Limits

Tomba.io API limits vary by plan:

- **Free**: 50 requests/month
- **Starter**: 1,000 requests/month
- **Growth**: 5,000 requests/month
- **Business**: 25,000 requests/month
- **Enterprise**: Custom limits

[View detailed pricing](https://tomba.io/pricing)

## Pipedream Pricing

- **Free**: 100 workflow executions/day
- **Basic**: $19/month - 1,000 executions/day
- **Advanced**: $49/month - 5,000 executions/day
- **Business**: Custom pricing

[View Pipedream pricing](https://pipedream.com/pricing)

## Resources

- [Tomba.io API Documentation](https://docs.tomba.io)
- [Pipedream Documentation](https://pipedream.com/docs)
- [Tomba on Pipedream](https://pipedream.com/apps/tomba)
- [Pipedream Community](https://pipedream.com/community)
- [API Status](https://status.tomba.io)

## Support

### Tomba.io Support

- Email: [support@tomba.io](mailto:support@tomba.io)
- Dashboard: [app.tomba.io](https://app.tomba.io)

### Pipedream Support

- Community: [pipedream.com/community](https://pipedream.com/community)
- Documentation: [pipedream.com/docs](https://pipedream.com/docs)
- Twitter: [@PipedreamHQ](https://twitter.com/PipedreamHQ)

## FAQs

**Q: Can I use Tomba.io in scheduled workflows?**
A: Yes, create a Cron trigger and connect Tomba actions to run on a schedule.

**Q: How do I handle pagination in Domain Search?**
A: Use a loop step to iterate through pages, incrementing the page parameter.

**Q: Can I export Tomba data to a database?**
A: Yes, use Pipedream's database integrations (PostgreSQL, MySQL, etc.) after Tomba steps.

**Q: Is it possible to combine multiple Tomba actions?**
A: Absolutely! Chain multiple Tomba actions together in a single workflow.

**Q: How do I test my workflow without consuming API credits?**
A: Use Pipedream's test mode with sample data before deploying to production.

## Version History

**v1.0.0** - Initial Pipedream integration

- Email Finder action
- Email Verifier action
- Domain Search action
- LinkedIn Finder action
- Enrichment action
- Phone Finder action
- Full Node.js SDK support