# Introduction

NoParam is a powerful, real-time email validation API designed to help businesses improve their email deliverability, reduce bounce rates, and maintain clean contact lists. With simple API integration, NoParam provides accurate verification of email addresses before you send your first message.


# Authentication

## Authentication

To use the NoParam API, you need an **API key**.\
Pass the API key in the `Authorization` header:

#### 🔑 Example Request

```http
POST /verify HTTP/1.1
Host: noparam.com/api/v1
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```


# API Endpoints

Single Email Validation

Verify a single email address.

**Endpoint:** `POST /verify`

**Request Body:**

```json
{
  "email": "example@domain.com"
}
```

**Response:**

```json
{
  "email": "example@domain.com",
  "details": {
    "syntax": true,
    "domain_exists": true,
    "mx_records": true,
    "mailbox_exists": true,
    "disposable": false,
    "role_based": false,
    "suggestions": []
  },
  "score": 100,
  "status": "VALID",
  "duration_ms": 120
}
```

**Response Fields**

| Field                    | Description                                                        |
| ------------------------ | ------------------------------------------------------------------ |
| `email`                  | The email address that was verified                                |
| `details`                | Object containing detailed verification results                    |
| `details.syntax`         | Whether the email has valid syntax                                 |
| `details.domain_exists`  | Whether the domain exists                                          |
| `details.mx_records`     | Whether the domain has MX records                                  |
| `details.mailbox_exists` | Whether the mailbox likely exists                                  |
| `details.disposable`     | Whether the email is from a disposable domain                      |
| `details.role_based`     | Whether the email is a role-based address (e.g., admin@, support@) |
| `details.suggestions`    | Array of suggested corrections if a typo is detected               |
| `score`                  | Numerical score (0-100) indicating overall email quality           |
| `status`                 | Overall status of the email verification                           |
| `duration_ms`            | Time taken to perform the verification in milliseconds             |

**Status Codes**

| Status Code      | Description                                     |
| ---------------- | ----------------------------------------------- |
| `VALID`          | Email is valid and safe to use                  |
| `PROBABLY_VALID` | Email is likely valid but has some minor issues |
| `INVALID_SYNTAX` | Email syntax is invalid                         |
| `INVALID_DOMAIN` | Email domain does not exist                     |
| `NO_MX_RECORDS`  | Domain does not have MX records                 |
| `DISPOSABLE`     | Email is from a disposable/temporary domain     |
| `ROLE_BASED`     | Email is a role-based address                   |
| `INVALID`        | Email failed multiple checks                    |

#### Bulk Email Validation

Verify multiple email addresses in a single request.

**Endpoint:** `POST /verify/bulk`

**Request Body:**

```json
{
  "emails": [
    "example1@domain.com",
    "example2@domain.com",
    "example3@domain.com"
  ]
}
```

**Response:**

```json
{
  "results": [
    {
      "email": "example1@domain.com",
      "details": {
        "syntax": true,
        "domain_exists": true,
        "mx_records": true,
        "mailbox_exists": true,
        "disposable": false,
        "role_based": false,
        "suggestions": []
      },
      "score": 100,
      "status": "VALID",
      "duration_ms": 120
    },
    {
      "email": "example2@domain.com",
      "details": { ... },
      "score": 80,
      "status": "PROBABLY_VALID",
      "duration_ms": 145
    },
    {
      "email": "example3@domain.com",
      "details": { ... },
      "score": 30,
      "status": "INVALID_DOMAIN",
      "duration_ms": 105
    }
  ]
}
```

**Limitations**

* Maximum of 100 emails per bulk request
* Bulk requests are limited by your plan's bulk quota
* The actual number of emails processed may be limited to your remaining monthly quota


# API Playground

{% openapi src="/files/2rr5JzOoX3p2WejHZHwF" path="/verify" method="post" %}
[openapi.yaml](https://2050073976-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyEkzCsZD4bOJXRwFqTiH%2Fuploads%2Fcoh4nsnERzLKemTev1MX%2Fopenapi.yaml?alt=media\&token=bd26867e-666f-448a-8b62-c4d4b8a6ac10)
{% endopenapi %}

{% openapi src="/files/2rr5JzOoX3p2WejHZHwF" path="/verify/bulk" method="post" %}
[openapi.yaml](https://2050073976-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyEkzCsZD4bOJXRwFqTiH%2Fuploads%2Fcoh4nsnERzLKemTev1MX%2Fopenapi.yaml?alt=media\&token=bd26867e-666f-448a-8b62-c4d4b8a6ac10)
{% endopenapi %}


# SDK Examples

Node.js

```javascript
const axios = require('axios');

const NOPARAM_API_KEY = 'your_api_key';
const baseURL = 'https://noparam.com/api/v1';

// Single email verification
async function verifyEmail(email) {
  try {
    const response = await axios.post(
      `${baseURL}/verify`,
      { email },
      {
        headers: {
          'Authorization': `Bearer ${NOPARAM_API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );
    return response.data;
  } catch (error) {
    console.error('Verification failed:', error.response?.data || error.message);
    throw error;
  }
}

// Bulk email verification
async function verifyEmails(emails) {
  try {
    const response = await axios.post(
      `${baseURL}/verify/bulk`,
      { emails },
      {
        headers: {
          'Authorization': `Bearer ${NOPARAM_API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );
    return response.data;
  } catch (error) {
    console.error('Bulk verification failed:', error.response?.data || error.message);
    throw error;
  }
}

// Example usage
(async () => {
  // Verify a single email
  try {
    const result = await verifyEmail('example@domain.com');
    console.log('Verification result:', result);
  } catch (error) {
    // Handle error
  }
  
  // Verify multiple emails
  try {
    const results = await verifyEmails([
      'example1@domain.com',
      'example2@domain.com'
    ]);
    console.log('Bulk verification results:', results);
  } catch (error) {
    // Handle error
  }
})();
```

#### Python

```python
import requests

NOPARAM_API_KEY = 'your_api_key'
BASE_URL = 'https://noparam.com/api/v1'

headers = {
    'Authorization': f'Bearer {NOPARAM_API_KEY}',
    'Content-Type': 'application/json'
}

# Single email verification
def verify_email(email):
    try:
        response = requests.post(
            f'{BASE_URL}/verify',
            json={'email': email},
            headers=headers
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f'Verification failed: {e}')
        if hasattr(e, 'response') and e.response:
            print(e.response.json())
        raise

# Bulk email verification
def verify_emails(emails):
    try:
        response = requests.post(
            f'{BASE_URL}/verify/bulk',
            json={'emails': emails},
            headers=headers
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f'Bulk verification failed: {e}')
        if hasattr(e, 'response') and e.response:
            print(e.response.json())
        raise

# Example usage
if __name__ == '__main__':
    # Verify a single email
    try:
        result = verify_email('example@domain.com')
        print(f'Verification result: {result}')
    except Exception:
        # Handle error
        pass
    
    # Verify multiple emails
    try:
        results = verify_emails([
            'example1@domain.com',
            'example2@domain.com'
        ])
        print(f'Bulk verification results: {results}')
    except Exception:
        # Handle error
        pass
```


# Error Handling

NoParam uses conventional HTTP response codes to indicate the success or failure of an API request.

| Code | Description                                      |
| ---- | ------------------------------------------------ |
| 200  | Request succeeded                                |
| 400  | Bad request - Invalid request format             |
| 401  | Unauthorized - Invalid API key                   |
| 422  | Validation error - Request validation failed     |
| 429  | Too Many Requests - Rate limit or quota exceeded |
| 500  | Internal Server Error                            |

#### Error Response Format

```json
{
  "message": "Error description",
  "errors": [
    {
      "field": "field_name",
      "message": "Specific error message"
    }
  ]
}
```


# Mailchimp

NoParam integrates seamlessly with Mailchimp to help maintain clean email lists.

**Setting Up Mailchimp Integration**

1. Log in to your NoParam dashboard
2. Navigate to Integrations > Mailchimp
3. Click "Connect to Mailchimp"
4. Authorize NoParam to access your Mailchimp account
5. Select the lists you want to validate

**Features**

* **List Validation**: Validate entire Mailchimp lists with one click
* **Automatic Cleaning**: Set up scheduled validations to keep lists clean
* **Segmentation**: Create segments based on email quality scores
* **Bounce Prevention**: Flag risky emails before sending campaigns


# Troubleshooting

If you run into any issues, here are some common problems and solutions:

* **"Rate limit exceeded"**: Wait for a few seconds and try again. Consider upgrading your plan for more requests.
* **"Invalid email format"**: Make sure the email you're sending is in a valid format (e.g., `user@example.com`).
* **"Unauthorized"**: Ensure your API key is correct and included in the request header.


# Best Practices

**Email Validation Strategy**

1. **Real-time validation**: Validate emails at the point of collection (signup forms, lead generation)
2. **Periodic list cleaning**: Regularly validate your existing email lists
3. **Pre-campaign checks**: Validate emails before sending important campaigns
4. **Segmentation by quality**: Create segments based on email verification scores

**Email Verification Tips**

* Use both syntax and domain validation for signup forms
* Consider setting a minimum score threshold (e.g., 70) for accepting emails
* For high-value leads, accept emails with lower scores but flag them for manual review
* Exclude disposable email domains for subscription services


# Changelog

**v1.0.0 (Current)**

* Initial API release
* Single email verification endpoint
* Bulk verification endpoint
* Mailchimp integration

#### Coming Soon

* Additional CRM/ESP integrations
* Email deliverability testing
* API rate limiting customization
* Enhanced validation for catch-all domains