cURL Examples and Shell Scripting Guide¶

Complete guide to using ReputeAPI from the command line with cURL and shell scripts.

Quick Start¶

Basic Request¶

curl -X GET "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: your-api-key-here"

With Pretty JSON Output¶

curl -X GET "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: your-api-key-here" \
  | jq '.'

Save API Key as Environment Variable¶

# Add to ~/.bashrc or ~/.zshrc
export REPUTE_API_KEY="your-api-key-here"
export REPUTE_API_URL="https://api.reputeapi.com"

# Use in requests
curl -X GET "$REPUTE_API_URL/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY"

All Endpoints¶

1. Check Endpoint (Complete Validation)¶

Basic check:

curl -X GET "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY"

With DKIM selectors:

curl -X GET "https://api.reputeapi.com/api/v1/check?domain=example.com&selectors=default,google" \
  -H "X-API-Key: $REPUTE_API_KEY"

Verbose output:

curl -X GET "https://api.reputeapi.com/api/v1/check?domain=example.com&verbose=true" \
  -H "X-API-Key: $REPUTE_API_KEY"

Force refresh (bypass cache):

curl -X GET "https://api.reputeapi.com/api/v1/check?domain=example.com&refresh=true" \
  -H "X-API-Key: $REPUTE_API_KEY"

2. Score Endpoint (Quick Check)¶

curl -X GET "https://api.reputeapi.com/api/v1/score?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY"

Extract just the score:

curl -s -X GET "https://api.reputeapi.com/api/v1/score?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY" \
  | jq -r '.score'

3. Recommendations Endpoint¶

curl -X POST "https://api.reputeapi.com/api/v1/recommendations" \
  -H "X-API-Key: $REPUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

Filter by severity:

curl -X POST "https://api.reputeapi.com/api/v1/recommendations" \
  -H "X-API-Key: $REPUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "severity": "critical"}'

4. History Endpoint¶

Last 30 days:

curl -X GET "https://api.reputeapi.com/api/v1/history?domain=example.com&days=30" \
  -H "X-API-Key: $REPUTE_API_KEY"

Date range:

curl -X GET "https://api.reputeapi.com/api/v1/history?domain=example.com&start_date=2025-01-01&end_date=2025-01-31" \
  -H "X-API-Key: $REPUTE_API_KEY"

5. Usage Endpoint¶

curl -X GET "https://api.reputeapi.com/api/v1/usage" \
  -H "X-API-Key: $REPUTE_API_KEY"

6. Bulk Validate (Legacy)¶

curl -X POST "https://api.reputeapi.com/v1/bulk-validate" \
  -H "X-API-Key: $REPUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains": ["example.com", "test.com", "demo.com"]}'

Error Handling¶

Check HTTP Status Code¶

curl -X GET "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY" \
  -w "\nHTTP Status: %{http_code}\n"

Verbose Output for Debugging¶

curl -v -X GET "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY"

Silent Mode (No Progress Bar)¶

curl -s -X GET "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY"

Handle Errors in Scripts¶

#!/bin/bash

DOMAIN="example.com"
RESPONSE=$(curl -s -w "\n%{http_code}" \
  "https://api.reputeapi.com/api/v1/check?domain=$DOMAIN" \
  -H "X-API-Key: $REPUTE_API_KEY")

HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
BODY=$(echo "$RESPONSE" | sed '$d')

if [ "$HTTP_CODE" -eq 200 ]; then
  echo "Success!"
  echo "$BODY" | jq '.'
elif [ "$HTTP_CODE" -eq 401 ]; then
  echo "Error: Invalid API key"
  exit 1
elif [ "$HTTP_CODE" -eq 429 ]; then
  echo "Error: Rate limit exceeded"
  exit 1
else
  echo "Error: HTTP $HTTP_CODE"
  echo "$BODY"
  exit 1
fi

JSON Processing with jq¶

Extract Specific Fields¶

Get score:

curl -s "https://api.reputeapi.com/api/v1/score?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY" \
  | jq -r '.score'

Get score and grade:

curl -s "https://api.reputeapi.com/api/v1/score?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY" \
  | jq '{score: .score, grade: .grade}'

List All Issues¶

curl -s "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY" \
  | jq '.issues[] | {severity: .severity, message: .message}'

Filter Critical Issues Only¶

curl -s "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY" \
  | jq '.issues[] | select(.severity == "critical")'

Count Issues by Severity¶

curl -s "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY" \
  | jq '.score_breakdown.issues_by_severity'

Extract DNS Snippets¶

curl -s "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY" \
  | jq '.issues[] | select(.dns_snippet) | .dns_snippet'

Format as Table¶

curl -s "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY" \
  | jq -r '.issues[] | [.severity, .category, .message] | @tsv' \
  | column -t -s $'\t'

Shell Scripts¶

1. Basic Domain Checker¶

#!/bin/bash
# check-domain.sh - Check domain mailflow security

set -e

DOMAIN="${1:-}"
API_KEY="${REPUTE_API_KEY:-}"

if [ -z "$DOMAIN" ]; then
  echo "Usage: $0 <domain>"
  exit 1
fi

if [ -z "$API_KEY" ]; then
  echo "Error: REPUTE_API_KEY environment variable not set"
  exit 1
fi

echo "Checking domain: $DOMAIN"
echo "========================"

RESULT=$(curl -s "https://api.reputeapi.com/api/v1/check?domain=$DOMAIN" \
  -H "X-API-Key: $API_KEY")

SCORE=$(echo "$RESULT" | jq -r '.score')
GRADE=$(echo "$RESULT" | jq -r '.grade')

echo "Score: $SCORE/100"
echo "Grade: $GRADE"
echo ""

# Show issues
CRITICAL_COUNT=$(echo "$RESULT" | jq '.score_breakdown.issues_by_severity.critical')
HIGH_COUNT=$(echo "$RESULT" | jq '.score_breakdown.issues_by_severity.high')
MEDIUM_COUNT=$(echo "$RESULT" | jq '.score_breakdown.issues_by_severity.medium')
LOW_COUNT=$(echo "$RESULT" | jq '.score_breakdown.issues_by_severity.low')

echo "Issues Found:"
echo "  Critical: $CRITICAL_COUNT"
echo "  High:     $HIGH_COUNT"
echo "  Medium:   $MEDIUM_COUNT"
echo "  Low:      $LOW_COUNT"
echo ""

# Show top 5 issues
echo "Top Issues:"
echo "$RESULT" | jq -r '.issues[:5][] | "  [\(.severity | ascii_upcase)] \(.message)"'

Usage:

chmod +x check-domain.sh
./check-domain.sh example.com

2. Batch Domain Checker¶

#!/bin/bash
# batch-check.sh - Check multiple domains

set -e

INPUT_FILE="${1:-domains.txt}"
OUTPUT_FILE="results.csv"

if [ ! -f "$INPUT_FILE" ]; then
  echo "Error: File $INPUT_FILE not found"
  exit 1
fi

# Create CSV header
echo "Domain,Score,Grade,Critical,High,Medium,Low,Status" > "$OUTPUT_FILE"

echo "Checking domains from $INPUT_FILE..."

while IFS= read -r DOMAIN; do
  # Skip empty lines and comments
  [[ -z "$DOMAIN" || "$DOMAIN" =~ ^# ]] && continue

  echo -n "Checking $DOMAIN... "

  RESPONSE=$(curl -s -w "\n%{http_code}" \
    "https://api.reputeapi.com/api/v1/score?domain=$DOMAIN" \
    -H "X-API-Key: $REPUTE_API_KEY")

  HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
  BODY=$(echo "$RESPONSE" | sed '$d')

  if [ "$HTTP_CODE" -eq 200 ]; then
    SCORE=$(echo "$BODY" | jq -r '.score')
    GRADE=$(echo "$BODY" | jq -r '.grade')

    # Count issues
    CRITICAL=$(echo "$BODY" | jq '[.top_issues[]? | select(.severity == "critical")] | length')
    HIGH=$(echo "$BODY" | jq '[.top_issues[]? | select(.severity == "high")] | length')
    MEDIUM=$(echo "$BODY" | jq '[.top_issues[]? | select(.severity == "medium")] | length')
    LOW=$(echo "$BODY" | jq '[.top_issues[]? | select(.severity == "low")] | length')

    echo "$DOMAIN,$SCORE,$GRADE,$CRITICAL,$HIGH,$MEDIUM,$LOW,success" >> "$OUTPUT_FILE"
    echo "Score: $SCORE/100"
  else
    echo "$DOMAIN,0,Error,0,0,0,0,http_$HTTP_CODE" >> "$OUTPUT_FILE"
    echo "Error (HTTP $HTTP_CODE)"
  fi

  # Rate limiting: wait between requests
  sleep 0.5

done < "$INPUT_FILE"

echo ""
echo "Results saved to $OUTPUT_FILE"

# Summary
TOTAL=$(tail -n +2 "$OUTPUT_FILE" | wc -l)
PASSING=$(tail -n +2 "$OUTPUT_FILE" | awk -F',' '$2 >= 80' | wc -l)

echo "Summary: $PASSING/$TOTAL domains passing (80+)"

domains.txt:

example.com
test.com
demo.com
# Add more domains here

Usage:

chmod +x batch-check.sh
./batch-check.sh domains.txt

3. Monitoring Script with Alerts¶

#!/bin/bash
# monitor-domain.sh - Monitor domain and send alerts

set -e

DOMAIN="${1:-example.com}"
THRESHOLD="${2:-70}"
ALERT_EMAIL="${ALERT_EMAIL:-admin@example.com}"

echo "[$(date)] Checking $DOMAIN (threshold: $THRESHOLD)"

RESULT=$(curl -s "https://api.reputeapi.com/api/v1/score?domain=$DOMAIN" \
  -H "X-API-Key: $REPUTE_API_KEY")

SCORE=$(echo "$RESULT" | jq -r '.score')
GRADE=$(echo "$RESULT" | jq -r '.grade')

echo "Score: $SCORE/100 ($GRADE)"

# Check if score is below threshold
if [ "$SCORE" -lt "$THRESHOLD" ]; then
  echo "ALERT: Score $SCORE is below threshold $THRESHOLD!"

  # Send email alert (requires mailx or sendmail)
  SUBJECT="ReputeAPI Alert: $DOMAIN score below threshold"
  MESSAGE="Domain: $DOMAIN
Score: $SCORE/100
Grade: $GRADE
Threshold: $THRESHOLD
Time: $(date)

Top Issues:
$(echo "$RESULT" | jq -r '.top_issues[]? | "  [\(.severity)] \(.message)"')
"

  echo "$MESSAGE" | mail -s "$SUBJECT" "$ALERT_EMAIL"
  echo "Alert email sent to $ALERT_EMAIL"

  exit 1
fi

echo "Status: OK"
exit 0

Schedule with cron:

# Check every hour
0 * * * * /path/to/monitor-domain.sh example.com 75 >> /var/log/repute-monitor.log 2>&1

4. Score History Tracker¶

#!/bin/bash
# track-history.sh - Track score changes over time

set -e

DOMAIN="${1:-example.com}"
HISTORY_FILE="history_${DOMAIN}.csv"

# Create file if it doesn't exist
if [ ! -f "$HISTORY_FILE" ]; then
  echo "Timestamp,Domain,Score,Grade" > "$HISTORY_FILE"
fi

echo "Fetching score for $DOMAIN..."

RESULT=$(curl -s "https://api.reputeapi.com/api/v1/score?domain=$DOMAIN" \
  -H "X-API-Key: $REPUTE_API_KEY")

SCORE=$(echo "$RESULT" | jq -r '.score')
GRADE=$(echo "$RESULT" | jq -r '.grade')
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

# Append to history
echo "$TIMESTAMP,$DOMAIN,$SCORE,$GRADE" >> "$HISTORY_FILE"

echo "Score: $SCORE/100 ($GRADE)"
echo "Saved to $HISTORY_FILE"

# Show trend (last 10 entries)
echo ""
echo "Recent history:"
tail -n 10 "$HISTORY_FILE" | column -t -s ','

5. Parallel Domain Checker¶

#!/bin/bash
# parallel-check.sh - Check multiple domains in parallel

set -e

INPUT_FILE="${1:-domains.txt}"
MAX_PARALLEL="${2:-5}"

if [ ! -f "$INPUT_FILE" ]; then
  echo "Error: File $INPUT_FILE not found"
  exit 1
fi

check_domain() {
  local DOMAIN=$1
  local RESULT=$(curl -s "https://api.reputeapi.com/api/v1/score?domain=$DOMAIN" \
    -H "X-API-Key: $REPUTE_API_KEY")

  local SCORE=$(echo "$RESULT" | jq -r '.score')
  local GRADE=$(echo "$RESULT" | jq -r '.grade')

  echo "$DOMAIN: $SCORE/100 ($GRADE)"
}

export -f check_domain
export REPUTE_API_KEY

echo "Checking domains (max $MAX_PARALLEL parallel)..."

# Use GNU parallel if available
if command -v parallel &> /dev/null; then
  cat "$INPUT_FILE" | parallel -j "$MAX_PARALLEL" check_domain
else
  # Fallback: sequential processing
  while IFS= read -r DOMAIN; do
    [[ -z "$DOMAIN" || "$DOMAIN" =~ ^# ]] && continue
    check_domain "$DOMAIN"
  done < "$INPUT_FILE"
fi

With GNU parallel:

sudo apt-get install parallel  # Debian/Ubuntu
brew install parallel          # macOS

./parallel-check.sh domains.txt 10

6. CI/CD Integration Script¶

#!/bin/bash
# ci-email-security-check.sh - Validate email security in CI/CD

set -e

DOMAIN="${CI_DOMAIN:-example.com}"
MIN_SCORE="${MIN_SCORE:-80}"

echo "Validating email security for $DOMAIN"
echo "Required minimum score: $MIN_SCORE"

RESULT=$(curl -s "https://api.reputeapi.com/api/v1/score?domain=$DOMAIN" \
  -H "X-API-Key: $REPUTE_API_KEY")

SCORE=$(echo "$RESULT" | jq -r '.score')
GRADE=$(echo "$RESULT" | jq -r '.grade')

echo "Current score: $SCORE/100 ($GRADE)"

# Check for critical issues
CRITICAL_ISSUES=$(echo "$RESULT" | jq '[.top_issues[]? | select(.severity == "critical")] | length')

if [ "$CRITICAL_ISSUES" -gt 0 ]; then
  echo "FAILED: $CRITICAL_ISSUES critical issues found"
  echo "$RESULT" | jq -r '.top_issues[]? | select(.severity == "critical") | "  - \(.message)"'
  exit 1
fi

# Check minimum score
if [ "$SCORE" -lt "$MIN_SCORE" ]; then
  echo "FAILED: Score $SCORE is below required minimum $MIN_SCORE"
  exit 1
fi

echo "PASSED: Email security validation successful"
exit 0

GitHub Actions:

name: Email Security Check
on: [push]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Check Email Security
        env:
          REPUTE_API_KEY: ${{ secrets.REPUTE_API_KEY }}
          CI_DOMAIN: example.com
          MIN_SCORE: 80
        run: |
          curl -o check.sh https://raw.githubusercontent.com/.../ci-email-security-check.sh
          chmod +x check.sh
          ./check.sh

7. DNS Snippet Extractor¶

#!/bin/bash
# extract-dns-snippets.sh - Extract DNS configuration snippets

set -e

DOMAIN="${1:-example.com}"
OUTPUT_DIR="dns_fixes_$DOMAIN"

mkdir -p "$OUTPUT_DIR"

echo "Fetching recommendations for $DOMAIN..."

RESULT=$(curl -s "https://api.reputeapi.com/api/v1/check?domain=$DOMAIN" \
  -H "X-API-Key: $REPUTE_API_KEY")

# Extract issues with DNS snippets
ISSUES_WITH_DNS=$(echo "$RESULT" | jq -c '.issues[] | select(.dns_snippet)')

if [ -z "$ISSUES_WITH_DNS" ]; then
  echo "No DNS fixes needed!"
  exit 0
fi

echo "Extracting DNS fixes..."

# Process each issue
echo "$ISSUES_WITH_DNS" | while IFS= read -r ISSUE; do
  CODE=$(echo "$ISSUE" | jq -r '.code')
  HOSTNAME=$(echo "$ISSUE" | jq -r '.dns_snippet.hostname')
  RECORD_TYPE=$(echo "$ISSUE" | jq -r '.dns_snippet.record_type')
  VALUE=$(echo "$ISSUE" | jq -r '.dns_snippet.value')

  # Create fix file
  FIX_FILE="$OUTPUT_DIR/${CODE}.txt"

  cat > "$FIX_FILE" <<EOF
Issue: $CODE
Severity: $(echo "$ISSUE" | jq -r '.severity')
Message: $(echo "$ISSUE" | jq -r '.message')

DNS Fix:
Hostname: $HOSTNAME
Type: $RECORD_TYPE
Value: $VALUE

BIND Format:
$HOSTNAME $RECORD_TYPE "$VALUE"

Cloudflare/Generic:
Name: $HOSTNAME
Type: $RECORD_TYPE
Content: $VALUE
EOF

  echo "  Created: $FIX_FILE"
done

echo ""
echo "DNS fixes saved to $OUTPUT_DIR/"
ls -1 "$OUTPUT_DIR/"

Advanced Usage¶

Request Timeout¶

curl --max-time 10 \
  "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY"

Retry on Failure¶

curl --retry 3 --retry-delay 2 \
  "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY"

Custom User Agent¶

curl -A "MyApp/1.0 (contact@example.com)" \
  "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY"

Save Response to File¶

curl -o result.json \
  "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY"

Follow Redirects¶

curl -L "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY"

Show Only Headers¶

curl -I "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY"

Include Headers in Output¶

curl -i "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY"

One-Liners¶

Quick Score Check¶

curl -s "https://api.reputeapi.com/api/v1/score?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY" | jq -r '"\(.domain): \(.score)/100 (\(.grade))"'

Check Multiple Domains¶

for domain in example.com test.com demo.com; do
  curl -s "https://api.reputeapi.com/api/v1/score?domain=$domain" \
    -H "X-API-Key: $REPUTE_API_KEY" | jq -r '"\(.domain): \(.score)/100"'
  sleep 0.5
done

Count Critical Issues¶

curl -s "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY" \
  | jq '.score_breakdown.issues_by_severity.critical'

Get DMARC Policy¶

curl -s "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY" | jq -r '.dmarc.policy'

Check SPF Record¶

curl -s "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY" | jq -r '.spf.record'

List DKIM Selectors¶

curl -s "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY" | jq -r '.dkim.discovered_selectors[]'

Export to CSV¶

echo "Domain,Score,Grade" > results.csv
for domain in example.com test.com; do
  curl -s "https://api.reputeapi.com/api/v1/score?domain=$domain" \
    -H "X-API-Key: $REPUTE_API_KEY" \
    | jq -r '"\(.domain),\(.score),\(.grade)"' >> results.csv
  sleep 0.5
done

Troubleshooting¶

Debug API Calls¶

# Enable verbose output
curl -v "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY"

# Show request/response timing
curl -w "\nTime: %{time_total}s\n" \
  "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY"

Test API Key¶

# Test authentication
curl -s -o /dev/null -w "HTTP %{http_code}\n" \
  "https://api.reputeapi.com/api/v1/usage" \
  -H "X-API-Key: $REPUTE_API_KEY"

Check Rate Limits¶

# View rate limit headers
curl -I "https://api.reputeapi.com/api/v1/score?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY" \
  | grep -i "x-ratelimit"

Tips and Best Practices¶

1. Use Environment Variables¶

Never hardcode API keys in scripts:

# Good
-H "X-API-Key: $REPUTE_API_KEY"

# Bad
-H "X-API-Key: sk_live_abc123..."

2. Add Rate Limiting¶

# Wait between requests
sleep 0.5

3. Handle Errors Gracefully¶

# Check HTTP status codes
if [ "$HTTP_CODE" -ne 200 ]; then
  echo "Error: HTTP $HTTP_CODE"
  exit 1
fi

4. Use Silent Mode for Scripts¶

# Suppress progress bar
curl -s "https://api.reputeapi.com/..."

5. Save Results for Analysis¶

# Save to timestamped file
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
curl -s "https://api.reputeapi.com/api/v1/check?domain=example.com" \
  -H "X-API-Key: $REPUTE_API_KEY" \
  > "result_${TIMESTAMP}.json"

Next Steps¶

Python Guide - Python integration
JavaScript Guide - JavaScript/Node.js integration
Integration Patterns - Architecture patterns
Best Practices - Optimization tips
API Reference - Complete API documentation

Additional Resources¶

Support¶

Need help with cURL or shell scripting?