Metadata-Version: 2.1
Name: mailValidator
Version: 0.2.0
Summary: A package to verify email addresses by checking DNS records and SMTP servers.
Author: Anu T
Author-email: mail2packagehandler@gmail.com
Maintainer: Anu T
Maintainer-email: mail2packagehandler@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: dnspython>=2.0.0
Requires-Dist: python-dotenv>=0.21.0
Requires-Dist: xlsxwriter>=1.3.0

# mailValidator

**Version:** 0.2.0

## Description

`mailValidator` is a Python package designed to verify email addresses by checking DNS records and SMTP servers. This package offers a reliable method for validating email addresses without sending actual emails. Currently, it is in the testing stage, and thus, it's not recommended for production or development environments.

## Features

- **DNS Verification:** Confirms the existence of the email domain by checking DNS records.
- **SMTP Verification:** Validates email addresses by connecting to the SMTP server without sending any email.
- **Logging:** Captures and logs the validation process and results for easy debugging and tracking.

## Installation

To install `mailValidator`, use pip:

```bash
pip install mailValidator

```

## Usage

### Command-Line Usage:

You can use mailValidator directly from the command line to validate email addresses.

```bash
mailValidator --emails emails.txt --output results.txt

```

#### You can also specify a timeout for the requests:

```bash
mailValidator --emails emails.txt --output results.txt --timeout 10

```

#### To validate a list of email addresses directly:

```bash
mailValidator --emails mail2Valid@gmail.com,test1@examples.com,mail2Valid@catchall.com --output results.txt

```

- **--emails:** Specifies the path to a .txt file containing email addresses.

    ```bash
        mail2Valid@gmail.com
        test1@examples.com
        test2@examples.com
        mail2Valid@catchall.com
        kadip70201@invalid.com
    ```
- **--output:** Specifies the path to save the results (.txt or .xlsx format).

    ```bash
        Success (200)
        ---------------
        mail2Valid@gmail.com: Valid email

        Domain is a catch-all (201)
        -----------------------------
        mail2Valid@catchall.com: Valid email but domain is a catch-all.

        Client Errors (400)
        ---------------------
        test1@examples.com: Invalid email: The mailbox is unavailable
        test2@examples.com: Invalid email: The mailbox is unavailable

        Not Found (404)
        -----------------
        kadip70201@invalid.com: MX record or domain details not found.

    ```

## Programmatic Usage

You can also use mailValidator programmatically within your Python code:

```bash

from mailValidator import verify_email, verify_emails_list

config = {
    "timeout": 5
}

email = "example@valid.com"
result = verify_email(email)
result_config = verify_email(email, config)


email_list = ["valid@companyemail.com", "test@nonvalid.com"]
results_list = verify_emails_list(email_list)
results_list_config = verify_emails_list(email_list, config)


print("output:")
print('result: ')
print(result)
print('result_config: ')
print(result_config)
print('results_list: ')
print(results_list)
print('results_list_config: ')
print(results_list_config)


-----------------------------------------------
output:
result: 
{'status': '200', 'message': 'Valid email'}
result_config: 
{'status': '200', 'message': 'Valid email'}
results_list: 
{'valid@companyemail.com': {'status': '200', 'message': 'Valid email'}, 'test@nonvalid.com': {"status": "400", "message": "Invalid email: The mailbox is unavailable"}}
results_list_config: 
{'valid@companyemail.com': {'status': '200', 'message': 'Valid email'}, 'test@nonvalid.com': {"status": "400", "message": "Invalid email: The mailbox is unavailable"}}

```

## License:

```bash
Custom License for "mailValidator"

Copyright (c) 2024 Anu T

**This software is currently in development and is provided for testing and evaluation purposes only. **

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to use the Software
within their code, subject to the following conditions:

1. The Software may not be copied or modified in any form or for any purpose.
2. The Software may not be distributed, sublicensed, or sold to others.

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Please note that this license is temporary and a more comprehensive license will be provided in the future.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

```

## Error Statuses:

When using mailValidator, you may encounter various HTTP status codes that indicate the result of the email verification process:

```bash
    200 - Success: The email address has been successfully verified.
    400 - Client Error: There was an issue with the request, often due to an invalid email format.
    403 - Forbidden: The server understood the request but refuses to authorize it, possibly due to a restriction on the SMTP server.
    404 - Not Found: The domain associated with the email address could not be found.
    500 - Server Error: An error occurred on the server side, which could indicate issues with the SMTP server or an unexpected failure.
    503 - Service Unavailable: The SMTP server is temporarily unable to handle the request, possibly due to overload or maintenance.

```


### `CHANGELOG.md`

```markdown
# Changelog

## [0.2.0] - 19-09-2024
### Added
- Customizable timeout setting for SMTP email verification.
- `--timeout` argument for specifying connection timeout in CLI.

## [0.1.1] - 01-09-2024
### Added
- Initial release of the `mailValidator` package.
- Added DNS and SMTP email verification functionality.
- Command-line interface for email validation.
- Logging for email validation processes.
- Output support for `.txt` and `.xlsx` formats.

## [0.1.0] - 31-08-2024
### Added
- Initial testing version of the package released.
