Load MailTester Ninja data in Python using dltHub

MailTester Ninja is an email verification service that checks addresses in real time against the recipient mail server. The REST API base URL is https://happy.mailtester.ninja and all requests require the API key query parameter key.

dlt is an open-source Python library that handles authentication, pagination, and schema evolution automatically. dlthub provides AI context files that enable code assistants to generate production-ready pipelines. Install with uv add "dlt[hub]" and start loading MailTester Ninja data in under 10 minutes.

---

What data can I load from MailTester Ninja?

MailTester Ninja has one endpoint. It verifies a single email address per request and returns one JSON object, so there are no lists to paginate or load incrementally:

---

How do I authenticate with the MailTester Ninja API?

Authentication is supplied as the required query parameter key on each GET request, for example, ?email=someone@example.com&key=YOUR_API_KEY. The documented no-signup option is key=free; the documentation does not specify an authentication header or a Bearer/token header format.

1. Get your credentials

MailTester Ninja does not use a conventional dashboard login for API credentials. For testing, call the API immediately with the literal key free; this provides up to 10 checks per day per IP, paced at one request every 30 seconds. For a no-card free token, open the MailTester Ninja free API-token page, complete the one-click human check, and copy the displayed token; it is valid for 7 days, renewable, and permits up to 50 checks per day at one request every 30 seconds. For production volume, open the MailTester Ninja pricing/subscription page, choose a paid plan, and complete checkout through Stripe. The API key is delivered after checkout (also described as the unlimited access key), and remains active while the subscription is in good standing. Save the key securely; the service says it replaces traditional login credentials. In API requests, pass the key as the key query parameter. Do not include the curly braces shown when copying an API key for the web form unless the provider specifically requires them there; the API documentation says to use the subscription key without {}.

2. Add them to .dlt/secrets.toml

Copy
[sources.mailtester_ninja_source]
api_key = "your_mailtester_ninja_api_key"

dlt reads this automatically at runtime — never hardcode tokens in your pipeline script. For production environments, see setting up credentials with dlt for environment variable and vault-based options.

---

How do I set up and run the pipeline?

Set up a virtual environment and install dlt:

Copy
uv init
uv add "dlt[hub]"

1. Install the dlt AI harness:

Copy
uv run dlthub ai init --agent <your-agent> # <agent>: claude | cursor | codex

This installs project rules, a secrets management skill, appropriate ignore files, and configures the dlt MCP server for your agent. Learn more →

2. Install the rest-api-pipeline toolkit:

Copy
uv run dlthub ai toolkit install rest-api-pipeline

This loads the skills and context about dlt the agent uses to build the pipeline iteratively, efficiently, and safely. The agent uses MCP tools to inspect credentials — it never needs to read your secrets.toml directly. Learn more →

3. Start LLM-assisted coding:

Use /find-source to load data from the MailTester Ninja API into DuckDB.

The rest-api-pipeline toolkit takes over from here — it reads relevant API documentation, presents you with options for which endpoints to load, and follows a structured workflow to scaffold, debug, and validate the pipeline step by step.

4. Run the pipeline:

Copy
uv run python mailtester_ninja_pipeline.py

If everything is configured correctly, you'll see output like this:

Copy
Pipeline mailtester_ninja_pipeline load step completed in 0.26 seconds
1 load package(s) were loaded to destination duckdb and into dataset mailtester_ninja_data
The duckdb destination used duckdb:/mailtester_ninja.duckdb location to store data
Load package 1749667187.541553 is LOADED and contains no failed jobs

Inspect your pipeline and data:

Copy
uv run dlthub show

This opens the Pipeline Dashboard where you can verify pipeline state, load metrics, schema (tables, columns, types), and query the loaded data directly.

---

Python pipeline example

This example verifies one address against the /ninja endpoint and loads the result into DuckDB. Each request checks one address, so to verify a list, run one request per address and respect your plan's rate limit:

Copy
import dlt
from dlt.sources.rest_api import RESTAPIConfig, rest_api_resources

@dlt.source
def mailtester_ninja_source(email: str, api_key=dlt.secrets.value):
    config: RESTAPIConfig = {
        "client": {
            "base_url": "https://happy.mailtester.ninja",
            "auth": {"type": "api_key", "name": "key", "api_key": api_key, "location": "query"},
            "paginator": "single_page",
        },
        "resources": [
            {
                "name": "email_verification",
                "endpoint": {"path": "ninja", "params": {"email": email}},
            },
        ],
    }
    yield from rest_api_resources(config)


def get_data() -> None:
    pipeline = dlt.pipeline(
        pipeline_name="mailtester_ninja_pipeline",
        destination="duckdb",
        dataset_name="mailtester_ninja_data",
    )
    load_info = pipeline.run(mailtester_ninja_source(email="someone@example.com"))
    print(load_info)

---

How do I query the loaded data?

Once the pipeline runs, dlt creates one table per resource. You can query with Python or SQL.

Python (pandas DataFrame):

Copy
import dlt

data = dlt.pipeline("mailtester_ninja_pipeline").dataset()
df = data.email_verification.df()
print(df.head())

SQL (DuckDB example):

Copy
SELECT * FROM mailtester_ninja_data.email_verification LIMIT 10;

In a marimo or Jupyter notebook:

Copy
import dlt

data = dlt.pipeline("mailtester_ninja_pipeline").dataset()
data.email_verification.df().head()

See how to explore your data in marimo Notebooks and how to query your data in Python with dataset.

---

What destinations can I load MailTester Ninja data to?

dlt supports loading into any of these destinations — only the destination parameter changes:

Change the destination in dlt.pipeline(destination="snowflake") and add credentials in .dlt/secrets.toml. See the full destinations list.

---

Next steps

Continue your data engineering journey with the other toolkits of the dltHub AI harness:

• data-exploration — Build custom notebooks, charts, and dashboards for deeper analysis with marimo notebooks.
• dlthub-platform — Deploy, schedule, and monitor your pipeline in production.

Copy
uv run dlthub ai toolkit install data-exploration
uv run dlthub ai toolkit install dlthub-platform

• How to deploy a pipeline
• How to explore your data in marimo Notebooks
• How to query your data in Python with dataset
• Join the dlt community on Slack