Skip to main content
Lettermint provides special test addresses that simulate real-world delivery scenarios (bounces, complaints, and successful deliveries) without sending actual emails. Use them to verify your integration handles all outcomes correctly.

​
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 @testing.lettermint.co addresses are:
  • Excluded from billing: They don’t count toward your monthly email quota
  • Excluded from statistics: They won’t skew 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:
AddressSimulated EventWebhook Event
ok@testing.lettermint.coSuccessful deliverymessage.delivered
softbounce@testing.lettermint.coSoft bounce (mailbox full)message.soft_bounced
hardbounce@testing.lettermint.coHard bounce (user unknown)message.hard_bounced
spamcomplaint@testing.lettermint.coDelivery + spam complaintmessage.delivered → message.spam_complaint
dsn@testing.lettermint.coOut-of-band DSN bouncemessage.hard_bounced
The local part (before @) determines behavior. You can use any local part ending in @testing.lettermint.co. For example, user+tag@testing.lettermint.co also works.

​
Sending test emails

import { Lettermint } from "lettermint";

const lettermint = new Lettermint({
  apiToken: process.env.LETTERMINT_API_TOKEN
});

// Test a soft bounce scenario
const response = await lettermint.email
  .from("you@yourdomain.com")
  .to("softbounce@testing.lettermint.co")
  .subject("Test soft bounce")
  .text("This will simulate a soft bounce.")
  .send();

console.log(`Test email queued: ${response.message_id}`);
// Later: webhook fires with message.soft_bounced
Install the SDK first: npm install lettermint (Node.js), composer require lettermint/lettermint-php (PHP), or pip install lettermint (Python).

​
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

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

​
Example webhook payload

When sending to softbounce@testing.lettermint.co, you’ll receive: 
{
  "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@testing.lettermint.co",
    "response": {
      "status_code": 452,
      "enhanced_status_code": "4.2.2",
      "content": "Mailbox full"
    },
    "metadata": {},
    "tag": null
  }
}
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: 
// In your test suite
describe("Email notifications", () => {
  it("handles bounce events gracefully", async () => {
    // Send to test address
    const response = await lettermint.email
      .from("app@yourdomain.com")
      .to("hardbounce@testing.lettermint.co")
      .subject("Test")
      .text("Test")
      .send();

    // 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 webhook is enabled: Disabled webhooks don’t 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 API token: Ensure your token is valid and has send permissions
  • Check “from” address: The sender domain must be verified in your project

​
Test address not recognized

  • Use exact domain: The domain must be exactly testing.lettermint.co (case-insensitive)
  • Check for typos: Common mistakes: test.lettermint.co (wrong), testing.lettermint.com (wrong TLD)

​
Next steps

Set up webhooks

Receive delivery events in real-time

Webhook events

See all event types and payloads

Verify domains

Configure DNS for sending

API Reference

Complete endpoint documentation