Package com.tnsai.tools.communication

Class EmailTools

java.lang.Object

com.tnsai.tools.communication.EmailTools

public class EmailTools
extends Object

Function-shape email tools — the LangChain-style replacement for the legacy EmailSenderTool (SMTP), GmailTool (Gmail send via REST), and GmailInboxTool (Gmail list via REST). See issue #188.

Three typed @Tool methods on a single POJO:

Method	Backend	Auth	Idempotent
smtpSend(java.lang.String, java.lang.String, java.lang.String)	JavaMail SMTP	SMTP_USERNAME/PASSWORD	✗ (sends a message)
gmailSend(java.lang.String, java.lang.String, java.lang.String)	Gmail REST API	GMAIL_ACCESS_TOKEN (OAuth)	✗
gmailInbox(int, java.lang.String)	Gmail REST API	GMAIL_ACCESS_TOKEN	✓ (read-only)

All credentials are constructor-injected; the LLM never sees a password / token / Gmail user. Methods that need a credential the POJO doesn't have throw IllegalStateException naming the missing env var, so an agent configured for SMTP-only can register the POJO without the Gmail methods working until a token shows up.

Since:

0.5.7 (Phase 2 batch 6a — built-in tool migration to function shape, see #188)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	EmailTools.Builder	Builder for tests / DI containers / multi-tenant setups that need to construct the POJO with explicit credentials instead of env-vars.

Constructor Summary

Constructors

Constructor	Description
EmailTools()	Default constructor — picks every credential from environment variables.

Method Summary

Modifier and Type	Method	Description
List<Map<String,Object>>	gmailInbox(int maxResults, String query)
String	gmailSend(String to, String subject, String body)
String	smtpSend(String to, String subject, String body)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

EmailTools

public EmailTools()

Default constructor — picks every credential from environment variables.

Env var	Default	Used by
SMTP_HOST	—	smtp_send
SMTP_PORT	587	smtp_send
SMTP_USERNAME	—	smtp_send
SMTP_PASSWORD	—	smtp_send
SMTP_AUTH	true	smtp_send
SMTP_STARTTLS_ENABLE	true	smtp_send
GMAIL_ACCESS_TOKEN	—	gmail_send + gmail_inbox
GMAIL_USER	—	gmail_send (From: header)

Method Details

smtpSend

@Tool(name="smtp_send",
      description="DESTRUCTIVE: send a plain-text email via the configured SMTP server (JavaMail). Returns a one-line confirmation with the recipient address. Requires SMTP_HOST + SMTP_USERNAME + SMTP_PASSWORD; the From: header is the configured SMTP_USERNAME.",
      keywords={"email","smtp","send","mail"})
public String smtpSend(@ToolParam(description="Recipient email address (single address; multiple recipients via comma-separated string)")
 String to,
 @ToolParam(description="Email subject line")
 String subject,
 @ToolParam(description="Plain-text body of the email")
 String body)
                throws jakarta.mail.MessagingException

Throws:

jakarta.mail.MessagingException

gmailSend

@Tool(name="gmail_send",
      description="DESTRUCTIVE: send a plain-text email via the Gmail REST API. The body is wrapped in a minimal MIME message and base64url-encoded into the {raw: \u2026} field. Returns a one-line confirmation. Requires GMAIL_ACCESS_TOKEN (OAuth bearer token with Gmail scope) and GMAIL_USER (the From: address).",
      keywords={"email","gmail","google","send"})
public String gmailSend(@ToolParam(description="Recipient email address")
 String to,
 @ToolParam(description="Email subject line")
 String subject,
 @ToolParam(description="Plain-text body of the email")
 String body)
                 throws IOException

Throws:

IOException

gmailInbox

@Tool(name="gmail_inbox",
      description="Read the latest Gmail messages \u2014 returns up to {maxResults} summaries (subject, from, date, snippet). Optional {query} is a Gmail search expression (e.g. \"is:unread\", \"from:alice@example.com\", \"newer_than:1d\"). Read-only \u2014 does not mark messages as read. Requires GMAIL_ACCESS_TOKEN.",
      keywords={"email","gmail","google","inbox","list","read"},
      idempotent=true)
public List<Map<String,Object>> gmailInbox(@ToolParam(description="Number of summaries (1..20; defaults to 5)",required=false,defaultValue="5")
 int maxResults,
 @ToolParam(description="Gmail search expression (e.g. \"is:unread\"); blank fetches the latest in primary",required=false,defaultValue="")
 String query)
                                    throws IOException

Throws:

IOException