Skill

Pass

Audit score 90

email-smtp-send

tiangong-ai/agent-skills

Send emails via SMTP with optional attachments and IMAP Sent folder sync.

What is email-smtp-send?

Sends outbound email through SMTP with environment-configured credentials, supports attaching local files to messages, and can optionally append sent messages to an IMAP Sent mailbox for cross-client visibility. Use this when you need reliable email delivery with attachment support or want sent messages synchronized across email clients.

Send emails via SMTP with configurable host, port, SSL/STARTTLS, and authentication
Attach local files (PDF, Excel, etc.) to outgoing messages with per-attachment size limits
Append sent messages to IMAP Sent mailbox for visibility in other email clients
Validate SMTP and IMAP configuration before attempting delivery
Return structured JSON status and error output with message IDs and sync metadata
Support CC, BCC, custom Message-ID, In-Reply-To, and References headers

How to install email-smtp-send

npx skills add https://github.com/tiangong-ai/agent-skills --skill email-smtp-send

Prerequisites

SMTP server credentials (host, port, username, password)
For IMAP Sent sync: IMAP server credentials and imapclient library (install via pip)
Local file paths for any attachments to be included

Claude Code

Cursor

Windsurf

Cline

How to use email-smtp-send

1.Set SMTP environment variables (SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM, etc.) or use assets/config.example.env as a template
2.Run `python3 scripts/smtp_send.py check-config` to validate your SMTP and optional IMAP configuration
3.Send a basic email: `python3 scripts/smtp_send.py send --to recipient@example.com --subject "Test" --body "Hello"`
4.To attach files, add `--attach ./path/to/file.pdf` (repeatable for multiple attachments)
5.For IMAP Sent sync, add `--sync-sent --sent-mailbox "Sent Items"` to append the message to your IMAP Sent folder
6.Check the JSON output for `message_id`, `attachment_count`, and `sent_sync` status to verify delivery

Use cases

Good for

Automated report delivery: send generated PDF reports to stakeholders with IMAP sync so they appear in your Sent folder
Batch email notifications: send multiple emails with attachments from an agent workflow
Cross-platform email sync: ensure sent messages appear in both SMTP client and webmail by syncing to IMAP Sent Items
Email with dynamic attachments: programmatically attach files generated during task execution
Reliable delivery verification: check SMTP connectivity and get detailed JSON status for each send

Who it's for

Automation engineers building email workflows
Agents that need to send reports or notifications with attachments
Teams using multiple email clients who want sent-mail synchronized across platforms
Developers integrating outbound email into larger agent tasks

email-smtp-send FAQ

What happens if SMTP send succeeds but IMAP sync fails?

By default, the send is considered successful and returns exit code 0. If you set `--sent-sync-required` or `SMTP_SYNC_SENT_REQUIRED=true`, sync failure will exit with code 1 and print an error event.

Can I use different credentials for SMTP and IMAP?

Yes. SMTP uses SMTP_* env vars; IMAP sent-sync uses SMTP_SENT_IMAP_* vars (with fallbacks to IMAP_* for compatibility).

What email formats are supported?

Plain text (default) and HTML. Set `--content-type html` or `SMTP_CONTENT_TYPE=html` for HTML emails.

Are there attachment size limits?

Yes. Set `--max-attachment-bytes` per send or `SMTP_MAX_ATTACHMENT_BYTES` globally. Individual attachments exceeding this limit will cause the send to fail.

How do I know if the email was actually sent?

Check the JSON output for `event=smtp_sent` and a non-null `message_id`. The script also returns exit code 0 on success and 1 on failure.

Full instructions (SKILL.md)

Source of truth, from tiangong-ai/agent-skills.

name: email-smtp-send description: Send emails through SMTP with optional local attachments and optional IMAP APPEND sync to Sent mailbox. Use when tasks need reliable outbound email delivery, attachment sending, SMTP connectivity checks, or cross-client sent-mail visibility (for example appending to "Sent Items" after SMTP send).

Email SMTP Send

Core Goal

Send outbound email via SMTP with env-configured credentials.
Attach local files into MIME email payload when requested.
Optionally append the sent message to IMAP sent mailbox for cross-client visibility.
Validate SMTP and sent-sync configuration before delivery.
Return machine-readable JSON status/error output.

Workflow

Configure SMTP env vars (see references/env.md and assets/config.example.env).
Optional: configure IMAP sent-sync env vars and install imapclient when sync is enabled.
Validate configuration:

python3 scripts/smtp_send.py check-config

Send one email:

python3 scripts/smtp_send.py send \
  --to recipient@example.com \
  --subject "SMTP test" \
  --body "Hello from email-smtp-send"

Send with attachments:

python3 scripts/smtp_send.py send \
  --to recipient@example.com \
  --subject "Package delivery" \
  --body "See attachments." \
  --attach ./report.pdf \
  --attach ./appendix.xlsx

Send and sync to sent mailbox:

python3 scripts/smtp_send.py send \
  --to recipient@example.com \
  --subject "Synced send" \
  --body "This message will be appended to Sent Items." \
  --sync-sent \
  --sent-mailbox "Sent Items"

Output Contract

check-config prints sanitized SMTP config + defaults + sent-sync config JSON.
send success prints one type=status JSON object containing:
- event=smtp_sent
- sender, recipient summary, subject, SMTP host/port
- message_id
- attachment_count and attachments[] metadata
- sent_sync object with enabled, required, appended, and sync metadata/error
send failures print type=error JSON to stderr with one of:
- event=smtp_send_invalid_args
- event=smtp_send_failed
- event=smtp_sent_sync_failed (only when sync is required and sync fails)

Parameters

send --to: required recipient, repeatable or comma-separated.
send --cc: optional CC recipients.
send --bcc: optional BCC recipients.
send --subject: optional subject (defaults from env).
send --body: optional body (defaults from env).
send --content-type: plain or html.
send --from: optional sender override.
send --attach: optional local attachment path, repeatable or comma-separated.
send --max-attachment-bytes: max bytes allowed per attachment.
send --message-id: optional Message-ID header.
send --in-reply-to: optional In-Reply-To header.
send --references: optional References header.
send --sync-sent|--no-sync-sent: force-enable/disable IMAP sent sync for this send.
send --sent-mailbox: override sent mailbox.
send --sent-flags: IMAP APPEND flags, comma-separated (default \Seen).
send --sent-sync-required: return non-zero if SMTP succeeds but sent sync fails.

Environment defaults:

SMTP_HOST, SMTP_PORT, SMTP_SSL, SMTP_STARTTLS
SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM, SMTP_CONNECT_TIMEOUT
SMTP_SUBJECT, SMTP_BODY, SMTP_CONTENT_TYPE
SMTP_MAX_ATTACHMENT_BYTES
SMTP_SYNC_SENT, SMTP_SYNC_SENT_REQUIRED
SMTP_SENT_IMAP_HOST, SMTP_SENT_IMAP_PORT, SMTP_SENT_IMAP_SSL
SMTP_SENT_IMAP_USERNAME, SMTP_SENT_IMAP_PASSWORD
SMTP_SENT_IMAP_MAILBOX, SMTP_SENT_IMAP_FLAGS, SMTP_SENT_IMAP_CONNECT_TIMEOUT
compatibility fallbacks: IMAP_HOST, IMAP_PORT, IMAP_SSL, IMAP_USERNAME, IMAP_PASSWORD, IMAP_CONNECT_TIMEOUT

Dependency

Sent-sync mode requires imapclient:

python3 -m pip install imapclient

Error Handling

Invalid env config exits with code 2.
Send failure exits with code 1.
If sync is required (--sent-sync-required or SMTP_SYNC_SENT_REQUIRED=true), sync failure exits with code 1.