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

# mailfloss

mailfloss provides email verification APIs for checking individual addresses and processing asynchronous verification batches.

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

## Tools

### Cancel Batch Verification

**Slug:** `MAILFLOSS_CANCEL_BATCH_VERIFICATION`

Cancel a pending or in-progress batch verification job. This irreversible operation stops remaining work and re-credits unprocessed emails; it is a no-op if the job has already completed. Composio generates an idempotency key when omitted and preserves it for retries within this execution. Reuse a caller-supplied key for the same cancellation across separate calls.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `batch_id` | string | Yes | Batch verification job ID to cancel. |
| `idempotency_key` | string | No | Deduplication key retained for 24 hours. Composio generates one when omitted and preserves it for retries within this action execution. Supply the same key when retrying this cancellation in a separate action call. Concurrent reuse can fail with 409, and reuse with a different request can fail with 422. |

#### 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 |

### Check API Key

**Slug:** `MAILFLOSS_CHECK_API_KEY`

Verify that the connected Mailfloss API key is valid. Uses the connection's Bearer credential and does not accept credentials, request widget tokens, or return signed-proof fields.

#### 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 Batch Verification

**Slug:** `MAILFLOSS_CREATE_BATCH_VERIFICATION`

Submit email addresses for asynchronous batch verification and return the job ID. Optionally request a completion webhook instead of polling. This billable action can fail with 402 insufficient_credits. Composio generates an idempotency key when none is supplied, so internal retries reuse the same key and email list. Separate action calls replay the cached response only when the caller reuses that key with identical emails; changing the list fails with 422, while a concurrent same-key request can fail with 409.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `emails` | array | Yes | Email addresses to verify in the asynchronous batch. |
| `webhook_url` | string | No | Optional HTTPS callback URL. When the batch finishes, Mailfloss sends the completed job ID and verdict summary to this URL. Omit it to poll batch status and results instead. |
| `idempotency_key` | string | No | Deduplication key retained for 24 hours. Composio generates one when this is omitted. Supply a key and preserve the exact key and email list when retrying the same logical batch across separate action calls. Reusing it with different emails fails with 422, and a concurrent request using the same key can fail with 409. Calls that reuse a supplied key and identical emails replay the cached response for 24 hours. |

#### 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 |

### Erase Verification Records

**Slug:** `MAILFLOSS_ERASE_VERIFICATION_RECORDS`

Permanently erase stored verification records for the supplied email addresses. This destructive data-privacy operation is irreversible; erased records cannot be recovered. Addresses with no stored records are a successful no-op. The body contains only the documented emails array. Composio generates an idempotency key when omitted and preserves it for retries within this execution.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `emails` | array | Yes | Email addresses whose stored verification records will be permanently erased. |
| `idempotency_key` | string | No | Deduplication key retained for 24 hours. Composio generates one when omitted and preserves it for retries within this action execution. Supply the same key and exact email list when retrying an erasure in a separate action call. Concurrent reuse can fail with 409, and reuse with a different email list can fail with 422. |

#### 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 Account

**Slug:** `MAILFLOSS_GET_ACCOUNT`

Return the authenticated Mailfloss account holder's identity, contact details, security posture, notification preferences, and signup time. This read does not expose API credentials or two-factor secrets.

#### 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 Batch Verification Results

**Slug:** `MAILFLOSS_GET_BATCH_VERIFICATION_RESULTS`

Return one cursor-controlled page of stored batch results after organization floss-setting overrides. These statuses and reasons can differ from Verify Email's raw verdict for the same address; fetching stored results is not documented as consuming verification credits.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `next` | string | No | Opaque next token returned at the top level of the prior response; omit it for the first page and pass it back unchanged. |
| `batch_id` | string | Yes | Completed or processing batch verification job ID returned by Create Batch Verification. |
| `per_page` | integer | No | Maximum result rows to return in this page, capped at 1000. |

#### 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 Batch Verification Status

**Slug:** `MAILFLOSS_GET_BATCH_VERIFICATION_STATUS`

Read an asynchronous batch verification job's state and available counters. Polling is not documented as consuming verification credits; authentication, policy, not-found, rate-limit, and server responses remain errors rather than job states.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `batch_id` | string | Yes | Batch verification job ID returned by Create Batch 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 |

### Get Verification Job

**Slug:** `MAILFLOSS_GET_JOB`

Return one verification job and its complete verdict breakdown. Results are null until completion and include all per-reason counters when present.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | Yes | Verification job ID returned by List Jobs or a batch submission. |

#### 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 Organization

**Slug:** `MAILFLOSS_GET_ORGANIZATION`

Return the authenticated Mailfloss organization's plan, credit balances, current-period usage, trial state, account status, and feature entitlements. This is a read-only view and does not expose API or billing credentials.

#### 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 Usage Report

**Slug:** `MAILFLOSS_GET_USAGE_REPORT`

Return verification usage for a UTC calendar period, optionally scoped to one ESP connection. Lifetime reports contain only the authoritative total; their range, status counts, and reason counts are null.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `period` | string ("this_week" | "this_month" | "this_year" | "lifetime") | No | UTC calendar period. Omit to use Mailfloss's default of this_month. |
| `connection_id` | string | No | Optional public ESP connection ID. Lifetime reports are organization-wide and cannot use this filter. |

#### 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 Verification Jobs

**Slug:** `MAILFLOSS_LIST_JOBS`

Return one page of the organization's verification-job history, newest first, with optional source and lifecycle filters. Completed jobs include verdict totals; use Get Job for the full per-reason breakdown.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cursor` | string | No | Opaque cursor returned in pagination.next_cursor by a prior call. Pass it back unchanged. |
| `source` | string ("api" | "csv" | "zapier" | "widget" | "input" | "integration") | No | Return only jobs submitted through this source. |
| `status` | string ("queued" | "processing" | "completed" | "cancelled") | No | Return only jobs in this lifecycle state. |
| `per_page` | integer | No | Number of jobs to return on this page (1-100). Omit to use Mailfloss's default of 25. |

#### 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:** `MAILFLOSS_VERIFY_EMAIL`

Verify one email address and return Mailfloss's raw engine verdict without organization floss-setting overrides. passed means safe to send, undeliverable is a hard failure, risky covers role, disposable, bounced, or complained addresses, and unknown includes accept-all addresses and transient SMTP failures. relay and gibberish are annotations and do not alter the verdict. Each successful call consumes one verification credit; a depleted balance fails with 402 insufficient_credits, so do not retry billable failures blindly.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | Yes | Email address to verify. |
| `timeout` | number | No | Optional provider-side verification timeout in seconds. This does not control the HTTP client timeout. |

#### 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 |