---
canonical_url: "https://docs.composio.dev/toolkits/mailvalid"
markdown_url: "https://docs.composio.dev/toolkits/mailvalid.md"
product: "platform"
version: null
last_updated: null
---

# MailValid

MailValid verifies individual and bulk email addresses, tracks verification jobs and credits, and processes delivery feedback.

- **Category:** email
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 9
- **Triggers:** 0
- **Slug:** `MAILVALID`
- **Version:** 00000000_00

## Tools

### Cancel Bulk Job

**Slug:** `MAILVALID_CANCEL_BULK_JOB`

DESTRUCTIVE: Cancel a pending or processing bulk verification job. Completed billable rows remain charged, while only unused reserved credits are released; inspect the job first and call only when cancellation is intended.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | Yes | ID of the pending or processing bulk job to cancel. Verify the job status before calling. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Bulk Verification

**Slug:** `MAILVALID_CREATE_BULK_VERIFICATION`

PAID / CREDIT-CONSUMING: Create an asynchronous verification job for many email addresses. MailValid reserves up to one credit per submitted address and charges billable results; unknown results and duplicates are free. Confirm the balance and list size before calling; free accounts accept up to 100 addresses and paid accounts up to 10,000.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `emails` | array | Yes | Email addresses to verify (1-10,000). Free accounts accept at most 100 addresses. Blank entries are stripped by MailValid, and malformed nonblank addresses may be classified instead of rejecting the batch. |
| `filename` | string | No | Optional display-only source filename echoed in bulk job reads. |
| `source_data` | object | No | Optional source columns and per-email row values to append to result exports. |
| `webhook_url` | string | No | Optional HTTPS callback URL for job completion, up to 2,048 characters. Completion webhooks are advertised as a paid-plan feature; omit this unless the account supports them and the receiver is ready. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Download Bulk Results

**Slug:** `MAILVALID_DOWNLOAD_BULK_RESULTS`

Download a completed bulk job's results as JSON or CSV, optionally filtered by verification status. This consumes no credits. MailValid advertises bulk export as paid, but JSON export was observed working on a free account; CSV tier access remains unverified.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `filter` | string ("all" | "valid" | "invalid" | "catch_all" | "unknown" | "do_not_mail") | No | Verification-status subset to include in the export. |
| `format` | string ("json" | "csv") | No | Export format. JSON returns structured results; CSV returns a downloadable file. |
| `job_id` | string | Yes | Completed bulk verification job ID whose results should be exported. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Bulk Job

**Slug:** `MAILVALID_GET_BULK_JOB`

Get one bulk verification job's status, progress, metadata, and currently available inline results. This read consumes no credits; poll deliberately rather than in an unbounded loop.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | Yes | Bulk verification job ID returned by creation or listing. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Credit Balance

**Slug:** `MAILVALID_GET_CREDIT_BALANCE`

Return the connected MailValid account's current credit balance and lifetime credit usage. Use this free read before credit-consuming verification when spend matters.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Bulk Jobs

**Slug:** `MAILVALID_LIST_BULK_JOBS`

List one native page of bulk verification jobs, optionally filtered by status. This read consumes no credits; use page and page_size to control traversal.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | One-based page number to return. Increment only when has_more is true. |
| `status` | string | No | Optional provider job-status filter. MailValid does not document a closed set of accepted values. |
| `page_size` | integer | No | Maximum number of bulk verification jobs to return in this page. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Submit Bounce Events

**Slug:** `MAILVALID_SUBMIT_BOUNCE_EVENTS`

STATE-MUTATING: Submit real delivery, bounce, complaint, or unsubscribe feedback that can change MailValid reputation history, cached results, and future validity classifications. Explicitly confirm every event came from an authoritative mail system; never invent feedback to test this action.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `events` | array | Yes | One to 1,000 authoritative delivery-feedback events. Never submit synthetic, guessed, or test events because they can change reputation history and future email classifications. |
| `confirm_authoritative_events` | boolean | Yes | Confirm that every event came from an authoritative mail delivery system and is not synthetic or inferred. This confirmation is required and is not sent to MailValid. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Verify Email

**Slug:** `MAILVALID_VERIFY_EMAIL`

PAID / CREDIT-CONSUMING: Verify one email using MailValid's syntax, domain, MX, SMTP, disposable, role, catch-all, and provider checks. Billable outcomes consume one credit even when cached; unknown outcomes consume none. Check MAILVALID_GET_CREDIT_BALANCE first when spend matters.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | Yes | Email address to verify. MailValid may reject reserved or special-use domains before running verification. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Verify Webhook Signature

**Slug:** `MAILVALID_VERIFY_WEBHOOK_SIGNATURE`

Verify an X-Mailvalid-Signature HMAC-SHA256 header against the exact raw completion-webhook body. The action retrieves the connected account's stable signing secret internally and never returns it.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `raw_body` | string | Yes | Exact raw UTF-8 webhook request body as received. Do not parse, format, or re-serialize the JSON before verification. This value is used locally and is not sent to MailValid. |
| `signature` | string | Yes | Hexadecimal X-Mailvalid-Signature header supplied with the webhook. This value is used locally and is not sent to MailValid. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |
