Receiving Emails

Read incoming messages from your LobsterMail inbox — poll, filter, and parse email content.

Last updated 2026-02-23

List messages#

Fetch all messages in an inbox:

const messages = await lobster.inbox.messages(inbox.id);

Each message object contains:

| Field | Type | Description | |-------|------|-------------| | id | string | Unique message identifier | | from | string | Sender email address | | to | string | Recipient address | | subject | string | Email subject line | | text | string | Plain text body | | html | string \| null | HTML body (if present) | | receivedAt | string | ISO 8601 timestamp | | read | boolean | Whether the message has been read | | attachments | Attachment[] | File attachments |

Filter by read status#

Fetch only unread messages:

const unread = await lobster.inbox.messages(inbox.id, {
  unread: true,
});

Read a single message#

const message = await lobster.inbox.message(inbox.id, messageId);

console.log(message.from);    // "alice@example.com"
console.log(message.subject); // "Re: Meeting tomorrow"
console.log(message.text);    // "Sounds good, see you at 3pm."

Handle attachments#

for (const attachment of message.attachments) {
  console.log(attachment.filename);  // "report.pdf"
  console.log(attachment.mimeType);  // "application/pdf"
  console.log(attachment.size);      // 142857 (bytes)

  // Download the attachment content
  const data = await lobster.inbox.downloadAttachment(
    inbox.id,
    message.id,
    attachment.id
  );
}

Mark messages as read#

await lobster.inbox.markRead(inbox.id, message.id);

Delete a message#

await lobster.inbox.delete(inbox.id, message.id);

What's next#