English
English繁中

Using Agent Mail Safely

By /

Using Agent Mail Safely

Agent Mail is a command-line tool for sending a message through a WordPress site that has been configured to use Gmail. Each send is explicit: the caller supplies the recipient, subject, and body. The tool does not monitor a mailbox or send messages automatically.

WordPress keeps the Gmail authorization and enforces an administrator-managed recipient allowlist. The CLI uses a separate Agent Mail Key; it does not need Gmail credentials or a Bugzilla API key.

Before the first send

A WordPress administrator must:

  • Connect the site’s Gmail account.
  • Enable the Agent Mail endpoint in the site’s Agent Mail settings.
  • Add the intended recipient address to the allowlist.
  • Provide the endpoint URL and the dedicated Agent Mail Key to the authorized operator.

The endpoint must use HTTPS. Copy its complete URL from WordPress settings instead of guessing the route.

The CLI requires Node.js 18 or newer. If you have an approved source checkout, run npm link from its root once, then confirm that agent-mail --help works.

Configure the CLI

Set two values: the complete HTTPS endpoint shown in WordPress and the dedicated Agent Mail Key. On Windows, the user-level configuration file is:

%APPDATA%\bugzilla-cli\.env.agent-mail.local

On macOS or Linux, use $XDG_CONFIG_HOME/bugzilla-cli/.env.agent-mail.local, or ~/.config/bugzilla-cli/.env.agent-mail.local when XDG_CONFIG_HOME is unset.

The file contains placeholders like these; replace them locally and never publish the real values:

WMP_MAIL_URL=https://your-wordpress.example/wp-json/<agent-mail-endpoint>
WMP_MAIL_KEY=your-dedicated-agent-mail-key

The CLI reads the user-level file first, then an optional .env.agent-mail.local file in the current directory, then process environment variables. Later values override earlier ones. These settings are separate from the Bugzilla CLI configuration.

Configuration files store the key as plain text. Restrict access to the file, keep project-local copies out of version control, and avoid putting the key in shell history or command-line arguments. You can use process environment variables for a short-lived session instead.

Prepare a message

Create a UTF-8 JSON file with to, subject, and body strings. The recipient must match an address on the WordPress allowlist.

{
  "to": "[email protected]",
  "subject": "Project update",
  "body": "Hello, here is the update.",
  "attachments": ["./report.pdf"]
}

Omit attachments when the message has no files. Attachment paths are read on the computer running the CLI; WordPress receives each filename and file contents, not the local path.

Send once

From the directory containing message.json, run:

agent-mail send --data '@message.json'

The command submits one message. A successful response includes a Gmail message_id. This confirms Gmail accepted the request; it does not confirm inbox delivery.

If the command times out or reports a server error, delivery may be uncertain. Check the Gmail account’s Sent folder before deciding whether to send again. The CLI does not automatically retry.

Limits and troubleshooting

  • One allowlisted recipient and a plain-text body are supported. HTML mail, multiple recipients, CC, and BCC are not supported.
  • A subject can be up to 200 UTF-8 bytes; a body can be up to 40,000 bytes.
  • Up to five regular files can be attached, with a combined decoded size of 10 MiB.
  • A 403 response usually means the endpoint is disabled, the key is invalid, or the recipient is not allowlisted. Ask the WordPress administrator to check the Agent Mail settings.
  • A validation error means the JSON fields or attachment list do not meet the limits above.
  • For an uncertain timeout or server error, check Gmail Sent before retrying.

Treat the Agent Mail Key as a credential. If it may have been exposed, ask the WordPress administrator to rotate it and update the local configuration.

Scroll to Top