Developer Guide

Integration testing for developers - API-driven email testing in your applications

Perfect for Automated Testing

Generate disposable emails programmatically and verify email content in your test suites. FounderMail provides a robust API that integrates seamlessly with your existing testing frameworks.

Why Use FounderMail for Integration Testing? Traditional email testing is slow, unreliable, and requires complex setup. FounderMail provides instant, isolated email addresses that work perfectly in automated test environments.

Step 1: Get Your API Key

Before you can use the FounderMail API, you need to obtain an API key from your dashboard.

1. Sign up for a free FounderMail account
2. Navigate to Settings → API Keys
3. Click Generate API Key
4. Copy and store it securely in your test environment

All API requests require authentication via the X-Api-Key header. Keep your API key secure and never commit it to version control.

# Store your API key as environment variable
$ export FOUNDERMAIL_API_KEY="your-api-key-here"

# Or in your test configuration
import os

API_KEY = os.getenv("FOUNDERMAIL_API_KEY")
API_BASE = "https://api.foundermail.mx"

# Install the SDK: pip install foundermail-client

# Configure the client
from foundermail_client import Configuration, ApiClient
from foundermail_client.api.mailboxes_api import MailboxesApi
from foundermail_client.api.messages_api import MessagesApi

import os
api_key = os.getenv("FOUNDERMAIL_API_KEY")

configuration = Configuration(
    host="https://api.foundermail.mx"
)
configuration.api_key['ApiKey'] = api_key

api_client = ApiClient(configuration)
mailboxes_api = MailboxesApi(api_client)
messages_api = MessagesApi(api_client)

// Store your API key as environment variable
$ export FOUNDERMAIL_API_KEY="your-api-key-here"

// Or in your test configuration
const API_KEY = process.env.FOUNDERMAIL_API_KEY;
const API_BASE = 'https://api.foundermail.mx';

// Install the SDK: npm install @founder-mail/client-api

// Configure the client
import { Configuration, MailboxesApi, MessagesApi } from '@founder-mail/client-api';

const apiKey = process.env.FOUNDERMAIL_API_KEY;

const configuration = new Configuration({
    basePath: 'https://api.foundermail.mx',
    baseOptions: {
        headers: {
            'X-API-Key': apiKey
        }
    }
});

const mailboxesApi = new MailboxesApi(configuration);
const messagesApi = new MessagesApi(configuration);

// Store in appsettings.json or user secrets
{
  "FounderMail": {
    "ApiKey": "your-api-key-here",
    "ApiBase": "https://api.foundermail.mx"
  }
}

// Or use environment variables
var apiKey = Environment.GetEnvironmentVariable("FOUNDERMAIL_API_KEY");

// Install the SDK: dotnet add package FounderMail.Client

// Configure in Program.cs or Startup.cs
using FounderMail.Client.Extensions;

var apiKey = Environment.GetEnvironmentVariable("FOUNDERMAIL_API_KEY");

services.AddApi(config =>
{
    config.AddApiHttpClients(client =>
    {
        client.BaseAddress = new Uri("https://api.foundermail.mx");
        client.DefaultRequestHeaders.Add("X-Api-Key", apiKey);
    });
});

// Store your API key as environment variable
$ export FOUNDERMAIL_API_KEY="your-api-key-here"

// Or in your test configuration
import "os"

apiKey := os.Getenv("FOUNDERMAIL_API_KEY")
apiBase := "https://api.foundermail.mx"

Step 2: Create a Temporary Mailbox

Create a disposable mailbox that will receive your test emails. Each mailbox gets a unique email address and password for SMTP authentication.

Temporary mailboxes are perfect for integration tests that need isolated, thread-safe email addresses.

Optional: You can specify a projectName to organize mailboxes. If not provided, your default project will be used.

SMTP Note: For direct SMTP sending, use the mailbox key (without @foundermail.mx) as the username and the password for authentication with smtp.foundermail.mx:587. Mail submitted this way is captured in the mailbox rather than delivered, unless the mailbox is switched to relay mode.

import requests

API_KEY = "your_api_key"
headers = {"X-Api-Key": API_KEY}

# Create a temporary mailbox (uses default project)
response = requests.post(
    "https://api.foundermail.mx/mailboxes",
    headers=headers,
    json={})

# Or specify a project: json={"projectName": "MyProject"}

mailbox = response.json()
print(f"Mailbox Key: {mailbox['key']}")
print(f"Email Address: {mailbox['key']}@foundermail.mx")
print(f"Password: {mailbox['password']}"

from foundermail_client.api.mailboxes_api import MailboxesApi
from foundermail_client.models.mailbox_create_model import MailboxCreateModel

# Create a temporary mailbox (uses default project)
mailbox_create_model = MailboxCreateModel()
# Or specify project: mailbox_create_model.project_name = "MyProject"

mailbox = mailboxes_api.create_mailbox(
    mailbox_create_model=mailbox_create_model
)

print(f"Mailbox Key: {mailbox.key}")
print(f"Email Address: {mailbox.key}@foundermail.mx")
print(f"Password: {mailbox.password}"

const API_KEY = 'your_api_key';
const headers = { 'X-Api-Key': API_KEY };

// Create a temporary mailbox (uses default project)
const response = await fetch(
    'https://api.foundermail.mx/mailboxes',
    {
        method: 'POST',
        headers: {
            ...headers,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({})
        // Or: body: JSON.stringify({ projectName: 'MyProject' })
    });

const mailbox = await response.json();
console.log(`Mailbox Key: ${mailbox.key}`);
console.log(`Email: ${mailbox.key}@foundermail.mx`);

import { MailboxesApi, MailboxCreateModel } from '@founder-mail/client-api';

// Create a temporary mailbox (uses default project)
const mailboxCreateModel = {};
// Or specify project: const mailboxCreateModel = { projectName: 'MyProject' };

const response = await mailboxesApi.createMailbox(mailboxCreateModel);
const mailbox = response.data;

console.log(`Mailbox Key: ${mailbox.key}`);
console.log(`Email: ${mailbox.key}@foundermail.mx`);
console.log(`Password: ${mailbox.password}`);

using System.Net.Http;
using System.Text;
using System.Text.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "your_api_key");

// Create a temporary mailbox (uses default project)
var payload = new { };
// Or specify project: var payload = new { projectName = "MyProject" };

var content = new StringContent(
    JsonSerializer.Serialize(payload),
    Encoding.UTF8,
    "application/json");

var response = await client.PostAsync(
    "https://api.foundermail.mx/mailboxes", content);
var mailbox = await response.Content.ReadFromJsonAsync<dynamic>();

Console.WriteLine($"Email: {mailbox.key}@foundermail.mx");

using FounderMail.Client.Api;
using FounderMail.Client.Model;

// Inject IMailboxesApi from DI container
var mailboxesApi = serviceProvider.GetRequiredService<IMailboxesApi>();

// Create a temporary mailbox (uses default project)
var mailboxCreateModel = new MailboxCreateModel();
// Or specify project: mailboxCreateModel.ProjectName = "MyProject";

var response = await mailboxesApi.CreateMailboxAsync(mailboxCreateModel);

if (response.IsOk)
{
    var mailbox = response.Ok();
    Console.WriteLine($"Email: {mailbox.Key}@foundermail.mx");
    Console.WriteLine($"Password: {mailbox.Password}");
}

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

// Create empty payload (uses default project)
payload := map[string]string{}
// Or specify project: payload := map[string]string{"projectName": "MyProject"}
jsonData, _ := json.Marshal(payload)

req, _ := http.NewRequest("POST",
    "https://api.foundermail.mx/mailboxes",
    bytes.NewBuffer(jsonData))
req.Header.Set("X-Api-Key", "your_api_key")
req.Header.Set("Content-Type", "application/json")

client := &http.Client{}
resp, _ := client.Do(req)

Step 3: Trigger Your Application

Now that you have a mailbox, you have two options to send emails that will be captured by FounderMail:

Option 1: Configure SMTP Server in Your Application

Configure your application's SMTP settings to use FounderMail's SMTP server with the credentials returned by the Create Mailbox API. Set the SMTP server to smtp.foundermail.mx:587, use the mailbox key as the username, and the password for authentication. Your application can then send emails to any recipient address, and all emails will be captured by FounderMail and delivered to your mailbox — nothing reaches the recipients you addressed. (A mailbox switched to relay mode behaves the opposite way; see below.)

Option 2: Send Directly to Mailbox Address

Alternatively, you can configure your application to send emails directly to the mailbox address ({key}@foundermail.mx). Any emails sent to this address will be automatically captured by FounderMail.

Sending for real: SMTP relay mode

Every persistent mailbox has an SMTP mode. Capture is the default and is what the two options above describe: submitted mail is stored in the mailbox and delivered to nobody, which is what a test suite wants. Relay makes the mailbox a real one — submitted mail leaves for its actual recipients, from the mailbox's own address, DKIM-signed for its domain.

Switch a mailbox with Send mail for real on its dashboard page. With relay on, a normal mail client can read the mailbox over IMAP and send from it over SMTP, so replies go out as the address they were sent to — no Gmail send-as, no separate DMARC setup per domain. A mailbox on a custom domain needs sending enabled for that domain first, so its DKIM records are published and verified.

Relayed mail counts against your plan's monthly outbound allowance, and free plans are reply-only: a relayed message must answer one the mailbox received.

Pro tip: Add a small delay (100-500ms) after triggering your application to ensure the email has been delivered before checking for it.

import time
import smtplib
from email.mime.text import MIMEText

# Option 1: Configure your app's SMTP server with FounderMail credentials
# Configure your app to use smtp.foundermail.mx:587 with mailbox key/password
# All emails sent by your app will be captured by FounderMail
smtp_server = "smtp.foundermail.mx"
smtp_port = 587
username = mailbox['key']  # Use key as username
password = mailbox['password']  # Use returned password

# Your app can now send emails normally - they'll all be captured
with smtplib.SMTP(smtp_server, smtp_port) as server:
    server.starttls()
    server.login(username, password)
    # Send to any recipient - all emails are captured by FounderMail
    server.sendmail(username, "any-recipient@example.com", "Test email body")

# Option 2: Send directly to the mailbox address
# Configure your app to send emails to key@foundermail.mx
test_email = f"{mailbox['key']}@foundermail.mx"
your_app.register_user(
    email=test_email,
    name="John Doe")

# Wait for email delivery
time.sleep(0.3)  # 300ms

import time
import smtplib
from email.mime.text import MIMEText

# Use mailbox from SDK response

# Option 1: Configure your app's SMTP server with FounderMail credentials
# Configure your app to use smtp.foundermail.mx:587 with mailbox key/password
# All emails sent by your app will be captured by FounderMail
smtp_server = "smtp.foundermail.mx"
smtp_port = 587
username = mailbox.key  # Use key as username
password = mailbox.password  # Use returned password

# Your app can now send emails normally - they'll all be captured
with smtplib.SMTP(smtp_server, smtp_port) as server:
    server.starttls()
    server.login(username, password)
    # Send to any recipient - all emails are captured by FounderMail
    server.sendmail(username, "any-recipient@example.com", "Test email body")

# Option 2: Send directly to the mailbox address
# Configure your app to send emails to key@foundermail.mx
test_email = f"{mailbox.key}@foundermail.mx"
your_app.register_user(
    email=test_email,
    name="John Doe")

# Wait for email delivery
time.sleep(0.3)  # 300ms

const nodemailer = require('nodemailer');

// Option 1: Configure your app's SMTP server with FounderMail credentials
// Configure your app to use smtp.foundermail.mx:587 with mailbox key/password
// All emails sent by your app will be captured by FounderMail
const transporter = nodemailer.createTransport({
    host: 'smtp.foundermail.mx',
    port: 587,
    secure: false,
    auth: {
        user: mailbox.key,  // Use key as username
        pass: mailbox.password  // Use returned password
    }
});

// Your app can now send emails normally - they'll all be captured
// Send to any recipient - all emails are captured by FounderMail
await transporter.sendMail({
    from: mailbox.key,
    to: 'any-recipient@example.com',
    subject: 'Test Email',
    text: 'Test email body'
});

// Option 2: Send directly to the mailbox address
// Configure your app to send emails to key@foundermail.mx
const testEmail = `${mailbox.key}@foundermail.mx`;
await yourApp.registerUser({
    email: testEmail,
    name: 'John Doe'
});

// Wait for email delivery
await new Promise(r => setTimeout(r, 300)); // 300ms

const nodemailer = require('nodemailer');

// Use mailbox from SDK response
const mailbox = response.data;

// Option 1: Configure your app's SMTP server with FounderMail credentials
// Configure your app to use smtp.foundermail.mx:587 with mailbox key/password
// All emails sent by your app will be captured by FounderMail
const transporter = nodemailer.createTransport({
    host: 'smtp.foundermail.mx',
    port: 587,
    secure: false,
    auth: {
        user: mailbox.key,  // Use key as username
        pass: mailbox.password  // Use returned password
    }
});

// Your app can now send emails normally - they'll all be captured
// Send to any recipient - all emails are captured by FounderMail
await transporter.sendMail({
    from: mailbox.key,
    to: 'any-recipient@example.com',
    subject: 'Test Email',
    text: 'Test email body'
});

// Option 2: Send directly to the mailbox address
// Configure your app to send emails to key@foundermail.mx
const testEmail = `${mailbox.key}@foundermail.mx`;
await yourApp.registerUser({
    email: testEmail,
    name: 'John Doe'
});

// Wait for email delivery
await new Promise(r => setTimeout(r, 300)); // 300ms

using System.Net.Mail;

// Option 1: Configure your app's SMTP server with FounderMail credentials
// Configure your app to use smtp.foundermail.mx:587 with mailbox key/password
// All emails sent by your app will be captured by FounderMail
using var smtpClient = new SmtpClient("smtp.foundermail.mx", 587)
{
    EnableSsl = true,
    Credentials = new System.Net.NetworkCredential(
        mailbox.key,  // Use key as username
        mailbox.password  // Use returned password
    )
};

// Your app can now send emails normally - they'll all be captured
// Send to any recipient - all emails are captured by FounderMail
var mailMessage = new MailMessage(mailbox.key, "any-recipient@example.com")
{
    Subject = "Test Email",
    Body = "Test email body"
};
await smtpClient.SendMailAsync(mailMessage);

// Option 2: Send directly to the mailbox address
// Configure your app to send emails to key@foundermail.mx
var testEmail = $"{mailbox.key}@foundermail.mx";
await yourApp.RegisterUserAsync(
    email: testEmail,
    name: "John Doe");

// Wait for email delivery
await Task.Delay(300); // 300ms

using System.Net.Mail;

// Use mailbox from SDK response
var mailbox = response.Ok();

// Option 1: Configure your app's SMTP server with FounderMail credentials
// Configure your app to use smtp.foundermail.mx:587 with mailbox key/password
// All emails sent by your app will be captured by FounderMail
using var smtpClient = new SmtpClient("smtp.foundermail.mx", 587)
{
    EnableSsl = true,
    Credentials = new System.Net.NetworkCredential(
        mailbox.Key,  // Use key as username
        mailbox.Password  // Use returned password
    )
};

// Your app can now send emails normally - they'll all be captured
// Send to any recipient - all emails are captured by FounderMail
var mailMessage = new MailMessage(mailbox.Key, "any-recipient@example.com")
{
    Subject = "Test Email",
    Body = "Test email body"
};
await smtpClient.SendMailAsync(mailMessage);

// Option 2: Send directly to the mailbox address
// Configure your app to send emails to key@foundermail.mx
var testEmail = $"{mailbox.Key}@foundermail.mx";
await yourApp.RegisterUserAsync(
    email: testEmail,
    name: "John Doe");

// Wait for email delivery
await Task.Delay(300); // 300ms

import "time"
import "net/smtp"

// Option 1: Configure your app's SMTP server with FounderMail credentials
// Configure your app to use smtp.foundermail.mx:587 with mailbox key/password
// All emails sent by your app will be captured by FounderMail
smtpServer := "smtp.foundermail.mx:587"
auth := smtp.PlainAuth("", mailbox.Key, mailbox.Password, "smtp.foundermail.mx")

// Your app can now send emails normally - they'll all be captured
// Send to any recipient - all emails are captured by FounderMail
msg := []byte("To: any-recipient@example.com\r\n" +
    "Subject: Test Email\r\n" +
    "\r\n" +
    "Test email body\r\n")
err := smtp.SendMail(smtpServer, auth, mailbox.Key, []string{"any-recipient@example.com"}, msg)

// Option 2: Send directly to the mailbox address
// Configure your app to send emails to key@foundermail.mx
testEmail := fmt.Sprintf("%s@foundermail.mx", mailbox.Key)
yourApp.RegisterUser(
    email: testEmail,
    name: "John Doe")

// Wait for email delivery
time.Sleep(300 * time.Millisecond)

Step 4: Verify the Email

Retrieve and verify the email from your mailbox. You can check the subject, body, sender, and any other email properties your test requires.

Use /single when you expect exactly one email, or /last to get the most recent email.

# Get the single message (fails if 0 or >1 messages)
response = requests.get(
    f"https://api.foundermail.mx/messages/{mailbox['key']}/single",
    headers=headers)

message = response.json()

# Verify email content
assert "Welcome" in message['subject']
assert "John Doe" in message['body']
assert message['from'][0] == "noreply@yourapp.com"

print("✓ Email verification passed!"

from foundermail_client.api.messages_api import MessagesApi

# Get the single message (fails if 0 or >1 messages)
message = messages_api.get_single_message(key=mailbox.key)

# Verify email content
assert "Welcome" in message.subject
assert "John Doe" in message.body
assert message.var_from and message.var_from[0] == "noreply@yourapp.com"

print("✓ Email verification passed!"

// Get the single message (fails if 0 or >1 messages)
const response = await fetch(
    `https://api.foundermail.mx/messages/${mailbox.key}/single`,
    { headers });

const message = await response.json();

// Verify email content
expect(message.subject).toContain('Welcome');
expect(message.body).toContain('John Doe');
expect(message.from[0]).toBe('noreply@yourapp.com');

console.log('✓ Email verification passed!');

import { MessagesApi } from '@founder-mail/client-api';

// Get the single message (fails if 0 or >1 messages)
const response = await messagesApi.getSingleMessage(mailbox.key);
const message = response.data;

// Verify email content
expect(message.subject).toContain('Welcome');
expect(message.body).toContain('John Doe');
expect(message.from && message.from[0]).toBe('noreply@yourapp.com');

console.log('✓ Email verification passed!');

// Get the single message (fails if 0 or >1 messages)
var response = await client.GetAsync(
    $"https://api.foundermail.mx/messages/{mailbox.key}/single");

var message = await response
    .Content.ReadFromJsonAsync<dynamic>();

// Verify email content
Assert.Contains("Welcome", message.subject.ToString());
Assert.Contains("John Doe", message.body.ToString());
Assert.Equal("noreply@yourapp.com", message.from[0].ToString());

Console.WriteLine("✓ Email verification passed!");

using FounderMail.Client.Api;

// Inject IMessagesApi from DI container
var messagesApi = serviceProvider.GetRequiredService<IMessagesApi>();

// Get the single message (fails if 0 or >1 messages)
var response = await messagesApi.GetSingleMessageAsync(mailbox.Key);

if (response.IsOk)
{
    var message = response.Ok();

    // Verify email content
    Assert.Contains("Welcome", message.Subject);
    Assert.Contains("John Doe", message.Body);
    Assert.NotNull(message.From);
    Assert.Equal("noreply@yourapp.com", message.From![0]);

    Console.WriteLine("✓ Email verification passed!");
}

// Get the single message (fails if 0 or >1 messages)
url := fmt.Sprintf(
    "https://api.foundermail.mx/messages/%s/single",
    mailbox.Key)

req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("X-Api-Key", apiKey)

resp, _ := client.Do(req)
var message Message
json.NewDecoder(resp.Body).Decode(&message)

// Verify email content
assert.Contains(t, message.Subject, "Welcome")
assert.Contains(t, message.Body, "John Doe"