Skip to main content
Messages represent individual emails received on your domain. Each message belongs to a thread and contains sender information, recipients, subject, and a reference to its content (plain text, HTML, and raw MIME).

​
List messages

Retrieve a paginated list of received messages across all your inboxes. You can filter by domain or sender address. 
import { Nuntly } from '@nuntly/sdk';

const nuntly = new Nuntly({
  apiKey: process.env.NUNTLY_API_KEY,
});

// List all messages
const messages = await nuntly.messages.list();

// Filter by domain
const domainMessages = await nuntly.messages.list({
  domainId: 'your-domain-id',
});

// Filter by sender
const fromMessages = await nuntly.messages.list({
  from: 'sender@example.com',
});

​
Available filters

ParameterDescription
domainIdFilter messages by a specific domain.
fromFilter messages by sender address.
cursorCursor for pagination.
limitMaximum number of results to return (1-30, default 30).

​
Retrieve a message

Get the full details of a single message by its ID. The response includes inbox information showing which inbox the message was routed to. 
const message = await nuntly.messages.retrieve('imsg_01kabn43yqyxn2bx4ve84mczd3');

console.log('From:', message.data.from);
console.log('Subject:', message.data.subject);
console.log('Attachments:', message.data.attachmentCount);

​
Message fields

FieldDescription
idThe unique message identifier.
inboxIdThe inbox the message was routed to, or null for the default catch-all.
threadIdThe thread this message belongs to.
messageIdThe email Message-ID header.
fromThe sender in RFC 5322 format (e.g. Jane Doe <jane@example.com> or jane@example.com).
toThe recipient addresses.
ccThe CC addresses.
bccThe BCC addresses.
replyToThe Reply-To addresses.
subjectThe message subject line.
receivedAtThe timestamp when the message was received.
statusThe message status (received, sent, discarded, or failed).
attachmentCountThe number of attachments.
headersThe raw email headers as a key-value map. Included on single retrieval only.

​
Get message content

Retrieve presigned download URLs for the message body in different formats. Each content item includes the download URL, the uncompressed size in bytes, and when the URL expires. By default, only the HTML format is returned. Use the format parameter to request additional formats. 
// HTML only (default)
const content = await nuntly.messages.getContent('imsg_01kabn43yqyxn2bx4ve84mczd3');

if (content.data.html) {
  console.log('HTML URL:', content.data.html.downloadUrl);
  console.log('HTML size:', content.data.html.size, 'bytes');
  console.log('Expires at:', content.data.html.expiresAt);
}

// Request specific formats
const full = await nuntly.messages.getContent('imsg_01kabn43yqyxn2bx4ve84mczd3', {
  format: ['html', 'text'],
});
Use the format query parameter to control which formats are included in the response. Requesting only the formats you need avoids unnecessary downloads.
ParameterDescription
formatFormats to retrieve: html, text, or mime. Defaults to html only. Repeatable.
Each of text, html, and mime is either a content item object or null if not requested or not available for the message.
FieldDescription
textPlain text content, or null.
htmlHTML content, or null.
mimeRaw MIME (.eml) content, or null. Returned for received messages only.
Each content item has the following fields:
FieldDescription
downloadUrlPresigned download URL.
sizeUncompressed size in bytes, or null.
expiresAtWhen the URL expires.

​
Attachments

​
List attachments

Retrieve all attachments for a specific message. 
const attachments = await nuntly.messages.listAttachments('imsg_01kabn43yqyxn2bx4ve84mczd3');

for (const attachment of attachments.data) {
  console.log(`${attachment.filename} (${attachment.contentType}, ${attachment.size} bytes)`);
}

​
Retrieve an attachment

Get a single attachment with a presigned download URL. 
const attachment = await nuntly.messages.getAttachment(
  'imsg_01kabn43yqyxn2bx4ve84mczd3',
  'iatt_01kabn43yqyxn2bx4ve84mczd3',
);

console.log('Download URL:', attachment.data.downloadUrl);
console.log('Content type:', attachment.data.contentType);
console.log('Size:', attachment.data.size);

​
Attachment fields

FieldDescription
idThe unique attachment identifier.
filenameThe original filename, or null.
contentTypeThe MIME content type (for example, application/pdf).
sizeThe size in bytes.
contentDispositionEither inline or attachment.
contentIdThe CID for inline images, or null.
downloadUrlPresigned download URL (included on single retrieval).

​
Next steps

Inboxes

Create and manage inboxes to route incoming emails

Threads

Understand how messages are grouped into conversations

Send, reply, and forward

Respond to received messages from your inboxes