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 request header:

x-opportify-token: YOUR_API_KEY

What is the best way to store API keys?

  • Use secure environment variables or a dedicated secret manager.
  • Never commit keys to source code.
  • Rotate keys if there is any risk of exposure.
  • Use IP Access Control (ACL Rules) to restrict access to trusted IP addresses.

What are ACL Rules?
ACL Rules are optional allowlists of IP addresses. Only requests from the listed IPs will be accepted, adding another layer of protection.

Can credentials be passed in query parameters?
No. For security reasons, secrets or personal information should never be included in query parameters. Always send them in headers or the request body.

How do I rotate API keys safely?

  1. Generate a new key.
  2. Deploy it to your applications.
  3. After confirming it works, remove the old key.
    It is recommended to overlap keys briefly to avoid downtime.

What does a 403 vs. 401 error mean?

  • 403: Connection established, but the request is not authorized (for example, invalid plan or token).
  • 401: Not commonly used here. Most authentication issues will return 403.

How should I handle rate limiting (429)?

  • Respect the Retry-After header.
  • Use exponential backoff for retries.
  • Avoid sending large retry bursts.
    Paid plans include higher rate limits, which reduce the likelihood of encountering this error.

Email Validation​

What is the difference between Reachable and Deliverable?

  • Reachable: The domain has valid MX records and can receive mail.
  • Deliverable: The mailbox itself accepts mail, confirmed through an SMTP simulation.

How are disposable emails identified?
Through a combination of pattern checks and a regularly updated database of known disposable email providers.

What is a catch-all domain?
A domain configured to accept all emails, even if the mailbox does not exist. In these cases, a “deliverable” result does not always confirm that the user address is valid.

Can typos be corrected automatically?
The system provides suggestions (e.g., gmail.con → gmail.com).

  • Best practice is to show suggestions for user confirmation.
  • Auto-correct only if you use a controlled allowlist.

Why might isDeliverable return unknown?
Common reasons include greylisting, temporary network issues, or anti-spam protections that block deeper checks.

IP Intelligence​

Do you support IPv6?
Yes. The ipType field will specify IPv4 or IPv6, with the same schema applied.

How is connection type determined?
By analyzing network ranges, ASN patterns, reverse DNS data, reputation sources, and behavior signals.

How often is blocklist data updated?
Continuously, with frequent polling of sources. Caching locally for short periods is recommended to reduce repeated calls.

What is Host Reverse?
A reverse DNS (PTR) lookup. It helps distinguish between enterprise, proxy, or cloud infrastructure.

What does trustedProvider indicate?
That the IP address belongs to a recognized and trusted provider, such as an enterprise security or ZTNA provider. These are generally lower risk.

Risk Scoring​

What is the normalized score range?
200–1000. Higher scores indicate higher risk. Scores are also mapped to descriptive levels (lowest to highest).

Can thresholds be customized?
Not directly via the API. You can apply your own internal mappings if needed.

How frequently is the model retrained?
Continuously with new data. The underlying scores are updated, while the descriptive levels remain stable for consistency.

Do all plans include risk scoring?
Free plans provide limited details. Full reports are available with paid plans.

Batch Processing​

Can emails or IPs be analyzed in bulk?
Yes. Submit them via batch endpoints. The job runs asynchronously, and results can be downloaded through pre-signed URLs.

What are the payload limits?
3 MB per request. Larger lists should be split and submitted in smaller batches.

Which formats are supported?

  • JSON arrays
  • CSV files
  • Line-separated text

What happens if part of a batch fails?
The batch continues processing. Errors are flagged in the output so you can reprocess only the failed items.

How should failed batches be retried?
Resubmit only the invalid entries. Avoid resending successful rows.

How long are download URLs valid?
They are time-limited. Retrieve results promptly and store them internally if long-term retention is required.

How can I monitor batch progress?
Use the progress field (0–100). If the job stalls without updates, it may require attention.

Integration & SDK​

Where can SDK instructions be found?
In the “Getting Started” guides for Node.js, Java, Python, PHP, and other supported languages.

Should I use an SDK or raw HTTP?

  • SDKs are recommended for faster setup, built-in retry handling, and type safety.
  • Raw HTTP is useful when a minimal footprint or custom transport is required.

How should retries be implemented?

  • Retry idempotent operations (GET/validation) on 5xx or network errors.
  • Do not retry 4xx responses, except for 429 (rate limit).
  • Use exponential backoff with jitter.

Can results be cached?
Yes, for relatively stable data such as geolocation or ASN. Avoid long caching for dynamic data such as blocklist or risk states.

How should logs be correlated?
Include an internal correlation ID with each request, along with endpoint, timestamp, and result. This improves traceability and auditing.

Operations & MarTech​

How can deliverability metrics be improved?

  • Validate emails in real time during acquisition.
  • Run nightly batch hygiene jobs.
  • Suppress disposable and high-risk domains early.

Which fields are useful for segmentation?
Risk level, email type, connection type, blocklist status, geolocation, and presence of corrections.

What metrics should be monitored weekly?

  • Bounce rates
  • Distribution of risk levels
  • Typo correction rates
  • Percentage of disposable signups
  • Batch error rates

How can quality gates be enforced?

  • Reject incomplete records.
  • Quarantine high-risk data for secondary validation.
  • Log reasons for reprocessing.

Security & Compliance​

Do you store personal data indefinitely?
No. Data is processed only as submitted. Retention policies are the responsibility of the customer.

How can data exposure be minimized?

  • Do not send secrets in query strings.
  • Always use HTTPS.
  • Rotate API keys.
  • Use ACL Rules for IP restriction.
  • Mask sensitive information in logs.

How should suspected abuse be reported?
Use the Contact Us form. Provide timestamps, IPs, and correlation IDs (but avoid raw sensitive data).

How does geolocation accuracy affect compliance?
Only apply region-specific rules (such as consent enforcement) when accuracy is high enough to reduce false positives.

Roadmap​

Do you support webhooks?
Not currently. Polling endpoints is required for now, but webhook support is on the roadmap.

Will additional risk factors be exposed?
Yes. Future updates will expand explanations and factor weighting transparency while preserving model integrity.

Can I request a feature?
Yes. Submit requests through the contact form or by opening a documentation issue, including the business case and expected outputs.

Still have questions? Contact us and our team will be glad to help.