Merge branch 'master' of ssh://github.com/reacherhq/check-if-email-ex…

…ists

docs/SUMMARY.md

@@ -11,19 +11,23 @@
 
 * [SaaS vs Self-Host](self-hosting/saas-vs-self-host.md)
 * [Install Reacher in 20min](self-hosting/install.md)
-* [Licensing](self-hosting/licensing.md)
-* [Scaling for Production](self-hosting/scaling-for-production.md)
+* [Scaling for Production](self-hosting/scaling-for-production/README.md)
+  * [Option 1: Manage scaling yourself](self-hosting/scaling-for-production/option-1-manage-scaling-yourself.md)
+  * [Option 2: RabbitMQ-based Queue Architecture](self-hosting/scaling-for-production/option-2-rabbitmq-based-queue-architecture.md)
+* [Licensing](self-hosting/licensing/README.md)
+  * [Commercial License Trial](self-hosting/licensing/commercial-license-trial.md)
 * [Proxies](self-hosting/proxies.md)
-* [Bulk Verification (v0.7)](self-hosting/bulk.md)
+* [Reacher Configuration](self-hosting/reacher-configuration-v0.10.md)
 * [Debugging Reacher](self-hosting/debugging-reacher.md)
-* [Docker Environment Variables (v0.7)](self-hosting/docker-environment-variables.md)
 
 ## Advanced
 
 * [OpenAPI](advanced/openapi/README.md)
   * [/v0/check\_email](advanced/openapi/v0-check_email.md)
   * [/v1/check\_email](advanced/openapi/v1-check_email.md)
   * [/v1/bulk](advanced/openapi/v1-bulk.md)
+* [Run your own Proxy](advanced/run-your-own-proxy.md)
 * [Migrations](advanced/migrations/README.md)
-  * [Migrating from 0.7 to 0.10 (beta)](advanced/migrations/migrating-from-0.7-to-0.10-beta.md)
-  * [Reacher Configuration (v0.10)](advanced/migrations/reacher-configuration-v0.10.md)
+  * [Migrating from 0.7 to 0.10](advanced/migrations/migrating-from-0.7-to-0.10-beta.md)
+  * [Bulk Verification (v0.7)](advanced/migrations/bulk.md)
+  * [Docker Environment Variables (v0.7)](advanced/migrations/docker-environment-variables.md)

docs/self-hosting/bulk.md → docs/advanced/migrations/bulk.md

@@ -1,10 +1,10 @@
-# Bulk Verification
+# Bulk Verification (v0.7)
 
 The default Reacher API only exposes one endpoint, `/v0/check_email`, which allows verifying one email at a time. The optional Bulk Verification API allows you to queue up a list of emails in one go.
 
 ## Prerequisites
 
-* A self-hosted setup, see [install.md](install.md "mention").
+* A self-hosted setup, see [install.md](../../self-hosting/install.md "mention").
 * A PostgreSQL database, you can start for free with [Supabase](https://supabase.com/) (no affiliation).
 
 ## Get Started

docs/self-hosting/docker-environment-variables.md → docs/advanced/migrations/docker-environment-variables.md

@@ -1,7 +1,7 @@
 # Docker Environment Variables (v0.7)
 
 {% hint style="info" %}
-This page only applies to Reacher version 0.7. For the `beta` v0.10 version, see [reacher-configuration-v0.10.md](../advanced/migrations/reacher-configuration-v0.10.md "mention").
+This page only applies to Reacher version 0.7. For the `beta` v0.10 version, see [reacher-configuration-v0.10.md](../../self-hosting/reacher-configuration-v0.10.md "mention").
 {% endhint %}
 
 Reacher's software is available on [Docker Hub](https://hub.docker.com/r/reacherhq/backend/tags). You can get started using the default parameters:

docs/advanced/migrations/migrating-from-0.7-to-0.10-beta.md

@@ -1,19 +1,15 @@
-# Migrating from 0.7 to 0.10 (beta)
-
-{% hint style="info" %}
-v0.10 is currently still in `beta` phase.
-{% endhint %}
+# Migrating from 0.7 to 0.10
 
 Reacher v0.10 introduces the `/v1/*` endpoints, namely:
 
-* `/v1/check_email`: Performs a single email verification while respecting the optional throttle and concurrency settings set in [reacher-configuration-v0.10.md](reacher-configuration-v0.10.md "mention").
+* `/v1/check_email`: Performs a single email verification while respecting the optional throttle and concurrency settings set in [reacher-configuration-v0.10.md](../../self-hosting/reacher-configuration-v0.10.md "mention").
 * `/v1/bulk`, `/v1/bulk/{job_id}`, `/v1/bulk/{job_id}/results`: Create a bulk verification job, and query its progress and status. Docs coming soon.
 
 The `/v0/check_email` endpoint **DOES NOT** change, neither in API nor in behavior. More specifically, even if you specify throttle and concurrency settings in the newly introduced Reacher Configuration, they will not be taken into account by the `/v0/check_email` endpoint, which will perform email verification as soon as it receives the request.
 
 ## Environment Variables
 
-With the introduction of [reacher-configuration-v0.10.md](reacher-configuration-v0.10.md "mention"), some of the Environment Variables have changed names.
+With the introduction of [reacher-configuration-v0.10.md](../../self-hosting/reacher-configuration-v0.10.md "mention"), some of the Environment Variables have changed names.
 
 <table><thead><tr><th width="220">Old name</th><th width="211">New name</th><th width="264">Description</th></tr></thead><tbody><tr><td><code>RCH_HTTP_HOST</code></td><td><code>RCH__HTTP_HOST</code></td><td>The host name to bind the HTTP server to.</td></tr><tr><td><code>PORT</code></td><td><code>RCH__HTTP_PORT</code></td><td>The port to bind the HTTP server to, often populated by the cloud provider.</td></tr><tr><td><code>RCH_SENTRY_DSN</code></td><td><code>RCH__SENTRY_DSN</code></td><td>If set, bug reports will be sent to this <a href="https://sentry.io">Sentry</a> DSN.</td></tr><tr><td><code>RCH_HEADER_SECRET</code></td><td><code>RCH__HEADER_SECRET</code></td><td>If set, then all HTTP requests must have the <code>x-reacher-secret</code> header set to this value. This is used to protect the backend against public unwanted HTTP requests.</td></tr><tr><td><code>RCH_FROM_EMAIL</code></td><td><code>RCH__FROM_EMAIL</code></td><td>Email to use in the <code>&#x3C;MAIL FROM:></code> SMTP step. Can be overwritten by each API request's <code>from_email</code> field.</td></tr><tr><td><code>RCH_HELLO_NAME</code></td><td><code>RCH__HELLO_NAME</code></td><td>Name to use in the <code>&#x3C;EHLO></code> SMTP step. Can be overwritten by each API request's <code>hello_name</code> field.</td></tr><tr><td><code>RCH_SMTP_TIMEOUT</code></td><td><code>RCH__SMTP_TIMEOUT</code></td><td>Timeout for each SMTP connection.</td></tr><tr><td><code>RCH_WEBDRIVER_ADDR</code></td><td><code>RCH__WEBDRIVER_ADDR</code></td><td>Set to a running WebDriver process endpoint (e.g. <code>http://localhost:9515</code>) to use a headless navigator to password recovery pages to check Yahoo and Hotmail/Outlook addresses. We recommend <code>chromedriver</code> as it allows parallel requests.</td></tr><tr><td><strong>For Bulk Verification:</strong></td><td></td><td></td></tr><tr><td><code>RCH_ENABLE_BULK</code></td><td><code>RCH__WORKER__ENABLE</code></td><td></td></tr><tr><td><code>DATABASE_URL</code></td><td><code>RCH__WORKER__POSTGRES__DB_URL</code></td><td>[Bulk] Database connection string for storing results and task queue</td></tr><tr><td><code>RCH_DATABASE_MAX_CONNECTIONS</code></td><td>Removed</td><td>[Bulk] Connections created for the database pool</td></tr><tr><td><code>RCH_MINIMUM_TASK_CONCURRENCY</code></td><td>Removed</td><td>[Bulk] Minimum number of concurrent running tasks below which more tasks are fetched</td></tr><tr><td><code>RCH_MAXIMUM_CONCURRENT_TASK_FETCH</code></td><td>Removed</td><td>[Bulk] Maximum number of tasks fetched at once</td></tr></tbody></table>
 

docs/advanced/openapi/v1-bulk.md

@@ -1,9 +1,5 @@
 # /v1/bulk
 
-{% hint style="info" %}
-This endpoint is available starting from Reacher v0.10.
-{% endhint %}
-
 {% swagger src="https://raw.githubusercontent.com/reacherhq/check-if-email-exists/refs/heads/master/backend/openapi.json" path="/v1/bulk" method="post" %}
 [https://raw.githubusercontent.com/reacherhq/check-if-email-exists/refs/heads/master/backend/openapi.json](https://raw.githubusercontent.com/reacherhq/check-if-email-exists/refs/heads/master/backend/openapi.json)
 {% endswagger %}

docs/advanced/openapi/v1-check_email.md

@@ -1,9 +1,5 @@
 # /v1/check\_email
 
-{% hint style="info" %}
-This endpoint is available starting from Reacher v0.10.
-{% endhint %}
-
 {% swagger src="https://raw.githubusercontent.com/reacherhq/check-if-email-exists/refs/heads/master/backend/openapi.json" path="/v1/check_email" method="post" %}
 [https://raw.githubusercontent.com/reacherhq/check-if-email-exists/refs/heads/master/backend/openapi.json](https://raw.githubusercontent.com/reacherhq/check-if-email-exists/refs/heads/master/backend/openapi.json)
 {% endswagger %}

docs/advanced/run-your-own-proxy.md

@@ -0,0 +1,5 @@
+# Run your own Proxy
+
+Reacher integrates seamlessy with [proxies.md](../self-hosting/proxies.md "mention"), and we propose some 3rd-party proxies to use. However, you may also choose to run your own Proxy.
+
+If you're interested in this feature, please contact [amaury@reacher.email](https://app.gitbook.com/u/F1LnsqPFtfUEGlcILLswbbp5cgk2 "mention").

docs/self-hosting/debugging-reacher.md

@@ -1,7 +1,17 @@
 # Debugging Reacher
 
+## How to debug Reacher? 
+
+The reflex to have when debugging Reacher is to set the `-e RUST_LOG=debug` flag to Docker. This will show all debug logs useful to pinpoint where the error happened.
+
+If you still don't understand the error after setting that flag, send an email to [amaury@reacher.email](https://app.gitbook.com/u/F1LnsqPFtfUEGlcILLswbbp5cgk2 "mention") along with those debug logs.
+
 ## How to check if port 25 is open?
 
+{% hint style="info" %}
+This only concerns users installing Reacher on a server without using [proxies.md](proxies.md "mention"). 
+{% endhint %}
+
 When choosing a server to install Reacher on, you need to make sure that the server itself has port `25` open AND the chosen cloud provider allows outbound port `25` connections on its network.
 
 To test this, there are two methods:
@@ -113,7 +123,7 @@ Here are details about some of the most well-known providers:
 * :warning: Digital Ocean: Your account needs to be 60d old, then you can [apply](https://www.digitalocean.com/community/questions/how-i-can-open-port-25-please?answer=67100) to open port 25 (Mar 2020).
 * ❌ GCP: Port 25 closed, [source](https://cloud.google.com/compute/docs/tutorials/sending-mail).
 * ❌ Heroku: Starting from July 2021, Heroku blocks port 25 intermittently according to [this document](https://help.heroku.com/IR3S6I5X/problem-in-sending-e-mails-through-smtp).
-* :warning: Hetzner: Port 25 open according to [unofficial source](https://www.reddit.com/r/hetzner/comments/lb2o13/does\_hetzner\_block\_port\_25/) (Feb 2021), but seems now that you need to request manually.
+* :warning: Hetzner: Port 25 open according to [unofficial source](https://www.reddit.com/r/hetzner/comments/lb2o13/does_hetzner_block_port_25/) (Feb 2021), but seems now that you need to request manually.
 * :warning: Linode: Port 25 closed for new accounts, but can be opened if reverse DNS is set up correctly, [source](https://www.linode.com/docs/guides/running-a-mail-server/#sending-email-on-linode=) (Apr 2022).
 * :white\_check\_mark: OVH: Port 25 open on new instances, but outbound port 25 traffic is monitored to prevent spam (May 2022).
 * :warning: Vultr: Create support ticket to open port 25, [source](https://www.vultr.com/docs/what-ports-are-blocked/), though [recent reports](https://github.com/LukeSmithxyz/emailwiz/issues/172) (May 2022) show that they won’t do it anymore.

docs/self-hosting/install.md

@@ -1,29 +1,43 @@
 # Install Reacher in 20min
 
-Reacher is built with self-hosting as a primary feature, giving you full control over how the service operates on your infrastructure. It can be deployed on a single server in under 20 minutes. This tutorial shows you how.
+Reacher is designed for seamless self-hosting, giving you full control over its operation on your infrastructure. This guide demonstrates how to install and run Reacher on your local computer in under 20 minutes, using a Dockerfile that is provided you as part of the [commercial-license-trial.md](licensing/commercial-license-trial.md "mention").
 
-{% hint style="info" %}
-You can run this tutorial without a Commercial License, as a Free Trial. Read more about the Free Trial in [licensing.md](licensing.md "mention").
-{% endhint %}
+## Prerequisites
+
+* An account on [https://reacher.email](https://reacher.email) (required for the Commercial License Trial and access to the Dockerfile).
+* Docker installed on your system (follow the [Docker installation guide](https://docs.docker.com/get-docker/) for your OS).
+
+## Tutorial Scope: Install Reacher on your local computer
+
+Reacher’s stateless architecture enables easy horizontal scaling by deploying multiple containers, each running a Reacher instance for parallel email verifications. However, for simplicity, this tutorial focuses on a local installation. A further section focuses on [scaling-for-production](scaling-for-production/ "mention").
+
+The provided Dockerfile includes a pre-configured proxy, resolving the common ISP restriction on outgoing requests to port 25 used by Reacher to perform SMTP verifications.
 
-## Tutorial Scope: Install Reacher on a single server
+<details>
 
-Reacher is **stateless** by design, meaning you can deploy multiple containers, each running a separate instance of Reacher, to perform email verifications in parallel. This architecture enables easy horizontal scaling.
+<summary>Understand the features and limitations of the Commercial License Trial.</summary>
 
-However, for the sake of this tutorial, we will install Reacher on a single dedicated server. This allows minimal setup to get Reacher working, and ensures that the chosen cloud provider allows outgoing port 25 requests.
+The Dockerfile provided as part of the Commercial License Trial is designed to enable quick setup for email verifications. Below are its key features and limitations:
 
-If you're interested in ideas for a production deployment setup, skip to [scaling-for-production.md](scaling-for-production.md "mention").
+* **Built-in Proxy Configuration**: we use [**Proxy4Smtp**](https://www.proxy4smtp.com), a 3rd-party proxy with carefully maintained IPs optimized for SMTP verifications. This ensures reliable email verification even in cloud environments with restricted SMTP access. Learn more in [proxies.md](proxies.md "mention").
+* **Daily Verification Limit**: capped at 60 per minute at **10,000 per day**.
+* **Usage Tracking**: verification results are anonymized and sent back to Reacher, and used to monitor daily usage and detect potential abuse.
+
+You can also read more in [commercial-license-trial.md](licensing/commercial-license-trial.md "mention").
+
+</details>
 
 ## Step-by-Step Tutorial
 
-1. Install Docker on your server. You can follow [Docker's guide](https://docs.docker.com/engine/install/) for your OS.
-2. Run Reacher's latest (v0.7) [Docker image](https://hub.docker.com/r/reacherhq/backend):
+1. Navigate to the **Commercial License Trial** tab of your Reacher Dashboard ([go there directly](https://app.reacher.email/en/dashboard/commercial_license)). You'll see a command to run Reacher's latest (v0.10) [Docker image](https://hub.docker.com/r/reacherhq/backend):
 
 ```bash
-docker run -p 8080:8080 reacherhq/backend:latest # v0.7
+docker run -e RCH__COMMERCIAL_LICENSE_TRIAL__API_TOKEN=<YOUR_UNIQUE_TOKEN> -p 8080:8080 reacherhq/commercial-license-trial:latest # v0.10
 ```
 
-You should see the following output:
+Replace `<YOUR_UNIQUE_TOKEN>` with your unique API token shown in the dashboard.
+
+Expected output:
 
 ```bash
 2024-09-19T12:58:32.918254Z  INFO reacher: Running Reacher version="0.10.0"
@@ -34,22 +48,45 @@ ChromeDriver was started successfully.
 2024-09-19T12:58:32.976589Z  INFO reacher: Server is listening host=0.0.0.0 port=80
 ```
 
-Advanced users can set additional [docker-environment-variables.md](docker-environment-variables.md "mention").
+If you see an error message, such as `` Error: missing field `api_token` ``, double-check the `-e RCH__COMMERCIAL_LICENSE_TRIAL__API_TOKEN` flag you passed. If you see other errors, either try [debugging-reacher.md](debugging-reacher.md "mention") or send an email to [amaury@reacher.email](https://app.gitbook.com/u/F1LnsqPFtfUEGlcILLswbbp5cgk2 "mention").
 
-3. Make sure that you can verify an email remotely by running the following command from your local machine.
+Advanced users can also set additional [reacher-configuration-v0.10.md](reacher-configuration-v0.10.md "mention").
 
-```bash
-curl -X POST \
-	-H'Content-Type: application/json' \
+4. Verify an email by running the following command in another terminal.
+
+<pre class="language-bash"><code class="lang-bash"><strong>curl -X POST \
+</strong>	-H'Content-Type: application/json' \
 	-d'{"to_email":"amaury@reacher.email"}' \
-	http://<IP_OF_YOUR_SERVER>:8080/v0/check_email
+	http://localhost:8080/v1/check_email
+</code></pre>
+
+Advanced users can pass additional configuration fields to the  [v1-check\_email.md](../advanced/openapi/v1-check_email.md "mention") endpoint.
+
+4. If successful, you'll see JSON object with an `is_reachable` field.
+
+```json
+{
+    "input": "amaury@reacher.email",
+    "is_reachable": "safe",
+    // --snip--
+}
 ```
 
+You can read more about all the fields in [is-reachable.md](../getting-started/is-reachable.md "mention").
+
 {% hint style="warning" %}
-If this step hangs for a long time, or returns a JSON result with `is_reachable="unknown"`, it generally means that port 25 is restricted. See [debugging-reacher.md](debugging-reacher.md "mention")on how to fix this.
+If this step hangs for a long time, or returns a JSON result with `is_reachable="unknown"`, see [debugging-reacher.md](debugging-reacher.md "mention")on how to fix this.
 {% endhint %}
 
-4. If you see a JSON output with an `is_reachable` field, then you're set, congratulations! :tada:
+If you go back to check the terminal with the Docker command, you should see corresponding logs:
+
+```log
+// --snip--
+2024-12-15T11:33:36.169891Z  INFO reacher: Starting verification email="amaury@reacher.email"
+2024-12-15T11:33:45.015130Z  INFO reacher: Done verification email="amaury@reacher.email" is_reachable=Safe
+```
+
+Congratulations! You just successfully verified an email from your computer. Now it's time to think about [scaling-for-production](scaling-for-production/ "mention").
 
 ## Troubleshooting
 

docs/self-hosting/licensing.md → docs/self-hosting/licensing/README.md

@@ -16,12 +16,12 @@ However, companies **cannot use** the open-source version if they plan to integr
 
 The Commercial License allows companies to integrate Reacher into their proprietary software or services without being bound by the open-source license terms (such as making their own code publicly available). By obtaining a Commercial License, businesses can use Reacher with full control over how the software is implemented and distributed within their products.
 
-Check Reacher's [pricing page](https://reacher.email/pricing) to buy a Commercial License.
+Check Reacher's [pricing page](https://reacher.email/pricing) to buy a Commercial License, or read the [full terms of the Commercial License](https://github.com/reacherhq/policies/blob/master/license/commercial.en.md).
 
 {% hint style="info" %}
 Both the open-source and Commercial License give you access to the same Reacher software.
 {% endhint %}
 
 ## Does Reacher offer a Free Trial?
 
-Yes, Reacher offers a **free trial** that allows you to use the self-hosted software for a limited time. During this period, you can test Reacher’s features for **internal testing** and **non-commercial purposes**. However, the trial is not intended for full-scale production use or commercial applications. To begin your trial, please contact [amaury@reacher.email](https://app.gitbook.com/u/F1LnsqPFtfUEGlcILLswbbp5cgk2 "mention"), and you can then follow the guide to [install.md](install.md "mention").
+Yes, Reacher offers a free trial for the Commercial License, see [commercial-license-trial.md](commercial-license-trial.md "mention").