@pipedream/tomba 0.0.5 → 0.1.0

package/README.md

@@ -1,11 +1,50 @@
 # Overview
 
-The Tomba API is a potent tool for email discovery and domain search. With it, you can automate the process of finding and verifying email addresses linked to a domain, which could be pivotal for lead generation, outreach campaigns, or market research. By leveraging the Tomba API on Pipedream, you streamline these tasks into efficient workflows that can interact with numerous other apps and services, such as CRMs, marketing automation tools, or database managers. The synergy between Tomba and Pipedream allows for real-time processing and integration of email data within your existing business systems.
+The Tomba API is a comprehensive email finder and verification service that enables you to discover, verify, and enrich email addresses and contact data. With Tomba, you can find email addresses from domains, names, LinkedIn profiles, or blog posts, verify email deliverability, and gather detailed company intelligence. Leverage Pipedream's capabilities to integrate Tomba with hundreds of other apps, creating powerful automated workflows for lead generation, email verification, contact enrichment, and competitive research.
 
 # Example Use Cases
 
-- **Lead Generation Automation**: Trigger a workflow when a new company is added to your CRM. Use Tomba to find email addresses associated with the company's domain. Enrich lead data in the CRM and follow up with an automated outreach sequence using an email marketing tool like Mailchimp.
+- **Lead Generation Automation**: Trigger a workflow when a new company is added to your CRM. Use Tomba to find email addresses associated with the company's domain, enrich the lead data, and automatically add qualified contacts to your outreach sequences in tools like Mailchimp or HubSpot.
 
-- **Domain Research and Monitoring**: Schedule a regular Pipedream workflow that checks a list of domains and uses Tomba to gather any new email addresses. Store the findings in a Google Sheets document and send a Slack notification to the sales team with any updates or new leads.
+- **Email List Verification**: Before launching an email campaign, run your contact list through a Pipedream workflow that uses Tomba's email verifier to validate each address. Automatically remove invalid emails and update your email platform like SendGrid, ensuring higher deliverability rates and protecting your sender reputation.
 
-- **Verification and Clean-up for Marketing Campaigns**: Before launching an email campaign, run your email list through a Pipedream workflow that uses Tomba to verify the validity of each address. Update the campaign list in your email platform, like Sendgrid, to omit invalid or nonexistent emails, ensuring higher deliverability and engagement rates.
+- **Competitive Intelligence Gathering**: Set up a scheduled workflow that monitors competitor domains using Tomba's domain search and technology detection features. Store findings in Google Sheets and send Slack notifications to your team with insights about competitor email patterns, employee counts, and tech stacks.
+
+# Getting Started
+
+To start using Tomba with Pipedream:
+
+1. **Sign up for Tomba**: Create an account at [tomba.io](https://tomba.io) and obtain your API key and secret from the dashboard.
+
+2. **Connect to Pipedream**: In your Pipedream workflow, add a Tomba action and authenticate using your API credentials.
+
+3. **Choose your action**: Select from 20 available actions including Email Finder, Domain Search, Email Verifier, and Company Search.
+
+4. **Configure parameters**: Set up your search criteria such as domain names, email addresses, or LinkedIn URLs.
+
+5. **Test and deploy**: Run your workflow to verify the results, then deploy for automated execution.
+
+# Troubleshooting
+
+**Authentication Issues**
+
+- Verify your API key and secret are correctly entered in the Pipedream connection settings
+- Check that your Tomba account has sufficient credits and is not suspended
+- Ensure your API keys haven't expired or been regenerated
+
+**Rate Limiting**
+
+- Tomba enforces API rate limits based on your subscription plan
+- Implement delays between requests in high-volume workflows
+- Monitor your usage with the "Get Usage" action to track quota consumption
+
+**No Results Found**
+
+- For Email Finder: Try different name variations or check if the domain uses a non-standard email format
+- For Domain Search: Some domains may have limited public email exposure
+- For LinkedIn Finder: Ensure the LinkedIn URL is publicly accessible and properly formatted
+
+**Invalid Email Addresses**
+
+- Use the Email Verifier action to validate emails before adding them to campaigns
+- Some emails may exist but have strict spam filters that prevent verification

package/actions/enrich-email/enrich-email.mjs

@@ -0,0 +1,33 @@
+import app from "../../tomba.app.mjs";
+
+export default {
+  key: "tomba-enrich-email",
+  name: "Enrich Email",
+  description:
+    "Look up person and company data based on an email. [See the documentation](https://docs.tomba.io/api/finder#email-enrichment)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    email: {
+      propDefinition: [
+        app,
+        "email",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.app.enrichEmail({
+      $,
+      email: this.email,
+    });
+
+    $.export("$summary", `Successfully enriched data for email: ${this.email}`);
+    return response;
+  },
+};

package/actions/find-author/find-author.mjs

@@ -0,0 +1,36 @@
+import app from "../../tomba.app.mjs";
+
+export default {
+  key: "tomba-find-author",
+  name: "Find Author",
+  description:
+    "Generate or retrieve the most likely email address from a blog post URL. [See the documentation](https://docs.tomba.io/api/finder#author-finder)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    blogUrl: {
+      propDefinition: [
+        app,
+        "blogUrl",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.app.findAuthor({
+      $,
+      blogUrl: this.blogUrl,
+    });
+
+    $.export(
+      "$summary",
+      `Successfully found author information for blog post: ${this.blogUrl}`,
+    );
+    return response;
+  },
+};

package/actions/find-email/find-email.mjs

@@ -0,0 +1,50 @@
+import app from "../../tomba.app.mjs";
+
+export default {
+  key: "tomba-find-email",
+  name: "Find Email",
+  description:
+    "Generate or retrieve the most likely email address from a domain name, a first name and a last name. [See the documentation](https://docs.tomba.io/api/finder#email-finder)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    domain: {
+      propDefinition: [
+        app,
+        "domain",
+      ],
+    },
+    firstName: {
+      propDefinition: [
+        app,
+        "firstName",
+      ],
+    },
+    lastName: {
+      propDefinition: [
+        app,
+        "lastName",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.app.findEmail({
+      $,
+      domain: this.domain,
+      firstName: this.firstName,
+      lastName: this.lastName,
+    });
+
+    $.export(
+      "$summary",
+      `Successfully found email for ${this.firstName} ${this.lastName} at ${this.domain}`,
+    );
+    return response;
+  },
+};

package/actions/find-linkedin-email/find-linkedin-email.mjs

@@ -0,0 +1,36 @@
+import app from "../../tomba.app.mjs";
+
+export default {
+  key: "tomba-find-linkedin-email",
+  name: "Find LinkedIn Email",
+  description:
+    "Generate or retrieve the most likely email address from a LinkedIn URL. [See the documentation](https://docs.tomba.io/api/finder#linkedin-finder)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    linkedinUrl: {
+      propDefinition: [
+        app,
+        "linkedinUrl",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.app.findLinkedIn({
+      $,
+      linkedinUrl: this.linkedinUrl,
+    });
+
+    $.export(
+      "$summary",
+      `Successfully found email from LinkedIn profile: ${this.linkedinUrl}`,
+    );
+    return response;
+  },
+};

package/actions/find-phone/find-phone.mjs

@@ -0,0 +1,64 @@
+import app from "../../tomba.app.mjs";
+
+export default {
+  key: "tomba-find-phone",
+  name: "Find Phone",
+  description:
+    "Search for phone numbers based on an email, domain, or LinkedIn URL. [See the documentation](https://docs.tomba.io/api/phone#phone-finder)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    searchType: {
+      type: "string",
+      label: "Search Type",
+      description: "Choose the type of search to perform",
+      options: [
+        {
+          label: "Search by Domain",
+          value: "domain",
+        },
+        {
+          label: "Search by Email",
+          value: "email",
+        },
+        {
+          label: "Search by LinkedIn URL",
+          value: "linkedin",
+        },
+      ],
+      default: "domain",
+    },
+    search: {
+      type: "string",
+      label: "Search Input",
+      description: "Enter the domain, email address, or LinkedIn URL to search",
+    },
+  },
+  async run({ $ }) {
+    const params = {};
+    if (this.searchType === "domain") {
+      params.domain = this.search;
+    } else if (this.searchType === "email") {
+      params.email = this.search;
+    } else if (this.searchType === "linkedin") {
+      params.linkedinUrl = this.search;
+    }
+
+    const response = await this.app.findPhone({
+      $,
+      ...params,
+    });
+
+    $.export(
+      "$summary",
+      `Successfully searched for phone numbers using ${this.searchType}: ${this.search}`,
+    );
+    return response;
+  },
+};

package/actions/find-similar-domains/find-similar-domains.mjs

@@ -0,0 +1,36 @@
+import app from "../../tomba.app.mjs";
+
+export default {
+  key: "tomba-find-similar-domains",
+  name: "Find Similar Domains",
+  description:
+    "Retrieve similar domains based on a specific domain. [See the documentation](https://docs.tomba.io/api/~endpoints#similar)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    domain: {
+      propDefinition: [
+        app,
+        "domain",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.app.findSimilarDomains({
+      $,
+      domain: this.domain,
+    });
+
+    $.export(
+      "$summary",
+      `Successfully found similar domains for: ${this.domain}`,
+    );
+    return response;
+  },
+};

package/actions/get-account/get-account.mjs

@@ -0,0 +1,26 @@
+import app from "../../tomba.app.mjs";
+
+export default {
+  key: "tomba-get-account",
+  name: "Get Account",
+  description:
+    "Returns information about the current account including usage statistics and plan details. [See the documentation](https://docs.tomba.io/api/account#get-account)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+  },
+  async run({ $ }) {
+    const response = await this.app.getAccount({
+      $,
+    });
+
+    $.export("$summary", "Successfully retrieved account information");
+    return response;
+  },
+};

package/actions/get-domain-status/get-domain-status.mjs

@@ -0,0 +1,36 @@
+import app from "../../tomba.app.mjs";
+
+export default {
+  key: "tomba-get-domain-status",
+  name: "Get Domain Status",
+  description:
+    "Find domain status if is webmail or disposable. [See the documentation](https://docs.tomba.io/api/~endpoints#domain-status)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    domain: {
+      propDefinition: [
+        app,
+        "domain",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.app.getDomainStatus({
+      $,
+      domain: this.domain,
+    });
+
+    $.export(
+      "$summary",
+      `Successfully retrieved domain status for: ${this.domain}`,
+    );
+    return response;
+  },
+};

package/actions/get-domain-suggestions/get-domain-suggestions.mjs

@@ -0,0 +1,37 @@
+import app from "../../tomba.app.mjs";
+
+export default {
+  key: "tomba-get-domain-suggestions",
+  name: "Get Domain Suggestions",
+  description:
+    "Retrieve a list of suggested domains similar to or related to your search query. This helps discover competitors, similar companies, and related businesses for market research and prospecting. [See the documentation](https://docs.tomba.io/api/domain-suggestions#get-domain-suggestions)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    query: {
+      propDefinition: [
+        app,
+        "query",
+      ],
+      description: "The domain or company name to find suggestions for",
+    },
+  },
+  async run({ $ }) {
+    const response = await this.app.getDomainSuggestions({
+      $,
+      query: this.query,
+    });
+
+    $.export(
+      "$summary",
+      `Successfully found domain suggestions for: ${this.query}`,
+    );
+    return response;
+  },
+};

package/actions/get-email-count/get-email-count.mjs

@@ -0,0 +1,36 @@
+import app from "../../tomba.app.mjs";
+
+export default {
+  key: "tomba-get-email-count",
+  name: "Get Email Count",
+  description:
+    "Find total email addresses we have for one domain. [See the documentation](https://docs.tomba.io/api/finder#email-count)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    domain: {
+      propDefinition: [
+        app,
+        "domain",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.app.getEmailCount({
+      $,
+      domain: this.domain,
+    });
+
+    $.export(
+      "$summary",
+      `Successfully retrieved email count for domain: ${this.domain}`,
+    );
+    return response;
+  },
+};

package/actions/get-email-format/get-email-format.mjs

@@ -0,0 +1,36 @@
+import app from "../../tomba.app.mjs";
+
+export default {
+  key: "tomba-get-email-format",
+  name: "Get Email Format",
+  description:
+    "Retrieve the email format patterns used by a specific domain. [See the documentation](https://docs.tomba.io/api/finder#email-format)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    domain: {
+      propDefinition: [
+        app,
+        "domain",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.app.getEmailFormat({
+      $,
+      domain: this.domain,
+    });
+
+    $.export(
+      "$summary",
+      `Successfully retrieved email format patterns for domain: ${this.domain}`,
+    );
+    return response;
+  },
+};

package/actions/get-email-sources/get-email-sources.mjs

@@ -0,0 +1,33 @@
+import app from "../../tomba.app.mjs";
+
+export default {
+  key: "tomba-get-email-sources",
+  name: "Get Email Sources",
+  description:
+    "Find email address source somewhere on the web. [See the documentation](https://docs.tomba.io/api/~endpoints#email-sources)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    email: {
+      propDefinition: [
+        app,
+        "email",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.app.getEmailSources({
+      $,
+      email: this.email,
+    });
+
+    $.export("$summary", `Successfully found sources for email: ${this.email}`);
+    return response;
+  },
+};

package/actions/get-location/get-location.mjs

@@ -0,0 +1,36 @@
+import app from "../../tomba.app.mjs";
+
+export default {
+  key: "tomba-get-location",
+  name: "Get Location",
+  description:
+    "Get employees location based on the domain name. [See the documentation](https://docs.tomba.io/api/finder#location)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    domain: {
+      propDefinition: [
+        app,
+        "domain",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.app.getLocation({
+      $,
+      domain: this.domain,
+    });
+
+    $.export(
+      "$summary",
+      `Successfully retrieved location data for domain: ${this.domain}`,
+    );
+    return response;
+  },
+};

package/actions/get-logs/get-logs.mjs

@@ -0,0 +1,45 @@
+import app from "../../tomba.app.mjs";
+
+export default {
+  key: "tomba-get-logs",
+  name: "Get Logs",
+  description:
+    "Retrieve API request logs for your account with pagination support. [See the documentation](https://docs.tomba.io/api/account#retrieve-api-logs)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    limit: {
+      propDefinition: [
+        app,
+        "limit",
+      ],
+    },
+    page: {
+      propDefinition: [
+        app,
+        "page",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const offset = (this.page - 1) * this.limit;
+
+    const response = await this.app.getLogs({
+      $,
+      limit: this.limit,
+      offset,
+    });
+
+    $.export(
+      "$summary",
+      `Successfully retrieved ${response.data?.length || 0} API logs`,
+    );
+    return response;
+  },
+};

package/actions/get-technology/get-technology.mjs

@@ -0,0 +1,36 @@
+import app from "../../tomba.app.mjs";
+
+export default {
+  key: "tomba-get-technology",
+  name: "Get Technology",
+  description:
+    "Retrieve the technologies used by a specific domain. [See the documentation](https://docs.tomba.io/api/~endpoints#technology)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+    domain: {
+      propDefinition: [
+        app,
+        "domain",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.app.getTechnology({
+      $,
+      domain: this.domain,
+    });
+
+    $.export(
+      "$summary",
+      `Successfully retrieved technology stack for domain: ${this.domain}`,
+    );
+    return response;
+  },
+};

package/actions/get-usage/get-usage.mjs

@@ -0,0 +1,26 @@
+import app from "../../tomba.app.mjs";
+
+export default {
+  key: "tomba-get-usage",
+  name: "Get Usage",
+  description:
+    "Retrieve API usage statistics and quota information for your account. [See the documentation](https://docs.tomba.io/api/account#retrieve-api-usage)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    app,
+  },
+  async run({ $ }) {
+    const response = await this.app.getUsage({
+      $,
+    });
+
+    $.export("$summary", "Successfully retrieved API usage statistics");
+    return response;
+  },
+};