macpymessenger documentation

macpymessenger sends iMessages from Python on macOS. It uses AppleScript, the Messages app, and Python 3.14 t-string templates.

It is built for scripts that should be easy to read and test. The public API is small, errors are explicit, and configuration is checked before a message is sent.

Start here

Install with uv add macpymessenger or pip install macpymessenger, then create a Configuration and an IMessageClient and call send():

from macpymessenger import Configuration, IMessageClient

client = IMessageClient(Configuration())
client.send("+15555555555", "Hello from macpymessenger!")

send() returns None when delivery succeeds. It raises MessageSendError when delivery fails.

Contents:

• Introduction
  • What you get
  • When to use it
  • Limits
  • Next steps
• Installation
  • Install with uv
  • Install with pip
  • Verify the install
  • Common install issues
  • Development setup
• Usage
  • Send a message
  • Handle send errors
  • Delay a message
  • Create a template
  • Send a template
  • Update and delete templates
  • Keep template values as strings
  • List all templates
  • Use TemplateManager directly
  • Send to multiple recipients
  • Experimental stubs
• Configuration
  • Use the bundled AppleScript
  • Use a custom AppleScript path
  • Enable file logging
  • Choose a log file path
  • Pass your own logger
  • Combine custom logging options
• Testing
  • Set up the environment
  • Run tests
  • Run lint and type checks
  • Build the package
  • Build the documentation
  • Understand failures
  • Write tests for changes
• Modules
  • Public API exports
  • client module
  • configuration module
  • templates module
  • Template errors
  • exceptions module
  • Experimental methods
  • AppleScript resource

Get help and contribute

Report bugs and request features at https://github.com/ethan-wickstrom/macpymessenger/issues. Pull requests for focused changes are welcome. Keep examples free of real phone numbers and secrets.

License

macpymessenger is licensed under Apache-2.0. See the LICENSE file for details.

Indices and tables

• Index

• Module Index

• Search Page