# Temp Email Inbox API — Create & Poll OTP (`khadinakbar/create-temp-email-inbox`) Actor

Create disposable temp email inboxes in bulk and poll for OTP/messages. QA/CI testing via Guerrilla Mail + mail.tm failover. Not for signup farming. Detection → email-address-validator. $0.003/inbox, $0.008/message.

- **URL**: https://apify.com/khadinakbar/create-temp-email-inbox.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** Developer tools, Automation, MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 temp inbox createds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Create Temp Email Inbox

Create disposable temporary email inboxes in bulk and poll them for inbound messages and OTP codes. Built for QA engineers, CI pipelines, and AI agents that need throwaway addresses for signup, magic-link, and transactional email testing. Each dataset row returns `email`, `provider`, session tokens, `subject`, `textPreview`, and optional `otp`.

### Best fit for this Actor

- Choose this Actor when you already control a staging app and need a disposable inbox to receive verification mail.
- Designed for QA create + poll workflows with Guerrilla Mail primary and mail.tm failover (`Powered by mail.tm`).
- Start with `mode: "createInbox"` and `count: 1`, then continue with `pollInbox` using the returned session token.
- For disposable-domain detection on an existing address, then use [Email Address Validator](https://apify.com/khadinakbar/email-address-validator).
- For breach-history enrichment of an email, then use [Email Breach Checker](https://apify.com/khadinakbar/email-breach-checker).

### Workflow story

A CI job starts with `createInbox`, pastes the returned address into a staging password-reset form, then polls the same inbox for up to 60 seconds. When the message arrives, `otp` is filled and the test asserts the code. If the window is empty, the Actor ends with `VALID_EMPTY` with no message event charges — keep the token and poll again after the app sends mail.

### Quick start input

```json
{
  "mode": "createInbox",
  "provider": "auto",
  "count": 1,
  "extractOtp": true
}
```

### Input reference

| Field | Type | What it controls |
| --- | --- | --- |
| `mode` | string | `listDomains`, `createInbox`, `pollInbox`, or `createAndPoll` |
| `provider` | string | `auto` (default), `guerrilla`, or `mailtm` |
| `count` | integer | Inboxes to create, 1–25. Prefill 1 |
| `pollDurationSecs` | integer | Poll window 0–120 seconds |
| `extractOtp` | boolean | Parse 4–8 digit codes from subject/body |
| `matchSubject` / `matchFrom` | string | Optional filters |
| `email` + session secrets | string | Required for `pollInbox` |

### What data you receive

Each dataset item is an inbox, message, or domain row.

```json
{
  "recordType": "inbox",
  "email": "example@guerrillamailblock.com",
  "provider": "guerrilla",
  "guerrillaSidToken": "session-token",
  "createdAt": "ISO-8601 timestamp",
  "mode": "createInbox",
  "outcome": "OK"
}
```

| Field | Meaning |
| --- | --- |
| `recordType` | `inbox`, `message`, or `domain` |
| `email` | Disposable address |
| `provider` | `guerrilla` or `mailtm` |
| `guerrillaSidToken` / `mailtmToken` | Session credentials for later poll |
| `from` / `subject` / `textPreview` | Inbound message fields |
| `otp` | Extracted verification code when present |

`OUTPUT` and `RUN_SUMMARY` hold `outcome`, `itemsPushed`, `inboxesCreated`, and `messagesReceived`. Download the dataset as JSON, CSV, Excel, or HTML.

### Pricing (Pay per event + usage)

Pay per event with caller-paid platform usage. The live Pricing tab is the current source of truth.

| Event | Price |
| --- | --- |
| Actor start | $0.00005 |
| Inbox created | $0.003 |
| Message received | $0.008 |

Worked example: create 3 inboxes ≈ `$0.00005 + 3 × $0.003 = $0.00905` plus platform usage. Domain-list rows and empty polls skip charging inbox or message events.

### Use through the API

```bash
curl -X POST "https://api.apify.com/v2/acts/khadinakbar~create-temp-email-inbox/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"createInbox","provider":"auto","count":1}'
```

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('khadinakbar/create-temp-email-inbox').call({
  mode: 'createInbox',
  provider: 'auto',
  count: 1,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

On Apify MCP, call `apify--create-temp-email-inbox`.

#### Agent prompt card

> Create one disposable email inbox for QA, return the address and session token with provenance fields, then poll for up to 60 seconds for a verification message and extract any OTP. Prefer VALID\_EMPTY over fabricating messages when the window is quiet.

### Best results

- Provide a short `pollDurationSecs` first, then extend if the staging app is slow.
- Start with `provider: "auto"` so Guerrilla → mail.tm failover covers outages.
- Confirm the staging app actually sent mail before repeating an empty poll.
- Keep `count` focused (1–5) for CI; schedule larger batches as separate runs.
- Validate session tokens from create rows before calling `pollInbox`.

### Builder's note

I built this Actor around documented Guerrilla and mail.tm HTTP APIs after finding that temp-mail HTML UIs change too often for reliable QA automation. My goal was a multi-provider OTP catcher with honest empty-poll semantics, not another thin single-API wrap.

### Responsible use

### Responsible use

Use on systems you are authorized to test. Respect provider rate limits, applicable laws, and Apify Store policies.
Guerrilla Mail is a trademark of its respective owners. This independent Actor is not affiliated with or endorsed by Guerrilla Mail. mail.tm is a trademark of its respective owners. Portions of this Actor are Powered by mail.tm. This Actor is not affiliated with or endorsed by mail.tm.

# Actor input Schema

## `mode` (type: `string`):

What to do. listDomains returns available domains. createInbox mints addresses. pollInbox reads an existing inbox. createAndPoll mints then waits for mail.

## `provider` (type: `string`):

Temp-mail backend. auto tries Guerrilla Mail first, then mail.tm. Pin guerrilla or mailtm to force one provider.

## `count` (type: `integer`):

How many disposable inboxes to create (createInbox / createAndPoll). Hard-capped at 25 per run.

## `pollDurationSecs` (type: `integer`):

How long to wait for inbound mail (pollInbox / createAndPoll). 0–120. Empty window returns VALID\_EMPTY with no message charges.

## `extractOtp` (type: `boolean`):

When true, parse 4–8 digit verification codes from subject/body into the otp field.

## `matchSubject` (type: `string`):

Optional case-insensitive subject filter. Only matching messages are saved.

## `matchFrom` (type: `string`):

Optional case-insensitive sender filter. Only matching messages are saved.

## `email` (type: `string`):

Required for pollInbox. The disposable address to read.

## `guerrillaSidToken` (type: `string`):

You must supply your own Guerrilla sid\_token for this run (from a prior create). This input secret is never written to the dataset, output, or logs.

## `mailtmToken` (type: `string`):

You must supply your own mail.tm JWT for this run (from a prior create). This input secret is never written to the dataset, output, or logs.

## `mailtmPassword` (type: `string`):

You must supply your own mail.tm password for this run if the JWT expired. This input secret is never written to the dataset, output, or logs.

## Actor input object example

```json
{
  "mode": "createInbox",
  "provider": "auto",
  "count": 1,
  "pollDurationSecs": 5,
  "extractOtp": true
}
```

# Actor output Schema

## `results` (type: `string`):

Inbox, message, and domain rows from this run.

## `output` (type: `string`):

Final outcome, itemsPushed, inboxesCreated, messagesReceived.

## `runSummary` (type: `string`):

Mode, provider usage, pricing, and outcome.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "createInbox",
    "provider": "auto",
    "count": 1,
    "pollDurationSecs": 5,
    "extractOtp": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/create-temp-email-inbox").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "createInbox",
    "provider": "auto",
    "count": 1,
    "pollDurationSecs": 5,
    "extractOtp": True,
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/create-temp-email-inbox").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "createInbox",
  "provider": "auto",
  "count": 1,
  "pollDurationSecs": 5,
  "extractOtp": true
}' |
apify call khadinakbar/create-temp-email-inbox --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,khadinakbar/create-temp-email-inbox"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/dWBlHQJYKC5V9hvZN/builds/n4ZS55lcJE4LCrepi/openapi.json