Send email

Test emails

Use Lettermint test addresses to simulate delivery, bounce, and complaint outcomes without sending email to a real recipient.

Use Sandbox mode when you need a project-wide test boundary, an unverified From domain, arbitrary recipient addresses, or more simulated results. Use the addresses on this page for a one-off test in a Live project.

Why use test addresses?

Sending test emails to real mailboxes (including your own) can harm your sender reputation. Repeated bounces, spam complaints, or test content flagged as suspicious may cause mailbox providers to throttle or block your domain. Test addresses let you simulate every scenario without affecting your deliverability metrics.

Test emails sent to @lettermint.dev addresses are:

Excluded from billing: They do not count toward your monthly email quota
Excluded from statistics: They do not change your bounce or complaint rates
Processed instantly: Events are generated within seconds

Test addresses

Send to any of these addresses to trigger specific delivery events:

Address	Simulated Event	Webhook Event
`ok@lettermint.dev`	Successful delivery	`message.delivered`
`softbounce@lettermint.dev`	Soft bounce (mailbox full)	`message.soft_bounced`
`hardbounce@lettermint.dev`	Hard bounce (user unknown)	`message.hard_bounced`
`spamcomplaint@lettermint.dev`	Delivery + spam complaint	`message.delivered` → `message.spam_complaint`
`dsn@lettermint.dev`	Out-of-band DSN bounce	`message.hard_bounced`

Use only the five test addresses in the table for a Live project. Other local parts are rejected.

The same five local parts remain available on @testing.lettermint.co for compatibility. Existing integrations do not need to change immediately.

Test addresses in a Sandbox project

Inside a Sandbox project, the same test addresses select a per-recipient result that overrides the message's sandbox_result. Sandbox accepts more local parts than Live: the five names above, plus every Sandbox result name, with or without underscores (for example hard_bounced or hardbounced), and a +label such as hardbounce+signup@lettermint.dev.

See Per-recipient results with test addresses for the full local part table and precedence rules.

Sending test emails

import { Lettermint } from "lettermint";

const lettermint = new Lettermint({
  sendingToken: process.env.LETTERMINT_PROJECT_TOKEN!,
});

// Test a soft bounce scenario
const response = await lettermint.emails.send({
  from: "you@yourdomain.com",
  to: ["softbounce@lettermint.dev"],
  subject: "Test soft bounce",
  text: "This will simulate a soft bounce.",
});

console.log(`Test email queued: ${response.message_id}`);
// Later: webhook fires with message.soft_bounced

Install the package for your language before you run an SDK example. See Integrations for package links and requirements.

Testing with webhooks

Test addresses are most useful when combined with webhooks. Set up a webhook to receive events, then send test emails to verify your handler processes each event type correctly.

Example: verify bounce handling

Create a webhook subscribed to message.hard_bounced events
Send to hardbounce@lettermint.dev
Confirm your webhook receives the event and your application handles it (e.g., marks the address as undeliverable)

Example webhook payload

When you send to softbounce@lettermint.dev, you receive:

Code
{
  "id": "9b0c4a4e-4e29-4d8b-8b3a-3f0f3e6d2f9b",
  "event": "message.soft_bounced",
  "timestamp": "2025-01-31T14:30:00.000Z",
  "data": {
    "message_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "subject": "Test soft bounce",
    "recipient": "softbounce@lettermint.dev",
    "response": {
      "status_code": 452,
      "enhanced_status_code": "4.2.2",
      "content": "Mailbox full"
    },
    "metadata": {},
    "tag": null,
    "tags": []
  }
}

See Webhook events for the complete payload reference.

Common testing workflows

Integration testing

Use test addresses in your CI/CD pipeline to verify email sending works without sending real emails:

Code
// In your test suite
describe("Email notifications", () => {
  it("handles bounce events gracefully", async () => {
    // Send to test address
    const response = await lettermint.emails.send({
      from: "app@yourdomain.com",
      to: ["hardbounce@lettermint.dev"],
      subject: "Test",
      text: "Test",
    });

    // Verify your webhook handler marks the address as bounced
    // (depends on your application logic)
  });
});

Manual testing

When developing locally, use a tunnel like ngrok to expose your webhook endpoint, then send test emails to verify the full flow.

Troubleshooting

No webhook received

Check that the webhook is enabled: Disabled webhooks do not send events
Verify event subscription: Ensure the webhook subscribes to the relevant event type (e.g., message.soft_bounced)
Allow processing time: Test events typically arrive within 5-10 seconds
Check webhook logs: View recent deliveries in Dashboard → Route → Webhooks → [Your Webhook]

API returns an error

Verify Project API token: Ensure your token is valid and can send for the project
Check "from" address: The sender domain must be verified in your project

Test address not recognized

Use an exact domain: Use lettermint.dev or the compatible testing.lettermint.co domain (case-insensitive)
Check for typos: Common mistakes: test.lettermint.co (wrong), lettermint.devm (wrong TLD)