GET https://inbound.new/api/v2/mail Authentication Bearer token for API authentication. Format: Bearer YOUR_API_KEY
Query Parameters Maximum number of emails to return. Range: 1-100.
Number of emails to skip for pagination. Must be non-negative.
Search query to filter emails by subject, sender, or recipient.
Filter emails by processing status. Options: all, processed, failed
Filter emails by recipient domain. Use specific domain name or all for no filter.
Filter emails by time range. Options: 24h, 7d, 30d, 90d
Whether to include archived emails in the results. By default, archived emails are excluded.
Filter emails by a specific email address. Searches across to, from, cc, and bcc fields. Cannot be used with emailId.
Filter emails by a specific email ID to get all emails in a thread. Cannot be used with emailAddress.
Request Examples import { InboundEmailClient } from '@inboundemail/sdk' ; const inbound = new InboundEmailClient ( 'your_api_key_here' ); // Basic request const { data , error } = await inbound . mail . list (); // With filters const { data , error } = await inbound . mail . list ({ limit: 20 , status: 'processed' , domain: 'example.com' }); // With search const { data , error } = await inbound . mail . list ({ search: 'urgent' , timeRange: '7d' }); // Filter by email address const { data , error } = await inbound . mail . list ({ emailAddress: 'customer@example.com' , limit: 50 }); // Filter by email ID (thread) const { data , error } = await inbound . mail . list ({ emailId: 'ses_abc123' , includeArchived: true });
Response { "emails" : [ { "id" : "email_123" , "emailId" : "ses_456" , "messageId" : "<message@example.com>" , "subject" : "Important Update" , "from" : "sender@example.com" , "fromName" : "John Doe" , "recipient" : "hello@yourdomain.com" , "preview" : "This is a preview of the email content..." , "receivedAt" : "2024-01-15T10:30:00Z" , "isRead" : false , "readAt" : null , "isArchived" : false , "archivedAt" : null , "hasAttachments" : true , "attachmentCount" : 2 , "parseSuccess" : true , "parseError" : null , "createdAt" : "2024-01-15T10:30:00Z" } ], "pagination" : { "total" : 150 , "limit" : 50 , "offset" : 0 , "hasMore" : true }, "filters" : { "uniqueDomains" : [ "example.com" , "yourdomain.com" , "test.com" ] } } Response Fields Array of email objects matching the query criteria. Unique identifier for the email record.
Original email ID from the email service.
Message ID from the email headers.
Email subject line. Returns “No Subject” if empty.
Sender’s display name, if available.
Recipient’s email address.
First 200 characters of the email content (text or HTML stripped).
ISO 8601 timestamp when the email was received.
Whether the email has been read.
ISO 8601 timestamp when the email was read, if applicable.
Whether the email has been archived.
ISO 8601 timestamp when the email was archived, if applicable.
Whether the email contains attachments.
Number of attachments in the email.
Whether the email was successfully parsed.
Error message if parsing failed, null if successful.
ISO 8601 timestamp when the email record was created.
Pagination information for the current request. Show Pagination Properties
Total number of emails matching the query.
Maximum number of results returned in this request.
Number of results skipped for this request.
Whether there are more results available.
Available filter options based on your data. Array of unique recipient domains in your emails.
Error Responses
400 Bad Request - Invalid Limit
{ "error" : "Limit must be between 1 and 100" }
400 Bad Request - Invalid Offset
{ "error" : "Offset must be non-negative" }
400 Bad Request - Conflicting Filters
{ "error" : "Cannot filter by both emailAddress and emailId at the same time" }
{ "error" : "Invalid or missing API key" }
500 Internal Server Error
{ "error" : "Failed to fetch emails" } Usage Examples import { InboundEmailClient } from '@inboundemail/sdk' ; const inbound = new InboundEmailClient ( 'your_api_key_here' ); let allEmails = []; let offset = 0 ; const limit = 50 ; while ( true ) { const { data , error } = await inbound . mail . list ({ limit , offset }); if ( error ) { console . error ( 'Error fetching emails:' , error ); break ; } allEmails . push ( ... data . emails ); if ( ! data . pagination . hasMore ) break ; offset += limit ; } Search with Filters import { InboundEmailClient } from '@inboundemail/sdk' ; const inbound = new InboundEmailClient ( 'your_api_key_here' ); const searchEmails = async ( query , domain , timeRange ) => { const { data , error } = await inbound . mail . list ({ search: query , domain: domain , timeRange: timeRange , status: 'processed' }); if ( error ) { throw new Error ( error ); } return data ; }; Filter by Email Address import { InboundEmailClient } from '@inboundemail/sdk' ; const inbound = new InboundEmailClient ( 'your_api_key_here' ); const getEmailsForAddress = async ( emailAddress ) => { const { data , error } = await inbound . mail . list ({ emailAddress: emailAddress , includeArchived: true , limit: 100 }); if ( error ) { throw new Error ( error ); } return data ; }; // Get all emails for a customer const customerEmails = await getEmailsForAddress ( 'customer@example.com' ); console . log ( `Found ${ customerEmails . emails . length } emails for customer` ); Get Email Thread import { InboundEmailClient } from '@inboundemail/sdk' ; const inbound = new InboundEmailClient ( 'your_api_key_here' ); const getEmailThread = async ( emailId ) => { const { data , error } = await inbound . mail . list ({ emailId: emailId , includeArchived: true }); if ( error ) { throw new Error ( error ); } // Sort by date to see conversation flow const sortedEmails = data . emails . sort ( ( a , b ) => new Date ( a . receivedAt ) - new Date ( b . receivedAt ) ); return sortedEmails ; }; // Get all emails in a thread const threadEmails = await getEmailThread ( 'ses_abc123' ); console . log ( `Thread contains ${ threadEmails . length } emails` ); Use the uniqueDomains array from the response to populate domain filter dropdowns in your application.
The emailAddress and emailId parameters cannot be used together in the same request. Use emailAddress to find all emails involving a specific address, or use emailId to find all emails in a specific thread.
Documentation verified against API implementation /api/v2/mail - All parameters, response fields, and error handling match the actual endpoint behavior.
1.0 - ✅ 
