​
Overview

The EMAIL_CREATE_INBOX step creates or retrieves a test email inbox for receiving emails during test execution. This is the first step in any email testing workflow.

​
Parameters

​
inboxName
string
required
Unique identifier for the inbox. Best practice is to include timestamps or random values to ensure uniqueness across test runs.Examples:
  • signup-test
  • user-{{TIMESTAMP}}
  • order-{{RANDOM}}
​
email
string
Custom email address to use instead of the auto-generated format. If not provided, the system generates an address using the pattern: {org_prefix}+{inbox_name}@withkeystonemail.com
​
storeAs
string
required
Variable name to store the generated email address. This variable can be used in subsequent steps.

​
Behavior

  1. Inbox Creation: Creates a new inbox or retrieves existing one
  2. Address Generation: Generates email address if not custom
  3. Organization Binding: Associates inbox with your organization
  4. Variable Storage: Stores email address in specified variable
  5. Idempotent Operation: Safe to re-run with same inbox name

​
Common Use Cases

  • Creating unique test emails for user registration
  • Setting up email addresses for password reset testing
  • Generating customer emails for order confirmations
  • Isolating email tests between test runs

​
Examples

​
Basic Inbox Creation

  • Step type: EMAIL_CREATE_INBOX
  • Inbox name: test-user
  • Store as: USER_EMAIL

​
With Timestamp for Uniqueness

  • Step type: EMAIL_CREATE_INBOX
  • Inbox name: signup-
  • Store as: TEST_EMAIL
This creates a unique inbox for each test run.

​
Custom Email Address

  • Step type: EMAIL_CREATE_INBOX
  • Email: custom@example.com
  • Inbox name: custom-test
  • Store as: CUSTOM_EMAIL
Use this when you need a specific email format.

​
Multiple Inboxes in One Test

Admin inbox:
  • Step type: EMAIL_CREATE_INBOX
  • Inbox name: admin-
  • Store as: ADMIN_EMAIL
Customer inbox:
  • Step type: EMAIL_CREATE_INBOX
  • Inbox name: customer-
  • Store as: CUSTOMER_EMAIL

​
Generated Email Format

When not using a custom email, addresses follow this pattern: +@withkeystonemail.com Example: acme123456+signup-test@withkeystonemail.com Where:
  • acme123456 is your organization’s unique prefix
  • signup-test is your specified inbox name
  • @withkeystonemail.com is Keystone’s email domain

​
Best Practices

Always use unique inbox names for parallel test execution. Include timestamps or random values to prevent conflicts.
  1. Unique Names: Use {{TIMESTAMP}} or {{RANDOM}} for uniqueness
  2. Descriptive Names: Use names that indicate the test purpose
  3. Store Variables: Always store the email for use in later steps
  4. Clean Setup: Each test run gets a fresh inbox

​
Error Handling

The step will fail if:
  • Organization ID is not configured
  • Variable name conflicts with existing variables
  • Email service is temporarily unavailable