Documentation makes strange assumptions about From:/To: in many services

[gdt]

I'm starting off with a discussion vs a bug. I'm new to using apprise, and trying to do so with Home Assistant, although I can reproduce my confusion on the command line. This message is perhaps best described as a plea for clearer docs, and perhaps for accommodation of what I view as the normal use case.

When I look at mail or xmpp, I am boggled by the instructions/syntax, and I think it's that my assumptions about the world are different. Specifically for mail I see the need to configure:

• MTA
  • hostname/addr
  • maybe port
  • maybe force-SSL, maybe opportunistic TLS, maybe negotiate-TLS-or-fail
  • maybe authentication user/password (and perhaps SASL method, but MUAs seem not to need that)
• From: field
• To: field (plural, the recipients)
  The examples seem geared to a remote MTA, and a single email address, using that address for 1) authenticating, 2) From: and 3) To:. I can see the point that systems that require auth likely require that authname and From: match, but sometimes authname is user and sometimes it is user@example.com.

I am expecting to use localhost as the MTA, and to not need to authenticate. I want to sent from bot@example.com and to notify alice@example.com and bob@example.net. The parameter list for mail says f you want the email address ReplyTo address to be something other then your own email address, then you can specify it here. which implies that you can't change From:.

A suggestion is to change the wording to talk about 'the email address used to send the notification" and "recipient of notification" separately, without assuming that they are the same. I view them being the same as a special case to accomodate peopel who can't set up a bot@ account to be the sender; I don't think it's good practice to send automated mail from an account associated with a person, but maybe that's just me. I'm not trying to push doctrine on others, just pointing out that with this mindset the documentation is hard to understand (and I haven't yet).

For xmpp, it seems geared around one JID, when for the same reasons above it seems normal to have two. (Also I can't tell how to split xmpp/xmpps with 5222-clear, 5222-TLS, 5223-oldstyle-SSL, and xmpps doesn't seem like a normal URI scheme.) The list of examples is hard to follow with the various password schemes, and I don't follow {password} being in braces in the examples vs a clear placeholder pass123.

When I look at other methods, I have similar questions.

Maybe the issue is that there's an assumption that the apprise URL is for a sending service, and that recipients are specified separately.

One improvement could be to stop using phrases like "your email" and instead "the email account the notification should be sent from".

[gdt]

For mail, I figured out that

mailto://bot@foo.example.com/?smtp=localhost&to=alice@example.com

works, but I did not find any example like that.

[caronc]

. I want to sent from bot@example.com and to notify alice@example.com and bob@example.net.

You can also write it our as:

• mailto://bot@foo.example.com/alice@example.com/bob@example.net/?smtp=localhost

Or:

• mailto://bot@foo.example.com/?smtp=localhost&to=alice@example.com,bob@example.net/

If you want to get fancy, you can even name the people:

• mailto://bot@foo.example.com/Alice<alice@example.com>/Bob<bob@example.net>/?smtp=localhost

The reason for the from=, to=, etc isn't to cause confusion, but the fact that all of these can be put into a YAML configuration file as well and locked down (so your credentials aren't open to the world).... hence:

# Saved as ~/.apprise.yml
urls:
   - mailto://bot@foo.example.com?smtp=localhost:
      -tag: groupnotify
       to:
           alice@example.com
           bob@example.net

You can then do things like:

# One time only, but protect your file as you would other private ones:
chmod 600 ~/.apprise.yml

apprise -g groupnotify -b "Hey guys, just letting you know the program crashed again, can you come have a look?" --attach /var/core.dump

[caronc]

Glad you figured it out. There is no doubt that the documentation lacks with Apprise. Most people who open tickets though end up solving it a bit later (a lot like you did). Where it lacks in documentation, the intuitiveness is mostly there. Once you get your Apprise URL set up, you'll never change it again. So these are 1 time (at-the-start) problems too. The example you referenced is provided here. But perhaps this page could be re-formatted to be easier to follow (i admit it's confusing).

As per your XMPP comments; unfortunately XMPP was too unreliable and it was pulled out of Apprise a few releases ago. At the end of the day it only wrapped an existing project for the Apprise support due to the protocol's complexity. I will re-visit this some day and add a more general version. So with respect to your reference here, I'm guessing you're using an older version of Apprise. Your comment did however remind me to take it off of the wiki listing here. So thank you for that. This project looks promising.

One improvement could be to stop using phrases like "your email" and instead "the email account the notification should be sent from".

This is great advice; i will go through the wiki page and try to update some of the references.

[gdt]

Thanks; I didn't mean to complain about being able to set parameters, but more that there are big assumptions that aren't explained and hidden defaults. Once I read the code it was a lot clearer, and I should have done that earlier :-)

So my revised suggestion is:

add an example with a no-auth localhost server, and bot@example.com From:, and two To's

which is exactly what you had above, and add

The first configuration is to name an email account (that will by default be the From: field) and to give username/password for authentication (if necessary) and an SMTP server (defaulting to the (normal mail receiver/MX records/domainname???) to use when sending. The second configuration is to name the recipients; as a special case the To: will match the From: if no recipients are specified.

(feel free to take verbatim and/or edit, and don't worry about attribution)

[caronc]

Sorry for the delayed response; i never saw this as a complaint! Very constructive and very valid! 👍

I need to re-write the wiki page for email it think or better structure it in general. I'm open to any help. Even writing here in the discussion is the same markdown as the wiki form itself. I would gladly update it and credit you.

Alternatively you can actually check the wiki out as though it were a project. You just need to append wiki.git to the end of the code.

Hence:

git checkout git@github.com:caronc/apprise.wiki.git

I would love any help you can offer; otherwise I'll definitely try to get to this myself eventually! 😉

[gdt]

I see now my example is sort of there, but It was too hard to see past "your email" and what seemed like standard practice of from/to being the same.