> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryrelaybase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python

> Official Python SDK for the Relaybase API

Official Python SDK for Relaybase.

<Card title="GitHub Repository" icon="github" href="https://github.com/Vusion-Labs/relaybase_python_sdk">
  Source, issues, and releases for the Relaybase Python SDK.
</Card>

## Requirements

* Python >= 3.8
* No external dependencies

## Installation

```bash theme={null}
pip install relaybase
```

## Authentication

Get your API key from the [Relaybase dashboard](/getting-started/create-api-key) and pass it to the constructor:

```python theme={null}
client = Relaybase("rb_key_your_api_key_here")
```

## Usage

```python theme={null}
from relaybase import Relaybase, RelaybaseAPIError

client = Relaybase("rb_key_your_api_key_here")

try:
    result = client.verify_single("test@example.com", mode="fast")

    print(result.status)      # valid, invalid, risky
    print(result.score)       # 0-100
    print(result.reason)      # human readable reason
    print(result.suggestion)  # suggested action
except RelaybaseAPIError as e:
    print(e.status_code)
    print(e.message)
```

## Verification modes

| Mode     | Description                             |
| -------- | --------------------------------------- |
| `fast`   | Quick syntax and domain check (default) |
| `medium` | Includes MX record validation           |
| `deep`   | Full SMTP verification                  |

See [Validation Results](/concepts/validation-results) for how these map to the API's `mode` field.

## Response fields

`verify_single()` returns a result object with:

| Field           | Type | Description                              |
| --------------- | ---- | ---------------------------------------- |
| `status`        | str  | `valid`, `invalid`, or `risky`           |
| `score`         | int  | Confidence score 0–100                   |
| `is_valid`      | bool | Whether the email passed validation      |
| `is_disposable` | bool | Whether the address is disposable        |
| `is_free`       | bool | Whether it uses a free provider          |
| `is_role_based` | bool | Whether it is a role address             |
| `mx_valid`      | bool | Whether the domain has valid MX records  |
| `syntax_valid`  | bool | Whether the email syntax is correct      |
| `catch_all`     | bool | Whether the domain accepts all addresses |
| `smtp_code`     | int  | SMTP response code                       |
| `reason`        | str  | Reason for the result                    |
| `suggestion`    | str  | Suggested action                         |

## Error handling

Errors from the API are raised as `RelaybaseAPIError`:

```python theme={null}
try:
    result = client.verify_single("test@example.com", mode="fast")
except RelaybaseAPIError as e:
    print(e.status_code)
    print(e.message)
```

## Roadmap

Bulk validation support for validating multiple emails in a single call is in progress and will be added in a future release.