Skip to content

Latest commit

 

History

History
375 lines (275 loc) · 13.3 KB

README.md

File metadata and controls

375 lines (275 loc) · 13.3 KB
Raw

SMTPc

smtpc version smtpc license smtpc python compatibility Downloads say thanks!

SMTPc is simple but powerfull SMTP client for sending emails using CLI. It's dedicated for system admins or developers, however it's easy to use and every CLI user will be satisfied using this.

SMTPc will be useful when:

  • you have to send emails from automated systems (like crons, i.e. some kinds of reports, notifications from NAS etc)
  • you are sending emails with specified structure and content, where only data is changing (templates)
  • you want to send messages using your SMTP provider without worrying about storing or passing credentials
  • you need a tool that will help you debug SMTP session to your SMTP server (interactive session, clean debugs)

If you like this tool, just say thanks.

Current stable version

0.9.2

Features

  • Predefined profiles for use with many SMTP servers
  • Predefined messages (with templates!) for sending messages just by referencing the message name
  • Automatically build message from given parameters, do not glue headers manually
  • Passwords stored in an encrypted form (optionally)
  • Edit raw message body just before sending
  • Interactive SMTP session
  • Clean and readable SMTP session logs (if enabled). Especially with colorama module (available by default in smtpc[extended] version)!
  • SSL and TLS connections, of course
  • You can easily spoof your own messages, by specifying other sender/recipient in message headers, and other one for SMTP session
  • Custom email headers
  • If you have multiple IP addresses available, choose which one you want to use
  • It's all Python!

Installation

SMTPc should work on any POSIX platform where Python is available. This includes Linux, macOS/OSX etc.

The simplest way is to use Python's built-in package system:

python3 -m pip install 'smtpc[extended]'

It will install SMTPc and related packages for the best user experience. If you want to install the basic version without additions (colors, extended Jinja2 templates), then start with:

python3 -m pip install smtpc

You can also use pipx if you don't want to mess with system packages and install SMTPc in virtual environment:

pipx install 'smtpc[extended]'

Voila!

Python version

SMTPc is tested against Python 3.7+. Older Python versions may work, or may not.

How to use

First, add the account that you want to use for sending. In this example we are using Sendria, which runs on our local environment:

smtpc profiles add sendria --host 127.0.0.1 --port 1025

You can verify that the profile is stored:

smtpc profiles list

Now, add a few messages for future use:

smtpc messages add plain --subject 'Some plain email' --body 'Some plain message body' --from [email protected] --to [email protected]
smtpc messages add html --subject 'Some html email' --body 'Some <b>HTML</b> message body' --body-type=html --from [email protected] --to [email protected]
smtpc messages add alternative --subject 'Some alternative email' --body 'Some plain message body' --body-html 'Some <b>HTML</b> message body' --from [email protected] --to [email protected]

You can verify that your messages are stored:

smtpc messages list

Now, lets send some emails:

smtpc send --profile sendria --message alternative
smtpc send --profile sendria --message plain --subject 'Changed subject for plain'

In the second example above, we are using a predefined message named plain, but with a changed subject.

smtpc messages add default-profile --profile sendria --subject 'Default profile' --body 'Plain email with default profile' --from [email protected] --to [email protected]
smtpc send --mesage default-profile # will use profile specified when creating message; `sendria`

Here we have specified some simple email, but together there is saved also profile name. Now, send specified message will use this profile by default!

You don't need to use any predefined profiles or messages. You can just pass them directly when sending:

smtpc send --host 127.0.0.1 --port 1025 --body-type html --subject 'Some html email' --body 'Some <b>HTML</b> message body' --from [email protected] --to [email protected]

But it's not where the fun is :)

You can also use your predefined messages as templates:

smtpc messages add template-test --subject 'Some templated email: {{ date }}' --body 'Some templated email body: {{ uuid }}' --from [email protected] --to [email protected]
smtpc send --profile sendria --message template-test --template-field "date=$(date)" --template-field "uuid=$(uuidgen)"

So when the email is received, the subject will look like this:

Some templated email: Thu Mar 18 19:05:53 CET 2021

and the body will look like this:

Some templated email body: C21B7FF0-C6BC-47C9-B3AC-5554865487E4

If Jinja2 module is available, you can use it as a templating engine! See more in Templating chapter.

Templating

Templating can be done in both simple and extended forms. In the simplest case, when Jinja2 module is not found, SMTPc can only substitute simple placeholders with data.

For example, if you specify the subject as:

--subject "Now we have {{ date }}"

and when sending you provide a value:

--template-field "date=$(date +'%Y-%m-%dT%H:%M:%S%Z')"

then in the final email it will look like:

Now we have 2021-03-19T10:56:31CET

But if you want to add conditions, loops or any other more complex syntax, you will need to install Jinja2 module (more: Installation).

You willl then have the full power of one of best templating engines Python has. Here's an example:

smtpc messages add template-test --subject 'Some of my projects, state on {{ date }}' --from [email protected] --to [email protected] --body-type html --body '<p>Here I am!</p>
{% if projects %}
<p>Some of my projects:</p>
<ul>
{% for project in projects %}
    <li><a href="https://github.com/msztolcman/{{ project }}">{{ project }}</a></li>
{% endfor %}
</ul>
{% else %}
<p>I have no projects to show :(</p>
{% endif %}
<p>That&#39;s all folks!</p>'
smtpc send --profile sendria --message template-test --template-field "date=$(date -u +'%Y-%m-%dT%H:%M:%S%Z')" --template-field-json='projects=["sendria", "smtpc", "versionner", "ff"]'

So when the email is received, the subject will look like this:

Some of my projects, state on 2021-03-19T10:03:56UTC

and the body (slightly reformatted here):

<p>Here I am!</p>
<p>Some of my projects:</p>
<ul>
    <li><a href="https://github.com/msztolcman/sendria">sendria</a></li>
    <li><a href="https://github.com/msztolcman/smtpc">smtpc</a></li>
    <li><a href="https://github.com/msztolcman/versionner">versionner</a></li>
    <li><a href="https://github.com/msztolcman/ff">ff</a></li>
</ul>
<p>That&#39;s all folks!</p>

There are also available fields from message configuration (like subject or to addresses). These fields (full list below) are the final values (calculated from CLI params to SMTPc and predefined message configuration). All of them are prefixed with smtpc_. This allows for much better customization of emails.

Available predefined fields:

  • smtpc_subject - analogous to --subject
  • smtpc_envelope_from - analogous to --envelope-from
  • smtpc_from - analogous to --from
  • smtpc_envelope_to - analogous to --envelope-to
  • smtpc_to - analogous to --to
  • smtpc_cc - analogous to --cc
  • smtpc_bcc - analogous to --bcc
  • smtpc_reply_to - analogous to --reply-to
  • smtpc_body_type - analogous to --body-type, but it's the final content-type of message
  • smtpc_raw_body - True if --raw-body was used, and False if not
  • smtpc_predefined_profile - almost all informations from profile, if specified (see: --profile)
  • smtpc_predefined_message - almost all informations from message, if specified (see: --message)

You can read more about Jinja2 capabilities on Jinja2 homepage.

Help!

I'm backend developer, not a frontend guy nor designer... And project requires some logo and/or icon. If you're able to prepare some for this project, do not hesitate to mail me :)

Also, if you have an idea how to enhance SMTPc, please fill the ticket. Every idea, every feature request can help you, me and others!

Authors

Contact

If you like or dislike this software, please do not hesitate to tell me about it via email ([email protected]).

If you find a bug or have an idea to enhance this tool, please use GitHub's issues.

ChangeLog

v0.10.0

  • interactive SMTP session: allows to view and edit every SMTP command before sending it to server
  • predefined message can now have attached default profile that will be used when sending
  • adding Date header when building new email message, and there is no custom Date specified using --header param
  • adding Message-ID header when building new email message, and there is no custom Message-ID specified using --header param
  • added new sending param: --disable-ehlo to forcing using HELO (by default EHLO is used, then HELO if first method fails)
  • added new sending and profile param: --auth-method to forcing using specified authorization method
  • added new sending param: --message-dump to dumping built mime message to STDERR
  • work with older SMTP servers which handle only HELO command (doesn't handle newest EHLO)
  • fixed issue where SMTPc doesn't send --identify-as value when using TLS

v0.9.2

  • regression errors fixed

v0.9.1

  • minor bugfixes

v.0.9.0

  • changed way of building message body
  • added template fields from message configuration to templates, with prefix smtpc_
  • default subcommand for commands profiles and messages is list now (calling without subcommand will display list of profiles/messages instead of help)
  • allow reading message body from STDIN if no --body or --body=- is used
  • improved handling rejects from SMTP server
  • added short aliases for main commands: p - for profiles, s for send, m for messages
  • huge improvements for debug messages
  • allow for missing from/envelope_from, to/cc/bcc/envelope_to when adding new predefined message
  • new e2e tests: sending messages

v0.8.1

  • fix error related to Content-Type (fixes #2 - thanks for tuxfamily for reporting)
  • fixed grammar and informations in README (thanks to slawekp for PR)
  • many minor changes reported by linters

v0.8.0

  • send and profiles commands: ask for password if --password param was used with no argument
  • when adding a new profile, you can choose to encrypt your password. In this case you will be asked for encryption key. The same key must be used to decrypt password when sending.
  • added many e2e tests

v0.7.0

  • added --message-interactive param for send command. Allows editing of raw message body just before sending
  • changed url in User-Agent header and when --version is called to smtpc.net
  • many internal fixes and rewrites, added few new tests

v0.6.0

  • added --template-field and --template-field-json params for send command, allows to replace some {{ fields }} in email body or subject with specified values. Or you can also use Jinja2 if module is installed

v0.5.0

  • safe writing config files: will show file content if writing will fail
  • messages list is simplified by default (just message name like in profiles list)
  • new commands: smtpc profiles delete, smtpc messages delete - self explanatory I guess :)
  • few minor bugs squashed
  • few internal changes and improvements

v0.4.1

  • fixed handling --ssl and --tls when sending message using profile
  • added simple --dry-run option
  • added --reply-to option
  • minor fixes to error handling
  • added User-Agent header to generated messages

v0.4.0

  • BC: renamed command: profile -> profiles
  • added new command: messages for managing of saved email messages
  • allow overwriting profile or message predefined options from CLI arguments
  • cleaner and more elegant code

v0.3.0

  • using commands now instead of dozens of CLI arguments

v0.2.0

  • added profiles

v0.1.1

  • fixed --version

v0.1.0

  • very initial version