feat: email verification library

docs/api/getting-started.md → docs/api/intro.md

@@ -2,4 +2,4 @@
 sidebar_position: 1
 ---
 
-# Getting Started
+# Introduction

docs/email-verification-library/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Email Verification Library",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "Node.js SMTP Email Verification Library"
+  }
+}

docs/email-verification-library/intro.md

@@ -0,0 +1,105 @@
+---
+sidebar_position: 1
+---
+
+# Introduction
+
+`ping-email` is a Node.js library that provides a simple and efficient way to verify email addresses. It performs syntax, domain, and SMTP checks to determine the validity of an email address. By integrating `ping-email` into your applications, you can ensure that users provide valid email addresses, reducing the risk of errors and improving communication reliability.
+
+## Install
+
+```bash
+npm install ping-email
+# or
+yarn add ping-email
+```
+
+## Setup
+
+```js
+import { PingEmail } from "ping-email";
+const pingEmail = new PingEmail({
+  port: 25, // Default SMTP port
+  fqdn: "mail.example.org", // Fully Qualified Domain Name of your SMTP server
+  sender: "name@example.org", // Email address to use as the sender in SMTP checks,
+  timeout: 10000, // Time in milliseconds to wait for a response from the SMTP server
+  attempts: 3, // Number of attempts to verify the email address
+});
+```
+
+## Usage
+
+### Verifying an Email Address
+
+To verify an email address using `ping-email`, call the ping method with the target email address:
+
+```js
+const { email, valid, message } = await pingEmail.ping("test@example.com");
+
+if (valid) {
+  console.log("Email is valid:", email);
+} else {
+  console.error("Verification failed:", message);
+}
+```
+
+### Ping Response
+
+The ping method returns an object with the following properties:
+
+- `email`: The email address being verified.
+- `valid`: A boolean indicating the overall validity of the email based on syntax, domain, and SMTP checks.
+- `success`: A boolean indicating if the verification process executed without encountering system-level errors (e.g., network issues).
+- `message`: A string providing detailed feedback about the verification outcome. This message can be one of the following, as defined in `PingResponseMessages`:
+  - `"Valid email"`: The email address is valid.
+  - `"Invalid email"`: The email address is invalid.
+  - `"Valid domain"`: The domain of the email address is valid.
+  - `"Invalid domain"`: The domain of the email address is invalid.
+  - `"Email is required"`: No email address was provided for verification.
+  - `"No MX records found"`: The domain does not have MX records, indicating it cannot receive emails.
+  - `"Invalid email syntax"`: The email address provided does not meet the syntactical standards for email addresses.
+  - `"SMTP connection error"`: There was an error connecting to the SMTP server for verification.
+  - `"Disposable email is not allowed"`: The email address belongs to a disposable email provider.
+  - `"Domain verification failed"`: The domain verification process failed.
+  - `"Unable to verify email"`: The email verification process failed for an unknown reason.
+  - `"Connection timeout"`: The connection to the SMTP server timed out.
+  - `"Exceeded attempts"`: The maximum number of attempts to verify the email address was exceeded.
+  - `"Valid email (ignored SMTP verification)"`: The email address is valid, but the SMTP verification process was skipped.
+
+These messages provide clear insights into the verification process, helping you understand the specific reason for an email's validation outcome.
+
+### Error Handling
+
+When integrating `ping-email` into your applications, pay special attention to the success and message properties in the ping method response. They are key to identifying and handling different scenarios, such as invalid email syntax, domain issues, or SMTP server connectivity problems. Logging these details can be helpful for debugging purposes or improving user feedback in your application interface.
+
+### Options
+
+You can customize `ping-email` by providing different options when you instantiate it. The available options are:
+
+- `port`: The port number to connect to the SMTP server `(default: 25)`.
+- `attempts`: The number of attempts to verify the email address `(default: 3)`.
+- `fqdn`: The Fully Qualified Domain Name of your SMTP server `(default: "mail.example.org")`.
+- `sender`: The email address used as the sender in SMTP checks `(default: "name@example.org")`.
+- `timeout`: The time in milliseconds to wait for a response from the SMTP server `(default: 10000)`.
+- `ignoreSMTPVerify`: A boolean indicating whether to skip the SMTP verification process `(default: false)`.
+- `debug`: A boolean indicating whether to enable debug mode, which logs detailed information about the verification process `(default: false)`.
+
+This allows you to tailor the library to your specific requirements, ensuring compatibility with your email verification workflow.
+
+### Example
+
+Here's a complete example demonstrating how to verify an email address:
+
+```js
+import { PingEmail } from "ping-email";
+
+const pingEmail = new PingEmail({
+  port: 587,
+  fqdn: "smtp.example.org",
+  sender: "verify@example.org",
+  timeout: 15000,
+  attempts: 5,
+});
+
+const { email, valid, success, message } = await pingEmail.ping("user@example.com");
+```

docs/email-verification-library/what-is-smtp.md

@@ -0,0 +1,58 @@
+---
+sidebar_position: 2
+---
+
+# What is SMTP?
+
+Simple Mail Transfer Protocol (SMTP) is the standard protocol for sending emails across the Internet. It defines the rules for how email messages are transmitted between mail servers, and how users' email clients submit outgoing emails to their outgoing mail server.
+
+### Why Validate Email Addresses?
+
+Validating email addresses is crucial for several reasons:
+
+- **Reduce Bounce Rates**: Ensuring that emails are sent to valid addresses prevents emails from being bounced back.
+- **Improve Delivery Rates**: By filtering out invalid addresses, email campaigns can achieve higher delivery rates.
+- **Enhance Security**: Verification helps prevent fraud and enhances the security of email communication by ensuring that emails are sent to intended recipients.
+- **Save Resources**: By avoiding sending emails to non-existent or disposable addresses, businesses can save on server resources and focus on genuine users.
+
+### Understanding Key Terms
+
+- **Port**: In the context of SMTP, a port is a numerical designation that specifies a specific gateway for network communication. Common SMTP ports include 25 (default SMTP), 587 (for encrypted SMTP), and 465 (SMTPS).
+
+- **FQDN (Fully Qualified Domain Name)**: This refers to the complete domain name of an Internet resource. In SMTP settings, it specifies the domain name of the SMTP server that is used to send emails. For example, `smtp.example.com`.
+
+- **Sender**: The email address that appears in the 'From' field of an email. In email verification, it's used to simulate the sending process without actually sending an email, helping to verify the validity of the recipient's address.
+
+Understanding these concepts is crucial for effectively utilizing `ping-email` and comprehending the mechanics of email verification and delivery.
+
+## Risk of IP Blocking
+
+When using `ping-email` for SMTP email verification, there is a risk of IP blocking. This risk arises because the method employed by the library to verify email addresses can be perceived as suspicious by email servers, especially when requests are frequent or in large volumes. Email servers may interpret these verification attempts as spam or malicious activity, leading to the blocking of your IP address.
+
+### Mitigating the Risk
+
+To mitigate this risk, it is crucial to use the library responsibly and understand the implications of SMTP email verification. If you are conducting bulk email verifications or are concerned about the potential for IP blocking, consider the following guidelines:
+
+- **Rate Limiting**: Limit the number of requests you make to the SMTP server within a given time frame.
+- **Use a Proxy**: Consider using a proxy server to distribute requests across multiple IP addresses, reducing the risk of being blocked.
+- **Use a Dedicated IP**: If you have a high volume of email verification requests, consider using a dedicated IP address to avoid being blocked.
+
+### `ignoreSMTPVerify` Option
+
+The `ignoreSMTPVerify` option in `ping-email` allows you to skip the SMTP verification process, which can help reduce the risk of IP blocking. However, it is important to note that by doing so, you may miss out on valuable insights into the validity of email addresses and the integrity of the recipient's domain.
+
+Here's an example of how to use the `ignoreSMTPVerify` option:
+
+```js
+const pingEmail = new PingEmail({
+  ignoreSMTPVerify: true,
+});
+```
+
+### Best Practices
+
+- **Gradual Processing**: Gradually process large lists of email addresses to avoid sudden spikes in traffic that could lead to your IP being flagged.
+- **Monitoring and Feedback**: Regularly monitor the feedback from the servers you are verifying against. If you notice an increase in failures or blocks, adjust your verification strategy accordingly.
+- **Compliance and Ethics**: Always use email verification tools ethically and in compliance with internet standards and regulations to maintain a good sending reputation.
+
+By following these guidelines and using `ping-email` judiciously, you can effectively verify email addresses while minimizing the risk of IP blocking and maintaining the integrity of your email verification processes.

docs/embed/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Embed",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Embeddable Form"
+  }
+}

docs/embed/intro.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 1
+---
+
+# Introduction

docusaurus.config.js

@@ -80,15 +80,15 @@ const config = {
             items: [
               {
                 label: "API",
-                to: "/docs/intro",
+                to: "/docs/api/intro",
               },
               {
                 label: "Embed",
-                to: "/docs/intro",
+                to: "/docs/embed/intro",
               },
               {
-                label: "Email Verification",
-                to: "/docs/intro",
+                label: "Email Verification Library",
+                to: "/docs/email-verification-library/intro",
               },
             ],
           },
@@ -109,6 +109,19 @@ const config = {
               },
             ],
           },
+          {
+            title: "Legal",
+            items: [
+              {
+                label: "Terms of Use",
+                href: "https://pingback.com/newsroom/termos-de-uso",
+              },
+              {
+                label: "Privacy Policy",
+                href: "https://pingback.com/newsroom/politica-de-privacidade-e-protecao-de-dados",
+              },
+            ],
+          },
         ],
         copyright: `Copyright © ${new Date().getFullYear()} Pingback. Built with 💜 for Developers.`,
       },

sidebars.js

@@ -14,20 +14,28 @@
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
-  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
+  allSidebar: [{ type: "autogenerated", dirName: "." }],
 
-  // But you can create a sidebar manually
-  /*
-  tutorialSidebar: [
-    'intro',
-    'hello',
+  apiSidebar: [
     {
-      type: 'category',
-      label: 'Tutorial',
-      items: ['tutorial-basics/create-a-document'],
+      type: "autogenerated",
+      dirName: "api",
+    },
+  ],
+
+  embedSidebar: [
+    {
+      type: "autogenerated",
+      dirName: "embed",
+    },
+  ],
+
+  emailVerificationLibrarySidebar: [
+    {
+      type: "autogenerated",
+      dirName: "email-verification-library",
     },
   ],
-   */
 };
 
 export default sidebars;

src/pages/index.js

@@ -61,7 +61,7 @@ export default function Home() {
 
           <p className={styles.subtitle}>Get started with the Pingback API and integrate with your product.</p>
 
-          <Link to='/docs/api/getting-started' className={clsx("button button--primary", styles.button)}>
+          <Link to='/docs/api/intro' className={clsx("button button--primary", styles.button)}>
             Get Started
           </Link>
         </section>

src/pages/index.module.css

@@ -41,6 +41,7 @@
   font-size: 1rem;
   margin-top: 1.5rem;
   line-height: 1.5rem;
+  opacity: 0.6;
 }
 
 .button {