Skip to main content
Messages represent individual emails received on your domain. Each message belongs to a thread and contains sender information, recipients, subject, security verdicts, 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, sender address, or spam verdict. 
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',
});

// Filter by spam verdict
const spamMessages = await nuntly.messages.list({
  spamVerdict: 'FAIL',
});

​
Available filters

ParameterDescription
domainIdFilter messages by a specific domain.
fromFilter messages by sender address.
spamVerdictFilter by spam verdict (PASS or FAIL).
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.fromAddress);
console.log('Subject:', message.data.subject);
console.log('Inbox:', message.data.inbox?.address);
console.log('Direction:', message.data.direction);
console.log('Spam verdict:', message.data.spamVerdict);

​
Message fields

FieldDescription
idThe unique message identifier.
domainNameThe domain the message was received on.
inboxIdThe inbox the message was routed to.
threadIdThe thread this message belongs to.
inboxThe inbox details (id, address, name), or null for default catch-all.
fromAddressThe sender email address.
fromNameThe sender display name.
toAddressesThe recipient addresses.
ccAddressesThe CC addresses.
subjectThe message subject line.
receivedAtThe timestamp when the message was received.
directionEither received or sent.
statusThe message status (received, sent, discarded, or failed).
spfVerdictThe SPF check result.
dkimVerdictThe DKIM check result.
spamVerdictThe spam verdict.
virusVerdictThe virus scan result.
attachmentCountThe number of attachments.

​
Get message content

Retrieve presigned URLs for the message body in different formats. The URLs are temporary and expire after a short period. 
const content = await nuntly.messages.getContent('imsg_01kabn43yqyxn2bx4ve84mczd3');

// Presigned URLs for downloading content
console.log('Plain text:', content.data.textUrl);
console.log('HTML:', content.data.htmlUrl);
console.log('Raw MIME:', content.data.mimeUrl);
FieldDescription
textUrlPresigned URL for the plain text content, or null.
htmlUrlPresigned URL for the HTML content, or null.
mimeUrlPresigned URL for the raw MIME (.eml) content, or null.

​
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.url);
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.
urlPresigned 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