Disposable Temporary Email API

Create a disposable temporary email address and poll its inbox for signup verification, OTP, and email-delivery QA. The Actor returns normalized mailbox and full-message records through an Apify dataset, so test automation does not need to maintain a permanent mailbox.

It uses the public mail.tm API. A generated inbox can be removed automatically after a bounded polling window, or retained when a later run must read it.

What does this Actor do?

The Actor supports four workflows:

1. createAndPoll creates a mailbox, returns its address immediately, polls for messages, and can delete it at the end.
2. createOnly creates an address without waiting for mail.
3. pollExisting authenticates to a previously retained mail.tm mailbox and downloads matching messages.
4. listDomains returns the provider's current active public domains.

For each received email, it fetches the full message rather than returning only an inbox preview. The result includes sender, recipients, subject, plain text, HTML parts, attachment metadata, and timestamps.

Who is it for?

• QA engineers testing signup, password-reset, invitation, and notification flows
• Developers validating transactional email in CI or staging environments
• Automation teams that need a short-lived inbox between workflow steps
• Deliverability teams checking whether a test message reached a disposable mailbox
• Integration builders that need normalized JSON instead of provider-specific responses

This tool is intended for systems you own or are authorized to test. It is not designed for bulk account creation, spam, evading platform controls, or accessing another person's messages.

Why use this temporary email service workflow?

A browser-based temporary mail page is awkward to automate and can change without notice. This Actor provides:

• an API-first workflow with no browser rendering;
• an immediate mailbox dataset row that another automation step can read;
• bounded polling from 0 to 240 seconds;
• subject and sender filters;
• full message bodies and normalized parties;
• explicit maximum-message limits;
• transient retry handling for network errors, rate limits, and server errors;
• optional cleanup of generated mailboxes;
• pay-per-result billing with no charge for empty polls.

Input parameters

Field	Type	Default	Description
mode	string	createAndPoll	createAndPoll, createOnly, pollExisting, or listDomains
address	string	—	Existing mail.tm address required by pollExisting
password	string	generated	Existing password, or an optional password for a new mailbox
usernamePrefix	string	random	Readable prefix; a random suffix is always appended
domain	string	first active domain	Optional currently active public mail.tm domain
pollDurationSecs	integer	30	Polling window from 0 to 240 seconds
pollIntervalSecs	integer	5	Delay from 2 to 30 seconds between inbox reads
maxMessages	integer	10	Maximum matching full messages, from 1 to 100
subjectContains	string	—	Case-insensitive subject substring
senderContains	string	—	Case-insensitive sender-address substring
deleteAfterRun	boolean	mode-dependent	Delete a mailbox generated by this run
includeCredentialsInOutput	boolean	false	Include the generated password in the mailbox row

pollExisting requires both address and password. The Actor never logs the password. If credentials are included in output, treat the run dataset as a secret.

Getting started

1. Open the Actor in Apify Console.
2. Keep mode set to createAndPoll.
3. Choose a short usernamePrefix meaningful to the test.
4. Set a polling window long enough for the application under test to send its message.
5. Start the Actor.
6. Read the first mailbox dataset row to obtain the generated address.
7. Submit that address to your authorized signup or delivery test.
8. Wait for message rows or for the polling window to finish.
9. Keep deleteAfterRun enabled unless a later run must reuse the inbox.

A run with no matching email still returns the created mailbox record. It does not invent a message or treat an empty inbox as an error.

Example inputs

Create and watch a short-lived signup inbox

{
  "mode": "createAndPoll",
  "usernamePrefix": "signup-qa",
  "pollDurationSecs": 60,
  "pollIntervalSecs": 5,
  "maxMessages": 3,
  "subjectContains": "verification",
  "deleteAfterRun": true
}

Create a reusable test mailbox

{
  "mode": "createOnly",
  "usernamePrefix": "delivery-test",
  "deleteAfterRun": false,
  "includeCredentialsInOutput": true
}

Download and secure the result before using that mailbox in pollExisting mode.

Poll an existing inbox once

{
  "mode": "pollExisting",
  "address": "your-retained-mailbox@current-provider-domain",
  "password": "your-secret-password",
  "pollDurationSecs": 0,
  "maxMessages": 10
}

Output records

The default dataset can contain three record types.

Record	Important fields	When emitted
mailbox	mailboxId, address, password, deleteAfterRun, createdAt	After a new mailbox is created
message	messageId, from, to, subject, text, html, attachments, receivedAt	After a matching full message is downloaded
domain	domainId, domain, isActive, isPrivate	In listDomains mode

Fields that do not apply to a record type are absent. Provider fields that are unavailable are returned as null or an empty array.

Example message output

{
  "recordType": "message",
  "provider": "mail.tm",
  "mailboxAddress": "signup-qa-a1b2c3d4@current-provider-domain",
  "messageId": "67a76543bcde210987654321",
  "from": {
    "address": "noreply@service.test",
    "name": "Example Service"
  },
  "to": [
    {
      "address": "signup-qa-a1b2c3d4@current-provider-domain",
      "name": null
    }
  ],
  "cc": [],
  "subject": "Confirm your test account",
  "intro": "Use the verification link to continue.",
  "text": "Your verification code is 123456.",
  "html": ["<p>Your verification code is <strong>123456</strong>.</p>"],
  "seen": false,
  "hasAttachments": false,
  "attachments": [],
  "receivedAt": "2026-09-19T14:00:00+00:00",
  "downloadedAt": "2026-09-19T14:00:05.000Z"
}

The values above are anonymized. Actual domain availability is controlled by mail.tm and changes over time.

How much does it cost to create and poll a temporary email inbox?

The Actor uses pay-per-event pricing:

• Start: $0.00005 once per run.
• Item extracted: one event for each useful mailbox, full message, or active domain row.
• Empty polls, retries, filtered-out messages, and failed operations do not create result charges.

Current result prices are:

Apify plan	Price per result
Free	$0.00276
Bronze	$0.00240
Silver	$0.001872
Gold	$0.00144
Platinum	$0.00144
Diamond	$0.00144

On the Bronze plan, a create-and-poll run that returns one mailbox and one message is about $0.00485. Ten useful results are about $0.02405, including the start event. One hundred useful results are about $0.24005. Infrastructure use can also count toward your Apify platform usage under your account plan. Refunds, disputes, taxes, fraud adjustments, and platform corrections can affect final billing.

Signup-flow QA pattern

Start the Actor asynchronously and watch its dataset. When the mailbox row appears, pass its address to the application under test. The same run continues polling and adds message rows as mail arrives.

A robust workflow should:

1. set a bounded polling duration;
2. use subjectContains or senderContains when unrelated mail is possible;
3. fail the test if no expected message arrives;
4. parse the text or HTML body in a downstream step;
5. retain test evidence only as long as needed; and
6. let the Actor delete the disposable mailbox.

Email-delivery monitoring pattern

For a scheduled delivery check, use a retained mailbox:

1. run createOnly with deleteAfterRun: false and includeCredentialsInOutput: true;
2. move the credentials into your secret manager;
3. delete or restrict the original dataset;
4. send authorized test messages on your schedule; and
5. use pollExisting with the secret input to collect new messages.

The Actor is not a durable mailbox service. mail.tm can rotate domains, expire accounts, or change limits.

API access with cURL

curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~temporary-email-inbox-api/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "createAndPoll",
    "usernamePrefix": "signup-qa",
    "pollDurationSecs": 30,
    "maxMessages": 3,
    "deleteAfterRun": true
  }'

To wait for completion and receive dataset items directly, use the synchronous dataset endpoint supported by the Apify API. For longer polling windows, asynchronous runs are preferable.

JavaScript integration

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/temporary-email-inbox-api').call({
    mode: 'createAndPoll',
    usernamePrefix: 'signup-qa',
    pollDurationSecs: 60,
    subjectContains: 'verification',
    maxMessages: 3,
    deleteAfterRun: true,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
const mailbox = items.find((item) => item.recordType === 'mailbox');
const messages = items.filter((item) => item.recordType === 'message');
console.log({ mailbox, messages });

Python integration

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/temporary-email-inbox-api').call(run_input={
    'mode': 'listDomains',
})
items = client.dataset(run['defaultDatasetId']).list_items().items
for item in items:
    print(item['domain'])

Do not hard-code retained mailbox passwords in source code. Pass them through a secret store or protected Actor input.

Use with Apify MCP

Claude Code

Add this Actor from a terminal:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/temporary-email-inbox-api"

Claude Desktop

Add this server object to the Claude Desktop MCP configuration:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/temporary-email-inbox-api"
    }
  }
}

Cursor

Add the same apify server object to Cursor's MCP settings and use the Actor-specific URL shown above.

VS Code

Add the same HTTP MCP server URL to your VS Code MCP configuration, then enable the automation-lab/temporary-email-inbox-api tool.

Example prompts:

• "List the active temporary email domains and return the shortest domain."
• "Create a disposable signup-test inbox and poll for 30 seconds."
• "Read my retained test mailbox once and return messages whose subject contains verification."

Never paste a real mailbox password into a shared conversation. Use your client's secret-input mechanism.

Limits and reliability

• Polling is capped at 240 seconds per run.
• The Actor reads the first current inbox page and accepts at most 100 matching messages.
• The public provider advertises a 30-request-per-minute limit.
• The minimum poll interval is two seconds.
• Network errors, HTTP 429, and temporary 5xx responses retry up to three times.
• Invalid credentials and other deterministic 4xx responses fail without blind retries.
• No residential proxy or browser fallback is used.
• Attachments are represented as metadata and provider URLs; binary files are not downloaded.
• A newly generated address is unique but delivery from a third-party sender is never guaranteed.
• Provider availability and retention are outside this Actor's control.

Data handling and privacy

Email messages may contain personal data, security codes, or private links. Only process messages you are authorized to receive. Minimize polling windows and delete datasets when the test evidence is no longer needed.

Generated passwords are excluded from output by default. When includeCredentialsInOutput is enabled, anyone who can read the dataset may be able to access the retained mailbox. Restrict dataset access and rotate or delete the mailbox after use.

The Actor sends mailbox registration and inbox requests to mail.tm. It does not use AI, train models, send outgoing email, or forward message content to another service. Apify stores run inputs and datasets according to your platform settings and retention policy.

Legality and responsible use

Use disposable addresses only for legitimate QA, development, privacy protection, and delivery testing. Do not use this Actor to create deceptive accounts, bypass access controls, abuse promotions, harvest private mail, or violate a website's terms.

You are responsible for:

• authorization to test the target application;
• the content sent to the temporary address;
• applicable privacy and data-retention rules;
• protecting retained credentials and message content; and
• complying with mail.tm and Apify terms.

FAQ and troubleshooting

Why did I get a mailbox but no message?

The sender may not have sent yet, delivery may be delayed, the filter may not match, or the provider may have rejected the message. Increase pollDurationSecs within the 240-second limit and confirm the subject/sender filter. An empty inbox is valid and is not billed as a message.

Why did authentication fail?

Confirm that the address belongs to mail.tm, the mailbox was not deleted, and the password is exact. A mailbox created with deleteAfterRun: true cannot be reused after that run.

Why is my preferred domain rejected?

Domains rotate. Run listDomains, then use one of the current records or omit domain to select automatically.

Can this Actor send email?

No. It creates and reads disposable inboxes only. Use your application or authorized email provider to send the test message.

Does it extract verification codes automatically?

It returns normalized text and HTML bodies so a downstream step can extract the code or link. It does not guess which substring is a code.

Related automation-lab Actor

• Bulk SMTP Email Verifier — Mailbox & Catch-All Checker checks whether supplied addresses are deliverable. Use it for list validation, not temporary inbox creation.

Support

If a run fails, include the public run URL, selected mode, and the non-secret part of the input in your report. Never include mailbox passwords, private verification links, or complete message bodies in a support request.