Technical Documentation: reacherhq/backend

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

⚙️ Reacher Backend

Backend Server for Reacher Email Verification API: https://reacher.email.

⚠️⚠️ IMPORTANT UPDATE ⚠️⚠️

This repo has been moved to the monorepo reacherhq/check-if-email-exists, in the backend subfolder.

Reacher Backend Copy Chapter

This repository holds the backend for Reacher. The backend is a HTTP server with the following components:

• check-if-email-exists, which performs the core email verification logic,
• warp web framework.

Get Started Copy Chapter

There are 2 ways you can run this backend.

1. Use Docker Copy Section

The Docker image is hosted on Docker Hub: https://hub.docker.com/r/reacherhq/backend.

To run it, run the following command:

docker run -p 8080:8080 reacherhq/backend

You can then send a POST request with the following body to http://localhost:8080/v0/check_email:

{
	"to_email": "[email protected]",
	"from_email": "[email protected]", // (optional) email to use in the `FROM` SMTP command, defaults to "[email protected]"
	"hello_name": "my-server.com",    // (optional) name to use in the `EHLO` SMTP command, defaults to "localhost"
	"proxy": {                        // (optional) SOCK5 proxy to run the verification through, default is empty
		"host": "my-proxy.io",
		"port": 1080
	},
	"smtp_port": 587                  // (optional) SMTP port to do the email verification, defaults to 25
}

2. Run locally Copy Section

If you prefer to run the server locally on your machine, just clone the repository and run:

cargo run

The server will then be listening on http://127.0.0.1:8080.

Configuration Copy Section

These are the environment variables used to configure the HTTP server:

REST API Documentation Copy Chapter

Read docs on https://help.reacher.email/rest-api-documentation.

The API basically only exposes one endpoint: POST /v0/check_email expecting the following body:

{
	"to_email": "[email protected]",
	"from_email": "[email protected]", // (optional) email to use in the `FROM` SMTP command, defaults to "[email protected]"
	"hello_name": "my-server.com",    // (optional) name to use in the `EHLO` SMTP command, defaults to "localhost"
	"proxy": {                        // (optional) SOCK5 proxy to run the verification through, default is empty
		"host": "my-proxy.io",
		"port": 1080
	},
	"smtp_port": 587                  // (optional) SMTP port to do the email verification, defaults to 25
}

Also check openapi.json for the complete OpenAPI specification.

License Copy Chapter

reacherhq/backend's source code is provided under a dual license model.

Commercial license Copy Section

If you want to use reacherhq/backend to develop commercial sites, tools, and applications, the Commercial License is the appropriate license. With this option, your source code is kept proprietary. Purchase an reacherhq/backend Commercial License at https://reacher.email/pricing.

Open source license Copy Section

If you are creating an open source application under a license compatible with the GNU Affero GPL license v3, you may use reacherhq/backend under the terms of the AGPL-3.0.

Read more about Reacher's license.

Sponsor my Open-Source Work Copy Chapter

If you like my open-source work at Reacher, consider sponsoring me! You'll also get 8000 free email verifications every month with your Reacher account, and a this contribution would mean A WHOLE LOT to me.

Overview (`migrations/README.md`) Copy Section

Database and Migrations

Migrations Copy Chapter

All migrations in this folder are embedded directly in the reacher_backend binary, so you don't need to run the migrations manually.

The migrations come from 2 sources:

• sqlxmq migrations
• Reacher's own migrations

`sqlxmq` migrations Copy Chapter

The following migration files have been copied from the sqlxmq repo as per the given instructions:

• 20210316025847_setup.{up,down}.sql
• 20210921115907_clear.{up,down}.sql
• 20211013151757_fix_mq_latest_message.{up,down}.sql
• 20220208120856_fix_concurrent_poll.{up,down}.sql
• 20220713122907_fix-clear_all-keep-nil-message.{up,down}.sql

Reacher migrations Copy Chapter

The following migrations are specific to Reacher:

• 20220117025847_email_data.down.sql: set up the bulk_jobs and email_results tables
• 20220810141100_result_created_at.down.sql: add a created_at column on email_result

Advanced Usage Copy Chapter

For more advanced usage (such as reverting to an old state), please use the sqlx CLI command.

See https://github.com/launchbadge/sqlx/blob/main/sqlx-cli/README.md

Overview (`tests/README.md`) Copy Section

Integration Tests

Files in this folder are Reacher backend's integration tests. They need the following to work:

• a working internet connection.

--- METRICS ---

• Files Extracted: 3
• Estimated Token Budget: ~1969 tokens
• Canonical Reference: https://codewiki.google/github.com/reacherhq/backend