Examples

This page contains practical Python snippets for using urlDNA to analyze URLs, search scans, and check if emails contain phishing links.
You can interact with urlDNA either via direct requests calls to the REST API or using the official urldna Python package for a cleaner interface.

Submit a New Scan

You can submit a suspicious URL to urlDNA and wait for the result. This is useful for analyzing links found in emails or websites.

Using `requests`

import time
import requests

# Replace with your API key from URLDNA
API_KEY = "your_api_key_here"

# Example: URL extracted from a suspicious email
suspicious_url = "http://example-phishing.com/login"

# Step 1: Submit the URL for analysis
response = requests.post(
    "https://api.urldna.io/v1/scan",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"submitted_url": suspicious_url}
)

if response.status_code != 200:
    raise Exception(f"Scan request failed: {response.text}")

# Get Scan objct
scan = response.json()

# Step 2: Poll until the scan is complete
while scan.get("status") in ["PENDING", "RUNNING"]:
    time.sleep(5)  # Wait 5 seconds before polling again
    scan_id = scan.get("id")
    result = requests.get(
        f"https://api.urldna.io/v1/scan/{scan_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    if result.status_code != 200:
        raise Exception(f"Failed to fetch scan result: {result.text}")
    scan_result = result.json()
    scan = scan_result.get("scan")

# Step 3: Print the verdict
if scan_result and scan_result.get("malicious"):
    print("⚠️ Warning: This URL is flagged as phishing!")
else:
    print("✅ This URL appears safe.")

Using `urldna` package

from urldna import UrlDNA

# Replace with your API key from URLDNA
API_KEY = "your_api_key_here"

# Example: URL extracted from a suspicious email
suspicious_url = "http://example-phishing.com/login"

# Step 1: Initialize the client
client = UrlDNA(API_KEY)

# Step 2: Submit the URL for analysis
scan_result = client.create_scan(suspicious_url)

# Step 3: Print the verdict
if scan_result.malicious:
    print("⚠️ Warning: This URL is flagged as phishing!")
else:
    print("✅ This URL appears safe.")

Search Scans

Use the urlDNA Custom Query Language to search across scans. This is useful for finding related phishing pages, suspicious domains, or tracking specific keywords.

Using `requests`

import requests

# Replace with your API key from URLDNA
API_KEY = "your_api_key_here"

# Example query: find malicious scans containing "paypal" in the title
query = "title LIKE paypal AND malicious = true"

# Perform search
response = requests.post(
    "https://api.urldna.io/v1/search",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"query": query}
)

if response.status_code != 200:
    raise Exception(f"Search request failed: {response.text}")

search_results = response.json()

# Print results
for scan in search_results:
    print(f"Scan ID: {scan.get('id')}, URL: {scan.get('submitted_url')}")

Using `urldna` package

from urldna import UrlDNA

# Replace with your API key from URLDNA
API_KEY = "your_api_key_here"

# Initialize client
client = UrlDNA(API_KEY)

# Example query: find malicious scans containing "paypal" in the title
query = "title LIKE paypal AND malicious = true"

# Perform search
search_results = client.search(query)

# Print results
for scan in search_results:
    print(f"Scan ID: {scan.id}, URL: {scan.submitted_url}")

Check URL using Fast Check

Fast Check is the quickest way to verify a URL. If the response is CLEAN or MALICIOUS, you can trust the verdict immediately. If the status is UNRATED, you should submit the URL as a new scan for deeper analysis.

Using `requests`

import requests

# Replace with your API key from URLDNA
API_KEY = "your_api_key_here"

# Example: URL extracted from a suspicious email
suspicious_url = "http://example-phishing.com/login"

# Step 1: Fast Check the URL
response = requests.post(
    "https://api.urldna.io/v1/fast-check",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"url": suspicious_url}
)

if response.status_code != 200:
    raise Exception(f"Fast Check request failed: {response.text}")

result = response.json()

# Step 2: Print result or fall back to full scan
if result.get("status") != "UNRATED":
    print(f"URL is already known and labeled as {result.get('status')}")
else:
    print("URL not yet rated — submit it as a new scan for deeper analysis.")

Using `urldna` package

from urldna import UrlDNA

# Replace with your API key from URLDNA
API_KEY = "your_api_key_here"

# Example: URL extracted from a suspicious email
suspicious_url = "http://example-phishing.com/login"

# Step 1: Initialize the client
client = UrlDNA(API_KEY)

# Step 2: Fast Check the URL
result = client.fast_check(suspicious_url)

# Step 3: Print result or fall back to full scan
if result.status != "UNRATED":
    print(f"URL is already known and labeled as {result.status}")
else:
    print("URL not yet rated — submit it as a new scan for deeper analysis.")

Check Email Safety

You can scan all links inside an email body and determine if the email contains malicious URLs.

Using `urldna` package

import re
from urldna import UrlDNA

# Replace with your API key from URLDNA
API_KEY = "your_api_key_here"

# Initialize client
client = UrlDNA(API_KEY)

# Example email body with a phishing link
email_body = """
Hi urlDNA,

Please update your password immediately: http://example-phishing.com/login  

Thanks,
Security Team
"""

# Extract URLs from the email
urls = re.findall(r'(https?://\S+)', email_body)

malicious_scans = []
for url in urls:
    scan_result = client.create_scan(url)
    if scan_result and scan_result.malicious:
        malicious_scans.append(scan_result)

# Print final verdict
if malicious_scans:
    print(
        f"⚠️ This email contains {len(malicious_scans)} phishing URLs! "
        f"Check these Scan IDs for details: {[scan.id for scan in malicious_scans]}"
    )
else:
    print("✅ This email seems safe.")

API Documentation

Endpoints

Submit a New Scan

Using `requests`

Using `urldna` package

Search Scans

Using `requests`

Using `urldna` package

Check URL using Fast Check

Using `requests`

Using `urldna` package

Check Email Safety

Using `urldna` package

​Submit a New Scan

​Using requests

​Using urldna package

​Search Scans

​Using requests

​Using urldna package

​Check URL using Fast Check

​Using requests

​Using urldna package

​Check Email Safety

​Using urldna package

Submit a New Scan

Using `requests`

Using `urldna` package

Search Scans

Using `requests`

Using `urldna` package

Check URL using Fast Check

Using `requests`

Using `urldna` package

Check Email Safety

Using `urldna` package