postmark to lobstermail migration guide

import { LobsterMail } from '@lobsterkit/lobstermail';

const lm = await LobsterMail.create();
const inbox = await lm.createSmartInbox({ name: 'Notifications' });
console.log(inbox.address); // notifications@lobstermail.ai

No dashboard clicking. No manual setup. The SDK handles account creation and token storage on first run. If you want to understand why this pattern matters for AI-driven systems, we wrote about it in [agent self-signup: why the agent should create its own inbox](/blog/agent-self-signup-explained).

For teams migrating a traditional app, you can also grab your API token from the dashboard and set it as an environment variable. Both paths work.

## Domain verification and DNS changes

Postmark uses Sender Signatures and Verified Domains with DKIM and Return-Path records. LobsterMail also requires domain verification, but the record format is slightly different.

You'll need to add two DNS records:

1. A DKIM TXT record at `lobstermail._domainkey.yourdomain.com`
2. An SPF include: `include:spf.lobstermail.ai` in your existing SPF record

If you're currently sending through Postmark, your SPF record probably includes `include:spf.mtasv.net`. During the parallel running phase, keep both. After cutover, remove the Postmark include.

One thing people worry about: does changing email providers affect my sender reputation? The short answer is yes, partially. Your domain reputation travels with you (that's the whole point of DKIM), but your IP reputation doesn't. LobsterMail uses shared sending infrastructure with pre-warmed IPs, so most senders won't notice a dip. If you're sending high volume (over 50,000/month), talk to us about dedicated IP options and a warm-up schedule.

For more on protecting your reputation during and after migration, our guide on [email deliverability for ai agents](/blog/email-deliverability-ai-agents) covers the mechanics of SPF, DKIM, and warm-up in detail.

## Updating your API integration

This is where most of the actual work happens. Postmark's API uses endpoints like `POST /email` with a `ServerToken` header. LobsterMail uses a different SDK-first approach, but you can also hit the REST API directly if you prefer.

Here's a typical Postmark send call and its LobsterMail equivalent:

**Postmark:**

```typescript
await fetch('https://api.postmarkapp.com/email', {
  method: 'POST',
  headers: {
    'X-Postmark-Server-Token': 'your-token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    From: 'hello@yourdomain.com',
    To: 'recipient@example.com',
    Subject: 'Your receipt',
    HtmlBody: '<p>Thanks for your purchase.</p>',
  }),
});
**LobsterMail:**

```typescript
import { LobsterMail } from '@lobsterkit/lobstermail';

const lm = await LobsterMail.create();
const inbox = await lm.getInbox('hello@yourdomain.com');

await inbox.send({
  to: 'recipient@example.com',
  subject: 'Your receipt',
  html: '<p>Thanks for your purchase.</p>',
});

The field names are slightly different (`HtmlBody` becomes `html`, `From` is implicit from the inbox), but the mapping is direct. If you have a wrapper function around your Postmark calls, you can swap the implementation without changing your app's interface.

For SMTP users: LobsterMail provides SMTP credentials in the dashboard under your inbox settings. The format is `lm_sk_live_*` as the username with the same value as the password, against `smtp.lobstermail.ai` on port 587 with STARTTLS. Postmark uses a similar pattern with their Server Token as both username and password, so the swap is a config file change.

## Webhook migration

Postmark offers webhooks for bounces, spam complaints, deliveries, opens, and clicks. LobsterMail supports bounce, complaint, and delivery webhooks today. Open and click tracking is on the roadmap.

The payload structures differ. Here's a quick mapping of the key fields:

| Event | Postmark field | LobsterMail field |
|---|---|---|
| Bounce type | `Type` (e.g., "HardBounce") | `bounce_type` (e.g., "hard") |
| Bounce recipient | `Email` | `recipient` |
| Complaint recipient | `Email` | `recipient` |
| Delivery recipient | `Recipient` | `recipient` |
| Message ID | `MessageID` | `message_id` |
| Timestamp | `DeliveredAt` / `BouncedAt` | `timestamp` (ISO 8601) |

If you're processing Postmark webhook payloads in your app, you'll need to update your parsing logic. I'd recommend creating a thin adapter layer that normalizes both formats during the parallel running phase, then remove the Postmark adapter after cutover.

## Migrating suppression lists

This one catches people off guard. Postmark maintains a suppression list of hard bounces and spam complaints. If you migrate without bringing that list over, you'll send to addresses that already bounced or complained, which torches your reputation fast.

Export your suppressions from Postmark's dashboard (Activity > Bounces, filter by type). Then import them into LobsterMail through the API:

```typescript
const lm = await LobsterMail.create();
await lm.addSuppressions([
  'bounced-user@example.com',
  'complained-user@example.com',
]);