Skip to main content

Frequently Asked Questions

Quick jump (categories):

Authentication & Security​

How do I authenticate with the Opportify API?​

Include your API Key in the Authorization header as a Bearer token.

Authorization: Bearer YOUR_API_KEY

How should I store my API Keys?​

Use environment variables or a secret manager. Never commit keys. Rotate if you suspect exposure.

What are ACL Rules?​

Optional allowlist of source IPs—only requests from those IPs are accepted (defense in depth).

Do you accept credentials via query parameters?​

No. Security policy: no query params for secrets or PII—use headers/body only.

How do I rotate keys safely?​

  1. Create a new key 2) Deploy it 3) Remove old key after validation. Overlap briefly to avoid downtime.

What does a 403 vs 401 style error mean here?​

403 errors (e.g., INVALID_TOKEN, INVALID_PLAN) indicate authenticated but not authorized or invalid subscription; missing/invalid token also maps to 403.

How do I handle rate limiting (429)?​

Respect Retry-After header, apply exponential backoff, and avoid parallel bursts from batch retries.

Email Validation​

What is the difference between Reachable and Deliverable?​

Reachable indicates the domain responds with valid MX (infrastructure present). Deliverable simulates SMTP to confirm mailbox acceptance.

How are disposable emails identified?​

Pattern + curated provider datasets; periodically refreshed. Treat as higher-risk for campaign quality.

What is a catch-all domain?​

Domain configured to accept any local-part. Deliverable may read as true while user existence remains uncertain; apply additional verification.

Can I auto-correct typos safely?​

Provide suggestion (e.g., gmail.con → gmail.com); only auto-apply if user confirms or implement conservative domain whitelist.

Why might isDeliverable be unknown?​

Server greylisting, transient network issues, or anti-abuse protections limiting validation depth.

IP Intelligence​

Do you support IPv6?​

Yes—ipType reflects IPv4 or IPv6; same enrichment schema where applicable.

How is connectionType determined?​

Heuristic fusion of network ranges, ASN patterns, reverse DNS, reputation datasets, and behavioral signals.

How often is blocklist data refreshed?​

Continuously aggregated; individual sources polled on cadence (near-real-time). Cache locally short-term to reduce calls.

What is Host Reverse?​

Reverse DNS (PTR) lookup; useful for trust heuristics (enterprise vs proxy vs cloud).

What does trustedProvider indicate?​

IP belongs to a recognized enterprise / security platform / ZTNA provider—often lower inherent abuse risk.

Risk Scoring​

What is the normalized score range?​

200–1000; mapped to static risk levels (lowest → highest) for consistent decision logic.

Can I customize thresholds?​

Not directly via API today—apply internal policy mapping if you need alternative cutoffs.

How frequently is the model retrained?​

Regularly with newly ingested signals (continuous improvement). Exact cadence may vary; treat level semantics as stable.

Does plan affect risk features?​

Free plan may exclude detailed risk reports; upgrade required for full scoring context.

Batch Processing​

Can I batch analyze emails or IPs?​

Yes—submit batch endpoints then poll status until COMPLETED; download results via pre-signed URLs.

What are the payload limits?​

Maximum request size 3MB. Split lists larger than that and stagger submissions.

What formats are supported?​

JSON array, CSV upload, or line-separated text (text/plain sets certain flags true by default per docs).

What happens if a batch partially fails?​

Errors appear in output (e.g., invalid entries). Continue processing valid rows—log and remediate failed subset separately.

How do I retry a failed batch?​

Resubmit only invalid items; avoid resubmitting successful rows to reduce cost & duplication.

How long are download URLs valid?​

Time-limited pre-signed URLs (exact TTL may vary). Download promptly and store internally if long-term retention required.

How do I monitor progress?​

Use progress field (0–100). Alert if a job stalls (e.g., no change for X minutes) to detect upstream issues.

Integration & SDK​

Where do I find SDK installation instructions?​

See Getting Started pages for each language (Node.js, Java, Python, PHP).

Should I use SDK or raw HTTP?​

Use SDKs for faster adoption, retry helpers, and typing; raw HTTP if you need ultra-minimal footprint or custom transport.

How should I implement retries?​

Retry idempotent GET/validation calls on 5xx or network errors with jittered exponential backoff; stop on 4xx except 429.

Can I cache results?​

Yes for relatively stable attributes (e.g., geo / ASN) short-term (e.g., hours). Avoid long cache for dynamic risk or blocklist states.

How do I correlate logs?​

Add an internal correlation ID per request; store Opportify endpoint + timestamp + risk result for audit.

Operations & MarTech​

How do I improve deliverability KPIs?​

Integrate real-time validation at acquisition + run nightly batch hygiene + suppress high-risk and disposable domains early.

Which fields enable segmentation?​

riskReport.level, emailType, connectionType, blocklisted.isBlockListed, geolocation (region/timezone), correction presence.

What metrics should I track weekly?​

Bounce rate, risk distribution shift, correction application rate, disposable signup percentage, batch failure rate.

How do I enforce quality gates?​

Reject records missing required identifiers; quarantine high-risk until secondary validation; log reasons for reprocessing.

Security & Compliance​

Do you store PII indefinitely?​

Only process what you send; follow least-privilege. Retrieve results, then enforce your internal retention policies.

How do I minimize data exposure?​

No secrets in query strings, use HTTPS only, rotate keys, restrict IPs with ACL Rules, and mask logs.

How do I report suspected abuse?​

Use the contact channel (support/contact-us form). Provide timestamps, IPs, and any correlation IDs—omit raw sensitive payloads.

How does geolocation accuracy affect compliance?​

Use confidence tiers: only enforce region-specific compliance (e.g., consent flows) at reliable levels (country+ region) to reduce false positives.

Roadmap​

Do you support webhooks?​

Not yet—planned for async completion notifications. For now poll status endpoints with backoff.

Will additional risk factors be exposed?​

Planned: expanded categorical explanations and factor weighting transparency while maintaining model integrity.

Can I request a feature?​

Submit via contact form or open a documentation issue referencing business case + expected field outputs.

Need something else covered? Open an issue or PR.