> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verisoul.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Integration
> How to integrate the Email Intelligence API: configure webhooks, submit emails, and process results
## Prerequisites
Before you begin, make sure you have:
* A **Verisoul API key** (available from the [Dashboard](https://dashboard.verisoul.ai))
***
## Step 1: Configure Your Webhook Endpoint (Optional)
Webhook configuration is **optional**. All email intelligence results are available in the [Dashboard](https://dashboard.verisoul.ai) regardless of whether a webhook is configured. Set up a webhook only if you need results delivered to your own endpoint in real time.
To configure a webhook, go to **Settings > Webhooks** in the Dashboard and add a new endpoint. Select the **Email Intel Completed** event type, enter your target URL, and click **Create**.
Your webhook endpoint must:
* Accept **POST** requests with **JSON** payloads
* Respond with a **2xx** HTTP status code on success
* Be **idempotent** (Verisoul may retry delivery)
* **Verify webhook signatures** for security (see [Step 3](#step-3-receive-and-verify-webhook-results))
Once configured, Verisoul will automatically deliver results to this endpoint when email analysis completes.
***
## Step 2: Submit Emails
Submit emails to the `POST /email` endpoint. You can submit a single email or a batch of emails.
Submit a single email with optional identity claims. Returns a `request_id` for webhook correlation.
Submit up to 1,000 emails with per-email claims. Returns a `batch_id` for grouping webhook results.
The API responds immediately with a `request_id` (single) or `batch_id` (batch), plus a `webhook_configured` boolean indicating whether a webhook subscription is active for your project. This confirms the email has been accepted for processing — it does not contain the analysis results.
***
## Step 3: Receive and Verify Webhook Results
Once analysis completes, Verisoul delivers a webhook to your configured endpoint with the event type `email.intelligence.completed`.
### Webhook Signature Verification
All webhook requests include an `x-signature` header containing an HMAC-SHA256 signature over the timestamp, selected headers, and the raw request body.
See the **[Webhook Signature Verification](/email-intelligence/webhook-signature-verification)** guide for the full algorithm, code examples in Node.js, Python, Go, and C#, and troubleshooting tips.
Always verify the signature before processing the payload. Use the **raw request body** (not a parsed/re-serialized version) and enforce a timestamp tolerance of ±5 minutes.
### Processing the Payload
1. Verify the webhook signature
2. Check the `status` field — either `success` or `error`
3. On success, use `data.result.decision` and `data.result.risk_score` for your business logic
4. On error, inspect the `error` object for details
See the [Webhook Payload Reference](/email-intelligence/webhook-reference) for the full payload structure and field definitions.
### Latency and Delivery Guarantees
The time between submitting an email and receiving the webhook depends on whether Verisoul has previously analyzed the email or its domain.
**Single email requests:**
| Scenario | Typical latency |
| ------------------------------------ | -------------------------------------------- |
| Invalid or previously analyzed email | Under **1 second** |
| New email on a known domain | Approximately **5 seconds** |
| New domain never seen before | **30–60 seconds** (one-time domain analysis) |
Verisoul guarantees that the webhook for a single email request will be delivered within **60 seconds** of submission. If analysis has not completed by then, a webhook is sent with `status: "error"` and `error.code: "timed_out"` so your system is never left waiting.
**Batch requests:**
Batch submissions are processed at a default throughput of approximately **200 emails per minute** per project. So a batch of 1,000 emails is fully processed and all of its webhooks delivered within about **5 minutes** of submission, and a batch of 200 within about **1 minute**.
Each email in the batch triggers its own webhook as soon as its analysis completes — you do not need to wait for the entire batch to finish before receiving results, and you can submit additional batches without waiting for earlier ones to drain.
If your use case requires higher throughput (for example, processing tens of thousands of emails in tight windows), [contact us](mailto:support@verisoul.ai) and we can raise your project's batch processing rate.
Batch emails are processed at a lower priority than single email requests, so real-time single-email submissions are never delayed by batch processing.
***
## FAQ
If your endpoint does not return a 2xx response, Verisoul retries delivery up to **3 times** over approximately **3.5 minutes**:
* 1st retry: 3 seconds after the initial failure
* 2nd retry: 10 seconds later
* 3rd retry: 3 minutes later
After the retry window expires, the webhook is marked as failed and no further attempts are made. Webhooks may be delivered more than once, so your endpoint must be idempotent.
Calls to `/email` count toward your API key's rate limit. If you need a higher limit, contact Verisoul.
All Verisoul webhooks are sent from:
```
34.71.198.163
```
You can allowlist this IP if your endpoint is behind a firewall. You should still verify webhook signatures regardless.