# Google Sheets Add-ons

Clearout for Sheets is a Google Sheets add-on that lets you **verify, clean, and find business email addresses directly inside your spreadsheets**. You can use it both to cleanse existing lists and to build new B2B prospect lists with minimal manual effort.

The add-on provides two primary workflows:

* **Email Verifier** – validate and enrich email addresses already present in your sheet.
* **Email Finder** – discover likely business email addresses from names, company information, and domains.

***

## Installation

{% stepper %}
{% step %}
Open any Google Sheet using your Google account.

{% endstep %}

{% step %}
Go to **Extensions → Add-ons → Get add-ons** to open the Google Workspace Marketplace.

{% endstep %}

{% step %}
Search for **Clearout for Sheets** and open the listing.

<div data-with-frame="true"><figure><img src="/files/NTnuf0OGEbTCH6J38spJ" alt=""><figcaption></figcaption></figure></div>

{% endstep %}

{% step %}
Click **Install** and approve the requested permissions to connect Clearout with your Google account and Sheets.

{% endstep %}

{% step %}
After installation, return to your sheet and open **Extensions → Clearout for Sheets → Open** to launch the add-on.
{% endstep %}
{% endstepper %}

Clearout runs in a sidebar inside Google Sheets, so you can work with your data without leaving the spreadsheet.

## Connecting your Clearout account

Before running any verification or finder operations, connect your Clearout account:

* When you first open the sidebar, you'll be asked to enter your **Clearout API key**.
* The add-on securely stores this token as a per-user setting so each collaborator uses their own account and credits.
* Your name and credit balance are displayed on adding a valid API key.

<div data-with-frame="true"><figure><img src="/files/YvfWf6Hl5cQiNmzX8q8g" alt=""><figcaption></figcaption></figure></div>

{% hint style="warning" %}
If your token becomes invalid (for example, after a reset), you'll be prompted to re-enter it before you can run new jobs.
{% endhint %}

***

## Email Verifier

Use the Email Verifier to validate and enrich email addresses already present in your sheet.

### Preparing your sheet

* Place email addresses in a dedicated column and optionally add a header such as `Email`, `Email Address`, or `Contact Email`.
* Clearout automatically scans header names and sample values to detect the most likely email column, even when headers use variations like `User Email` or `E-mail Address`.

If automatic detection is incorrect, you can manually choose the correct column from a dropdown in the sidebar.

### Selecting rows to verify

You can control which rows are processed:

| Option                 | Behavior                                                                         |
| ---------------------- | -------------------------------------------------------------------------------- |
| **Entire sheet**       | Runs verification across all rows with data in the selected email column.        |
| **Selected rows only** | Choose a specific range and enable **Verify only selected rows** in the sidebar. |

{% hint style="info" %}
When Google Sheets filters are active, Clearout skips filtered-out rows and processes only those currently visible.
{% endhint %}

### Email Verifier preferences

Email Verifier preferences are stored per user so your settings do not affect other collaborators on the same sheet.

| Option                | Description                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------- |
| **Output columns**    | Choose which results to write (status, safe-to-send, reasons, bounce type, timestamps, and more). |
| **Timeout**           | API timeout per batch — 5, 10, 15, 20, 25, or 30 seconds.                                         |
| **Remove duplicates** | Avoid processing the same email address more than once.                                           |
| **Remove empty rows** | Skip rows where the email column is blank.                                                        |
| **Reverify rule**     | Re-verify only `unknown`, `invalid`, `failed`, or results older than a selected threshold.        |

Preferences are remembered between sessions for each user, making repeated tasks faster.

### Running verification

When you start a verifier run:

* The add-on groups rows into batches, deduplicates repeated requests, and calls the Clearout API using batch requests for efficiency.
* Results are written back to the sheet in grouped ranges to improve performance on large datasets.

#### Long-running sheets

If your sheet is large, the run may pause before Google Apps Script's hard 6-minute limit:

* Clearout stops intentionally near the 5-minute mark, saves run state for the current user, and shows a **Resume** prompt in the sidebar.
* When you click **Resume**, the add-on continues from the same spreadsheet, sheet tab, and email column selection used for the original run.

### Re-verifying failed or stale rows

Clearout includes a dedicated `failed` rule for re-runs:

* If a batch fails due to a network or API issue, that batch is marked as `failed` and the reason column shows a generic error message.
* Re-run verification using the **Only if status is Failed** reverify rule to retry only those rows.

This avoids reprocessing rows that already have valid, up-to-date results.

<div data-with-frame="true"><figure><img src="/files/cNoQLRLZdQu4STq8sePD" alt=""><figcaption></figcaption></figure></div>

***

## Email Finder

Use the Email Finder to discover likely business email addresses based on contact details stored in your sheet.

### Required fields

For the best results, provide:

* **First name** and **last name** columns.
* At least one of: **company name** or **domain**.

Use clear headers such as `First Name`, `Last Name`, `Company`, and `Domain`. The add-on also recognizes common variants like `Given Name`, `Surname`, `Company Name`, and `Website`.

{% hint style="info" %}
The finder can still work when some fields are missing, but more complete input generally produces better results.
{% endhint %}

### Column mapping

The Email Finder sidebar displays a mapping interface:

* Clearout auto-detects likely columns for First Name, Last Name, Company, and Domain using header patterns and sample cell values.
* A **preview list** shows sample values from each column so you can confirm the mapping is correct before running.

If your table includes headers, keep the **My data has headers** option enabled to avoid processing the header row.

### Email Finder preferences

Email Finder preferences are per user and independent from Email verifier settings.

| Option                | Description                                                                                                                                    |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Output columns**    | Choose which results to create (email address, finder status, reason, confidence score, domain, role account flag, business type, found time). |
| **Timeout**           | Finder API timeout per email — 5 to 30 seconds.                                                                                                |
| **Remove duplicates** | Skip repeated combinations of input fields.                                                                                                    |
| **Remove empty rows** | Ignore rows that lack required input fields.                                                                                                   |
| **Re-find rule**      | Re-run only when status is `Not Found`, `failed`, or beyond a certain age.                                                                     |

<div data-with-frame="true"><figure><img src="/files/pO4Eu1XqPsc5nyPWLbKJ" alt=""><figcaption></figcaption></figure></div>

### Running Email Finder

When you start a Email Finder run:

* The add-on batches rows and sends finder requests in bulk, then writes results to the selected output columns.
* Like the Email Verifier, Email Finder runs are **resumable** — long runs may pause near the time limit and resume later using the same mapping.

***

## Filters, resumes, and cancellations

Clearout for Sheets is designed to handle real-world usage with large sheets and multiple collaborators.

### Working with filters

When you apply filters in the Google Sheets UI:

* Clearout respects the active filters and processes **only rows that are visible** in the current view.
* Rows hidden by filters are skipped, allowing you to restrict operations to specific segments without copying data.

This behavior applies to both Email Verifier and Email Finder workflows.

### Resumable runs

Because Google Apps Script imposes execution time limits:

* Clearout tracks the start time of each run and stops before hitting the hard 6-minute limit.
* When a run pauses, the add-on stores a resumable state for that user, including the spreadsheet, sheet tab, and relevant column mappings.

When you open the sidebar again, you may see a **Resume** prompt. Resuming continues from the same sheet and context. If you've switched to another sheet, you may be asked to return to the original before resuming.

### Cancelling a run

You can cancel an in-progress run from the sidebar:

* Cancellation is checked **between batches** — the current batch finishes before the run stops.
* After the batch completes, the run is marked as cancelled and converted into a resumable state so you can decide later whether to continue or discard it.

{% hint style="info" %}
This design ensures partial results are written consistently while still giving you control over long operations.
{% endhint %}

### Concurrency and collaboration

Clearout prevents overlapping runs on the same spreadsheet:

* Only **one Email Verifier or Email Finder run** can be active per spreadsheet at a time.
* If another user tries to start a run while one is already in progress, they'll see a message that another process is running and may need to wait up to 6 minutes.

If a previous run fails before releasing its lock, the concurrency guard automatically expires after its time-to-live so new runs can proceed.

***

## Output columns

Clearout writes results into dedicated columns so that your original data remains intact.

### Email Verifier columns

| Column name                  | Description                                                              |
| ---------------------------- | ------------------------------------------------------------------------ |
| Clearout Verification Status | Overall result: `valid`, `invalid`, `catch-all`, `unknown`, or `failed`. |
| Clearout Safe To Send        | Whether the email is considered safe to send.                            |
| Clearout Reason              | Explanation for the status (e.g. syntax issue, mailbox error).           |
| Clearout Bounce Type         | Bounce classification when applicable.                                   |
| Clearout Verified At (UTC)   | Verification timestamp in UTC.                                           |
| Clearout Time Taken (ms)     | Time taken to verify the email in milliseconds.                          |
| Clearout Disposable Status   | Whether the address uses a disposable email service.                     |
| Clearout Free Account Status | Whether the email is from a free provider.                               |
| Clearout Role Account Status | Whether the address is a role account (e.g. `support`, `sales`).         |
| Clearout Suggested Email     | Suggested correction when a possible typo is detected.                   |
| Clearout Gibberish Status    | Whether the email appears to be gibberish.                               |
| Clearout Account             | Local part of the email (before the `@`).                                |
| Clearout Domain              | Domain part of the email (after the `@`).                                |
| Clearout MX Record           | MX record details when available.                                        |
| Clearout SMTP Provider       | Detected SMTP provider if identifiable.                                  |
| Clearout AI Verdict          | Additional AI-driven interpretation of the result.                       |

<div data-with-frame="true"><figure><img src="/files/6koBNuQdyXyfHRZrhtvr" alt=""><figcaption></figcaption></figure></div>

You can choose which columns to include via Email Verifier preferences.

### Email Finder columns

| Column name                      | Description                                              |
| -------------------------------- | -------------------------------------------------------- |
| Clearout Finder Email Address    | Email address found for the contact.                     |
| Clearout Finder Status           | `found`, `not found`, or `failed`.                       |
| Clearout Finder Reason           | Reason when the email could not be found or is unusable. |
| Clearout Finder Confidence Score | How strong the match is.                                 |
| Clearout Finder Domain           | Domain associated with the found email.                  |
| Clearout Finder Role Account     | Whether the found email is a role email address.         |
| Clearout Finder Business         | Whether the found email is a business email address.     |
| Clearout Finder Found Time       | Timestamp when the email was found.                      |

<div data-with-frame="true"><figure><img src="/files/pKRwOmul7kHxdwK0oFST" alt=""><figcaption></figcaption></figure></div>

As with Email Verifier outputs, you can enable or disable specific columns in Email Finder preferences.

***

## Conditional formatting

Clearout enhances the sheet with conditional formatting so you can scan results quickly.

### Email Verifier

| Status                                              | Color  |
| --------------------------------------------------- | ------ |
| <mark style="color:$success;">`valid`</mark>        | Green  |
| <mark style="color:red;">`invalid`</mark>           | Red    |
| <mark style="color:blue;">`catch_all`</mark>        | Blue   |
| <mark style="color:$info;">`unknown`</mark>         | Gray   |
| <mark style="color:$primary;">`Verifying...`</mark> | Orange |
| <mark style="color:red;">`failed`</mark>            | Red    |

### Finder confidence colors

| Confidence range | Color |
| ---------------- | ----- |
| ≥ 90             | Green |
| ≥ 80 and < 90    | Blue  |
| < 80             | Gray  |

***

## Troubleshooting

| Symptom                             | What to do                                                                                                                |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Resume prompt appears unexpectedly  | There is a paused or cancelled run for this sheet. Resume from the same sheet or discard the paused state in the sidebar. |
| "Another run is already active"     | A job is running or recently failed. Wait a few minutes for the lock to expire, then try again.                           |
| Run stops before finishing all rows | The add-on likely paused near the time limit. Click **Resume** to continue.                                               |
| Only some rows were processed       | Check whether a filter is active — Clearout intentionally skips rows hidden by filters.                                   |
| Cancel did not stop immediately     | Cancellation applies between batches; the current batch must finish first.                                                |
| Token or credits not loading        | Re-enter or refresh your Clearout API key in the sidebar.                                                                 |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clearout.io/platform-features/tools/google-sheets-add-ons.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.