Get Email Details

GET

api

mail

{id}

GET https://inbound.new/api/v2/mail/{id}

{
  "id": "email_123",
  "emailId": "ses_456",
  "messageId": "<message@example.com>",
  "subject": "Important Update",
  "from": "sender@example.com",
  "fromName": "John Doe",
  "to": "recipient@yourdomain.com",
  "cc": "cc@example.com",
  "bcc": null,
  "replyTo": "reply@example.com",
  "recipient": "recipient@yourdomain.com",
  "receivedAt": "2024-01-15T10:30:00Z",
  "isRead": true,
  "readAt": "2024-01-15T12:00:00Z",
  "content": {
    "textBody": "This is the plain text version of the email...",
    "htmlBody": "<html><body><p>This is the HTML version...</p></body></html>",
    "rawContent": "Received: from mail.example.com...",
    "attachments": [
      {
        "filename": "document.pdf",
        "contentType": "application/pdf",
        "size": 102400,
        "contentId": "att_123"
      }
    ],
    "headers": {
      "received": ["from mail.example.com..."],
      "x-mailer": "Example Mailer 1.0",
      "content-type": "multipart/mixed"
    }
  },
  "addresses": {
    "from": {
      "text": "John Doe <sender@example.com>",
      "addresses": [
        {
          "address": "sender@example.com",
          "name": "John Doe"
        }
      ]
    },
    "to": {
      "text": "recipient@yourdomain.com",
      "addresses": [
        {
          "address": "recipient@yourdomain.com",
          "name": null
        }
      ]
    },
    "cc": {
      "text": "cc@example.com",
      "addresses": [
        {
          "address": "cc@example.com",
          "name": null
        }
      ]
    },
    "bcc": null,
    "replyTo": {
      "text": "reply@example.com",
      "addresses": [
        {
          "address": "reply@example.com",
          "name": null
        }
      ]
    }
  },
  "metadata": {
    "inReplyTo": "<previous@example.com>",
    "references": [
      "<ref1@example.com>",
      "<ref2@example.com>"
    ],
    "priority": "normal",
    "parseSuccess": true,
    "parseError": null,
    "hasAttachments": true,
    "attachmentCount": 1,
    "hasTextBody": true,
    "hasHtmlBody": true
  },
  "security": {
    "spf": "PASS",
    "dkim": "PASS",
    "dmarc": "PASS",
    "spam": "PASS",
    "virus": "PASS"
  },
  "processing": {
    "processingTimeMs": 245,
    "timestamp": "2024-01-15T10:30:00Z",
    "receiptTimestamp": "2024-01-15T10:30:00Z",
    "actionType": "SNS",
    "s3Info": {
      "bucketName": "inbound-emails",
      "objectKey": "emails/2024/01/15/email_123.eml",
      "contentFetched": true,
      "contentSize": 51200,
      "error": null
    },
    "commonHeaders": {
      "from": ["sender@example.com"],
      "to": ["recipient@yourdomain.com"],
      "messageId": "<message@example.com>",
      "subject": "Important Update"
    }
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T12:00:00Z"
}

GET https://inbound.new/api/v2/mail/{id}

Authentication

Authorization

string

required

Bearer token for API authentication. Format: Bearer YOUR_API_KEY

Path Parameters

string

required

Unique identifier for the email record. Must be a valid email ID.

Request Examples

import { InboundEmailClient } from '@inboundemail/sdk'

const inbound = new InboundEmailClient('your_api_key_here')

// Get email details
const { data: email, error } = await inbound.mail.get('email_123')

if (error) {
  console.error('Error:', error)
} else {
  console.log('Email subject:', email.subject)
  console.log('From:', email.from)
  console.log('Content:', email.content)
}

Response

{
  "id": "email_123",
  "emailId": "ses_456",
  "messageId": "<message@example.com>",
  "subject": "Important Update",
  "from": "sender@example.com",
  "fromName": "John Doe",
  "to": "recipient@yourdomain.com",
  "cc": "cc@example.com",
  "bcc": null,
  "replyTo": "reply@example.com",
  "recipient": "recipient@yourdomain.com",
  "receivedAt": "2024-01-15T10:30:00Z",
  "isRead": true,
  "readAt": "2024-01-15T12:00:00Z",
  "content": {
    "textBody": "This is the plain text version of the email...",
    "htmlBody": "<html><body><p>This is the HTML version...</p></body></html>",
    "rawContent": "Received: from mail.example.com...",
    "attachments": [
      {
        "filename": "document.pdf",
        "contentType": "application/pdf",
        "size": 102400,
        "contentId": "att_123"
      }
    ],
    "headers": {
      "received": ["from mail.example.com..."],
      "x-mailer": "Example Mailer 1.0",
      "content-type": "multipart/mixed"
    }
  },
  "addresses": {
    "from": {
      "text": "John Doe <sender@example.com>",
      "addresses": [
        {
          "address": "sender@example.com",
          "name": "John Doe"
        }
      ]
    },
    "to": {
      "text": "recipient@yourdomain.com",
      "addresses": [
        {
          "address": "recipient@yourdomain.com",
          "name": null
        }
      ]
    },
    "cc": {
      "text": "cc@example.com",
      "addresses": [
        {
          "address": "cc@example.com",
          "name": null
        }
      ]
    },
    "bcc": null,
    "replyTo": {
      "text": "reply@example.com",
      "addresses": [
        {
          "address": "reply@example.com",
          "name": null
        }
      ]
    }
  },
  "metadata": {
    "inReplyTo": "<previous@example.com>",
    "references": [
      "<ref1@example.com>",
      "<ref2@example.com>"
    ],
    "priority": "normal",
    "parseSuccess": true,
    "parseError": null,
    "hasAttachments": true,
    "attachmentCount": 1,
    "hasTextBody": true,
    "hasHtmlBody": true
  },
  "security": {
    "spf": "PASS",
    "dkim": "PASS",
    "dmarc": "PASS",
    "spam": "PASS",
    "virus": "PASS"
  },
  "processing": {
    "processingTimeMs": 245,
    "timestamp": "2024-01-15T10:30:00Z",
    "receiptTimestamp": "2024-01-15T10:30:00Z",
    "actionType": "SNS",
    "s3Info": {
      "bucketName": "inbound-emails",
      "objectKey": "emails/2024/01/15/email_123.eml",
      "contentFetched": true,
      "contentSize": 51200,
      "error": null
    },
    "commonHeaders": {
      "from": ["sender@example.com"],
      "to": ["recipient@yourdomain.com"],
      "messageId": "<message@example.com>",
      "subject": "Important Update"
    }
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T12:00:00Z"
}

Response Fields

string

Unique identifier for the email record.

emailId

string

Original email ID from the email service.

messageId

string

Message ID from the email headers.

subject

string

Email subject line.

from

string

Sender’s email address.

fromName

string | null

Sender’s display name, if available.

string

Primary recipient’s email address.

string | null

Carbon copy recipients, if any.

bcc

string | null

Blind carbon copy recipients, if any.

replyTo

string | null

Reply-to email address, if different from sender.

recipient

string

Primary recipient’s email address (same as ‘to’ for backward compatibility).

receivedAt

string

ISO 8601 timestamp when the email was received.

isRead

boolean

Whether the email has been read. Automatically set to true when fetched via this endpoint.

readAt

string | null

ISO 8601 timestamp when the email was read. Set automatically when fetching via this endpoint.

content

object

Complete email content and attachments.

Show Content Properties

textBody

string | null

Plain text version of the email content.

htmlBody

string | null

HTML version of the email content (sanitized).

rawContent

string | null

Raw email content including headers.

attachments

array

Array of attachment objects.

Show Attachment Properties

filename

string

Original filename of the attachment.

contentType

string

MIME type of the attachment.

size

integer

Size of the attachment in bytes.

contentId

string

Unique identifier for the attachment.

headers

object

Email headers as key-value pairs.

addresses

object

Parsed email addresses with names.

Show Address Properties

from

object

Sender address information.

Show Address Format

text

string

Full address string with name.

addresses

array

Array of parsed address objects.

Show Address Object

address

string

Email address.

name

string | null

Display name, if available.

object

Primary recipient address information.

object | null

Carbon copy recipients, if any.

bcc

object | null

Blind carbon copy recipients, if any.

replyTo

object | null

Reply-to address information, if different from sender.

metadata

object

Email metadata and parsing information.

Show Metadata Properties

inReplyTo

string | null

Message ID this email is replying to.

references

array

Array of referenced message IDs.

priority

string | null

Email priority level.

parseSuccess

boolean

Whether the email was successfully parsed.

parseError

string | null

Error message if parsing failed.

hasAttachments

boolean

Whether the email contains attachments.

attachmentCount

integer

Number of attachments in the email.

hasTextBody

boolean

Whether the email has a text body.

hasHtmlBody

boolean

Whether the email has an HTML body.

security

object

Email security verification results.

Show Security Properties

spf

string

SPF verification result. Values: PASS, FAIL, NEUTRAL, SOFTFAIL, TEMPERROR, PERMERROR, UNKNOWN.

dkim

string

DKIM verification result. Values: PASS, FAIL, UNKNOWN.

dmarc

string

DMARC verification result. Values: PASS, FAIL, UNKNOWN.

spam

string

Spam verification result. Values: PASS, FAIL, UNKNOWN.

virus

string

Virus verification result. Values: PASS, FAIL, UNKNOWN.

processing

object

Email processing and storage information.

Show Processing Properties

processingTimeMs

integer | null

Time taken to process the email in milliseconds.

timestamp

string | null

ISO 8601 timestamp when processing started.

receiptTimestamp

string | null

ISO 8601 timestamp when email was received by the service.

actionType

string | null

Type of action taken (e.g., SNS, S3).

s3Info

object

S3 storage information for the email.

Show S3 Info Properties

bucketName

string | null

S3 bucket name where the email is stored.

objectKey

string | null

S3 object key for the email file.

contentFetched

boolean | null

Whether the email content was successfully fetched from S3.

contentSize

integer | null

Size of the email content in bytes.

error

string | null

Error message if S3 fetch failed.

commonHeaders

object | null

Common headers parsed from the email during processing.

createdAt

string

ISO 8601 timestamp when the email record was created.

updatedAt

string

ISO 8601 timestamp when the email record was last updated.

Error Responses

400 Bad Request - Invalid ID

401 Unauthorized

404 Not Found

500 Internal Server Error

Usage Examples

Basic Email Retrieval

import { InboundEmailClient } from '@inboundemail/sdk'

const inbound = new InboundEmailClient('your_api_key_here')

const getEmailDetails = async (emailId) => {
  const { data: email, error } = await inbound.mail.get(emailId)
  
  if (error) {
    throw new Error(`Failed to get email: ${error}`)
  }
  
  return email
}

// Usage
const email = await getEmailDetails('email_123')
console.log(email.subject)
console.log(email.content.textBody)

Processing Attachments

const processEmailAttachments = async (emailId) => {
  const { data: email, error } = await inbound.mail.get(emailId)
  
  if (error) {
    console.error('Error:', error)
    return
  }
  
  if (email.metadata.hasAttachments) {
    email.content.attachments.forEach(attachment => {
      console.log(`Attachment: ${attachment.filename}`)
      console.log(`Type: ${attachment.contentType}`)
      console.log(`Size: ${attachment.size} bytes`)
    })
  }
}

Security Verification Check

const checkEmailSecurity = async (emailId) => {
  const { data: email, error } = await inbound.mail.get(emailId)
  
  if (error) {
    return { emailId, error }
  }
  
  const securityPassed = 
    email.security.spf === 'PASS' &&
    email.security.dkim === 'PASS' &&
    email.security.dmarc === 'PASS' &&
    email.security.spam === 'PASS' &&
    email.security.virus === 'PASS'
  
  return {
    emailId,
    securityPassed,
    details: email.security
  }
}

When you fetch an email using this endpoint, it’s automatically marked as read and the readAt timestamp is updated.

Use the metadata.parseSuccess field to check if the email was parsed correctly. If parseSuccess is false, check the parseError field for details.

Verified: This endpoint documentation has been verified against the actual API implementation in /inbound-app/app/api/v2/mail/[id]/route.ts and /inbound-app/functions/mail/primary.ts. All endpoint paths, request/response structures, error codes, and examples are accurate and up-to-date.

1.0 - ✅

List EmailsRetrieve all emails with filtering, pagination, and search capabilities

GET https://inbound.new/api/v2/mail/{id}

{
  "id": "email_123",
  "emailId": "ses_456",
  "messageId": "<message@example.com>",
  "subject": "Important Update",
  "from": "sender@example.com",
  "fromName": "John Doe",
  "to": "recipient@yourdomain.com",
  "cc": "cc@example.com",
  "bcc": null,
  "replyTo": "reply@example.com",
  "recipient": "recipient@yourdomain.com",
  "receivedAt": "2024-01-15T10:30:00Z",
  "isRead": true,
  "readAt": "2024-01-15T12:00:00Z",
  "content": {
    "textBody": "This is the plain text version of the email...",
    "htmlBody": "<html><body><p>This is the HTML version...</p></body></html>",
    "rawContent": "Received: from mail.example.com...",
    "attachments": [
      {
        "filename": "document.pdf",
        "contentType": "application/pdf",
        "size": 102400,
        "contentId": "att_123"
      }
    ],
    "headers": {
      "received": ["from mail.example.com..."],
      "x-mailer": "Example Mailer 1.0",
      "content-type": "multipart/mixed"
    }
  },
  "addresses": {
    "from": {
      "text": "John Doe <sender@example.com>",
      "addresses": [
        {
          "address": "sender@example.com",
          "name": "John Doe"
        }
      ]
    },
    "to": {
      "text": "recipient@yourdomain.com",
      "addresses": [
        {
          "address": "recipient@yourdomain.com",
          "name": null
        }
      ]
    },
    "cc": {
      "text": "cc@example.com",
      "addresses": [
        {
          "address": "cc@example.com",
          "name": null
        }
      ]
    },
    "bcc": null,
    "replyTo": {
      "text": "reply@example.com",
      "addresses": [
        {
          "address": "reply@example.com",
          "name": null
        }
      ]
    }
  },
  "metadata": {
    "inReplyTo": "<previous@example.com>",
    "references": [
      "<ref1@example.com>",
      "<ref2@example.com>"
    ],
    "priority": "normal",
    "parseSuccess": true,
    "parseError": null,
    "hasAttachments": true,
    "attachmentCount": 1,
    "hasTextBody": true,
    "hasHtmlBody": true
  },
  "security": {
    "spf": "PASS",
    "dkim": "PASS",
    "dmarc": "PASS",
    "spam": "PASS",
    "virus": "PASS"
  },
  "processing": {
    "processingTimeMs": 245,
    "timestamp": "2024-01-15T10:30:00Z",
    "receiptTimestamp": "2024-01-15T10:30:00Z",
    "actionType": "SNS",
    "s3Info": {
      "bucketName": "inbound-emails",
      "objectKey": "emails/2024/01/15/email_123.eml",
      "contentFetched": true,
      "contentSize": 51200,
      "error": null
    },
    "commonHeaders": {
      "from": ["sender@example.com"],
      "to": ["recipient@yourdomain.com"],
      "messageId": "<message@example.com>",
      "subject": "Important Update"
    }
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T12:00:00Z"
}

Quickstart

Sending Emails

Endpoints

Email Addresses

Domains

Inbound Emails

Get Email Details

Authentication

Path Parameters

Request Examples

Response

Response Fields

Error Responses

Usage Examples

Basic Email Retrieval

Processing Attachments

Security Verification Check

Quickstart

Sending Emails

Endpoints

Email Addresses

Domains

Inbound Emails

​Authentication

​Path Parameters

​Request Examples

​Response

​Response Fields

​Error Responses

​Usage Examples

​Basic Email Retrieval

​Processing Attachments

​Security Verification Check

Authentication

Path Parameters

Request Examples

Response

Response Fields

Error Responses

Usage Examples

Basic Email Retrieval

Processing Attachments

Security Verification Check