Skip to content

msgraph.md

Latest commit

 

History

History
296 lines (224 loc) · 9.04 KB

msgraph.md

File metadata and controls

296 lines (224 loc) · 9.04 KB

Microsoft Graph Protocol — gomailtest

Exchange Online mailbox operations via Microsoft Graph API: send emails, manage calendar events, export inbox.

Legacy name: msgraphtool. The legacy binary was removed in v3.1. Use gomailtest msgraph <action> --flag (see the migration table in README.md).

Quick Start

# Set authentication via environment variables
$env:MSGRAPHTENANTID = "your-tenant-id"
$env:MSGRAPHCLIENTID = "your-client-id"
$env:MSGRAPHSECRET = "your-secret"
$env:MSGRAPHMAILBOX = "user@example.com"

# Get calendar events
gomailtest msgraph getevents

# Send test email
gomailtest msgraph sendmail --to "recipient@example.com"

# Get inbox messages
gomailtest msgraph getinbox --count 10

Actions

getevents — Retrieve Calendar Events

gomailtest msgraph getevents
gomailtest msgraph getevents --count 10
gomailtest msgraph getevents --count 5 --verbose

sendmail — Send Email Messages

# Send to self (default)
gomailtest msgraph sendmail

# Send to specific recipient
gomailtest msgraph sendmail --to "recipient@example.com"

# Custom subject and body
gomailtest msgraph sendmail \
    --to "recipient@example.com" \
    --subject "Test Email" \
    --body "This is a test message"

# Multiple recipients with CC and BCC
gomailtest msgraph sendmail \
    --to "user1@example.com,user2@example.com" \
    --cc "cc@example.com" \
    --bcc "bcc@example.com" \
    --subject "Team Update"

# HTML email
gomailtest msgraph sendmail \
    --to "recipient@example.com" \
    --subject "HTML Email" \
    --bodyHTML "<h1>Hello</h1><p>This is an <strong>HTML</strong> email.</p>"

# Both text and HTML (multipart MIME)
gomailtest msgraph sendmail \
    --to "recipient@example.com" \
    --subject "Multipart Email" \
    --body "This is the plain text version" \
    --bodyHTML "<h1>HTML Version</h1><p>This is the <em>HTML</em> version</p>"

# With attachments
gomailtest msgraph sendmail \
    --to "recipient@example.com" \
    --subject "Report Attached" \
    --attachments "C:\Reports\report.pdf,C:\Data\spreadsheet.xlsx"

sendinvite — Create Calendar Invitations

gomailtest msgraph sendinvite --subject "Team Meeting"

gomailtest msgraph sendinvite \
    --subject "Project Review" \
    --start "2026-01-15T14:00:00Z" \
    --end "2026-01-15T15:00:00Z"

# All-day event
gomailtest msgraph sendinvite \
    --subject "Conference Day" \
    --start "2026-02-01T00:00:00Z" \
    --end "2026-02-02T00:00:00Z"

getinbox — Retrieve Inbox Messages

gomailtest msgraph getinbox
gomailtest msgraph getinbox --count 20

getschedule — Check Recipient Availability

gomailtest msgraph getschedule --to "colleague@example.com"

exportinbox — Export Inbox to JSON

gomailtest msgraph exportinbox --count 50

Output goes to %TEMP%\export\{date}\message_{n}_{timestamp}.json.

searchandexport — Search by Message ID

gomailtest msgraph searchandexport --messageid "<message-id@example.com>"

Flags

Persistent (all subcommands)

Flag Description Environment Variable Default
--tenantid Azure AD Tenant ID (GUID) MSGRAPHTENANTID —
--clientid Application (Client) ID (GUID) MSGRAPHCLIENTID —
--mailbox Target user email address MSGRAPHMAILBOX —
--secret Client Secret MSGRAPHSECRET —
--pfx Path to .pfx certificate file MSGRAPHPFX —
--pfxpass Password for .pfx certificate MSGRAPHPFXPASS —
--thumbprint Certificate thumbprint (Windows only) MSGRAPHTHUMBPRINT —
--bearertoken Pre-obtained Bearer token MSGRAPHBEARERTOKEN —
--proxy HTTP/HTTPS proxy URL MSGRAPHPROXY —
--maxretries Maximum retry attempts MSGRAPHMAXRETRIES 3
--retrydelay Retry delay (milliseconds) MSGRAPHRETRYDELAY 2000
--count Number of items to retrieve MSGRAPHCOUNT 3
--verbose Enable verbose output — false
--loglevel Log level: DEBUG, INFO, WARN, ERROR MSGRAPHLOGLEVEL INFO
--logformat Log file format: csv, json MSGRAPHLOGFORMAT csv

Email flags (sendmail / sendinvite)

Flag Description Environment Variable
--to Comma-separated TO recipients MSGRAPHTO
--cc Comma-separated CC recipients MSGRAPHCC
--bcc Comma-separated BCC recipients MSGRAPHBCC
--subject Email subject MSGRAPHSUBJECT
--body Email body text MSGRAPHBODY
--bodyHTML Email body HTML MSGRAPHBODYHTML
--body-template Path to HTML template file MSGRAPHBODYTEMPLATE
--attachments Comma-separated file paths MSGRAPHATTACHMENTS
--start Start time (RFC3339) MSGRAPHSTART
--end End time (RFC3339) MSGRAPHEND
--messageid Internet Message ID MSGRAPHMESSAGEID

Authentication Methods

Provide exactly one method. Mutually exclusive:

Client Secret

gomailtest msgraph getevents \
    --tenantid "..." --clientid "..." \
    --secret "your-client-secret" \
    --mailbox "user@example.com"

PFX Certificate

gomailtest msgraph getevents \
    --tenantid "..." --clientid "..." \
    --pfx "C:\Certs\app-cert.pfx" --pfxpass "certificate-password" \
    --mailbox "user@example.com"

Windows Certificate Store (Thumbprint)

gomailtest msgraph getevents \
    --tenantid "..." --clientid "..." \
    --thumbprint "CD817B3329802E692CF30D8DDF896FE811B048AB" \
    --mailbox "user@example.com"

Bearer Token

gomailtest msgraph getevents \
    --tenantid "..." --clientid "..." \
    --bearertoken "eyJ0eXAi..." \
    --mailbox "user@example.com"

Environment Variables

$env:MSGRAPHTENANTID = "tenant-id"
$env:MSGRAPHCLIENTID = "client-id"
$env:MSGRAPHSECRET = "your-secret"
$env:MSGRAPHMAILBOX = "user@example.com"

gomailtest msgraph sendmail --to "recipient@example.com"

Proxy Usage

# Specify proxy on command line
gomailtest msgraph sendmail \
    --to "user@example.com" \
    --proxy "http://proxy.company.com:8080"

# Proxy via environment variable
$env:MSGRAPHPROXY = "http://proxy.company.com:8080"
gomailtest msgraph getevents

Advanced Examples

HTML Report with Multiple Attachments

gomailtest msgraph sendmail \
    --to "team-lead@example.com,manager@example.com" \
    --cc "team@example.com" \
    --subject "Q1 2026 Performance Report" \
    --bodyHTML "<h1>Q1 Performance Report</h1><p>See attached metrics and analysis.</p>" \
    --attachments "C:\Reports\Q1-Metrics.xlsx,C:\Reports\Q1-Analysis.pdf" \
    --verbose

Automated Monitoring Script

# Log inbox and calendar to files
gomailtest msgraph getinbox --count 50 | Out-File -Append "C:\Logs\inbox-monitor.log"
gomailtest msgraph getevents --count 20 | Out-File -Append "C:\Logs\calendar-monitor.log"

CSV Logging

Operations are logged to %TEMP%\_msgraphtool_{action}_{date}.csv.

Log Schemas

Action Columns
getevents Timestamp, Action, Status, Mailbox, Event Subject, Event ID
sendmail Timestamp, Action, Status, Mailbox, To, CC, BCC, Subject, Body Type, Attachments
sendinvite Timestamp, Action, Status, Mailbox, Subject, Start Time, End Time, Event ID
getinbox Timestamp, Action, Status, Mailbox, Subject, From, To, Received DateTime

Retry Configuration

# Custom retry settings
gomailtest msgraph getevents --maxretries 5 --retrydelay 3000

# Disable retries
gomailtest msgraph sendmail --maxretries 0

Retry uses exponential backoff: 2s → 4s → 8s → 16s → 30s (capped). Retries on HTTP 429, 503, 504, network timeouts. Never retries authentication failures or 4xx errors.

Required Azure AD Permissions

Action Permission
sendmail Mail.Send
getevents, sendinvite Calendars.ReadWrite
getinbox, exportinbox, searchandexport Mail.Read
getschedule Calendars.Read

Tips and Best Practices

  1. Security: Use environment variables for sensitive data — avoid passing secrets as CLI flags (visible in process list)
  2. Verbose Mode: Use --verbose when troubleshooting authentication or API issues
  3. CSV Logs: Check CSV log files for historical records of all operations
  4. Graceful Shutdown: Press Ctrl+C to interrupt long-running operations safely (CSV logger closes cleanly)
  5. Flag Precedence: Command-line flags override environment variables
  6. Comma Separation: Lists (--to, --cc, --bcc, --attachments) use comma-separation; spaces are trimmed
  7. Time Format: Calendar times use RFC3339 format (e.g., 2026-01-15T14:00:00Z)

Related Documentation