Skip to main content

​
Overview

Jasni provides a complete email API that enables your AI agents to communicate autonomously. Send, receive, read, reply, and forward emails—all programmatically through your agent’s inbox.

​
Agent Inboxes

Before your agent can work with emails, it needs an inbox—its own email identity. You can:
  • Create a new identity: Set up a fresh email address with your custom domain for your agent
  • Connect an existing account: Give your agent access to an existing email provider (Gmail, Outlook, custom IMAP)
Each inbox is linked to your Jasni account. Your agents can only access emails from inboxes you’ve configured.

​
Email Structure

An email object in Jasni contains the following fields:
FieldTypeDescription
uidintegerUnique identifier within the mailbox
messageIdstringRFC 2822 Message-ID header
fromstringSender email address
tostring[]Recipient email addresses
ccstring[]CC recipients
subjectstringEmail subject line
datedatetimeWhen the email was sent/received
textstringPlain text body
htmlstringHTML body
attachmentsobject[]List of attachments
flagsstring[]IMAP flags (e.g., \Seen, \Flagged)

​
Operations

​
Listing Emails

Fetch emails from any folder in your mailbox: 
GET /api/v1/[email protected]&folder=INBOX&limit=50
Common folders:
  • INBOX - Incoming emails
  • Sent - Sent emails
  • Drafts - Draft emails
  • Trash - Deleted emails
  • Spam or Junk - Spam folder

​
Reading an Email

Fetch a specific email by its UID: 
GET /api/v1/emails/[email protected]&folder=INBOX

​
Sending Emails

Send a new email from one of your accounts: 
POST /api/v1/emails/send
{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Hello!",
  "text": "Plain text content",
  "html": "<p>HTML content</p>"
}
Always provide both text and html versions for maximum compatibility across email clients.

​
Replying to Emails

Reply to an existing email with proper threading: 
POST /api/v1/emails/123/[email protected]
{
  "text": "Thanks for your message!",
  "replyAll": false,
  "includeOriginal": true
}
Jasni automatically:
  • Sets the correct In-Reply-To and References headers
  • Determines the correct recipients
  • Adds Re: prefix to the subject
  • Quotes the original message (if includeOriginal is true)

​
Forwarding Emails

Forward an email to new recipients: 
POST /api/v1/emails/123/[email protected]
{
  "to": ["[email protected]"],
  "text": "FYI - see below"
}

​
Updating Email Status

Mark emails as read or unread: 
PATCH /api/v1/emails/123[email protected]
{
  "action": "read"
}

​
Deleting Emails

Move an email to trash: 
DELETE /api/v1/emails/[email protected]

​
Threading

Email threading is automatically handled by Jasni. When you reply to or forward an email, the proper headers are set:
  • Message-ID: Unique identifier for each email
  • In-Reply-To: References the parent email’s Message-ID
  • References: Full chain of Message-IDs in the thread
This ensures emails are grouped correctly in the recipient’s email client.

​
Attachments

When listing or reading emails, attachment metadata is included: 
{
  "attachments": [
    {
      "filename": "document.pdf",
      "contentType": "application/pdf",
      "size": 102400
    }
  ]
}
Attachment download endpoints are available for fetching actual attachment content.

​
Best Practices for AI Agents

Set up webhooks for email.received events so your agent can react immediately. Polling adds latency and wastes resources.
Use the References header to track email threads. This helps your agent understand conversation history and respond contextually.
Have your agent validate recipient email addresses before sending to avoid bounces and maintain sender reputation.
Implement proper rate limiting in your agent to avoid hitting API limits, especially when processing large volumes.
https://mintcdn.com/jasni/lHmS9NbBwozpErCB/icons-svg/send.svg?fit=max&auto=format&n=lHmS9NbBwozpErCB&q=85&s=23534ce0224cf8ac2167cfab19e3a64d

Send Email

Send email endpoint
https://mintcdn.com/jasni/lHmS9NbBwozpErCB/icons-svg/inbox.svg?fit=max&auto=format&n=lHmS9NbBwozpErCB&q=85&s=54294ec8095f35b5faa79a4dd46d0ec5

List Emails

List emails endpoint
https://mintcdn.com/jasni/HyBGBd8FKHwaOJ6d/icons-svg/webhook.svg?fit=max&auto=format&n=HyBGBd8FKHwaOJ6d&q=85&s=f0553984c133e7a1715f7c76ccb52b75

Webhooks

Real-time notifications
https://mintcdn.com/jasni/lHmS9NbBwozpErCB/icons-svg/label.svg?fit=max&auto=format&n=lHmS9NbBwozpErCB&q=85&s=c7aba010e59e1e6eb938baaa17197ac2

Labels

Organize emails