diff --git a/Troubleshooting.md b/Troubleshooting.md index 87dac56..3c5e0a1 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -79,4 +79,60 @@ Below is a chart of special characters and the value you should set them: | **@** | **%40** | The at symbol is what divides the user and/or password from hostname in a URL. if your username and/or password contains an '@' symbol, it can cause the url parser to get confused. | **+** | **%2B** | By default a addition/plus symbol **(+)** is interpreted as a _space_ when specified in the URL. It must be escaped if you actually want the character to be represented as a **+**. | **,** | **%2C** | A comma only needs to be escaped in _extremely rare circumstances_ where one exists at the very end of a specific URL that has been chained with others using a comma. [See PR#104](https://github.com/caronc/apprise/pull/104) for more details as to why you _may_ need this. -| **:** | **%3A** | A colon will never need to be escaped unless it is found as part of a user/pass combination. Hence in a url `http://user:pass@host` you can see that a colon is already used to separate the _username_ from the _password_. Thus if your _{user}_ actually has a colon in it, it can confuse the parser into treating what follows as a password (and not the remaining of your username). This is a very rare case as most systems don't allow a colon in a username field. \ No newline at end of file +| **:** | **%3A** | A colon will never need to be escaped unless it is found as part of a user/pass combination. Hence in a url `http://user:pass@host` you can see that a colon is already used to separate the _username_ from the _password_. Thus if your _{user}_ actually has a colon in it, it can confuse the parser into treating what follows as a password (and not the remaining of your username). This is a very rare case as most systems don't allow a colon in a username field. + +## Formatting Issues +If your upstream server is not correctly interpreting the information you're passing it, it could be a simple tweak to Apprise you need to make to help it along. + +The thing with Apprise is it doesn't know what you're feeding it (the format the text is in); so by default it just passes exactly what you hand it right along to the upstream service. Since Email operates using HTML formatting (by default), if you feed it raw text, it may not interpret the new lines correctly (because HTML ignores these charaters); you can solve this problem by 3 ways: + +1. Change your email URL to read this instead (adding the `format=text` parameter) + * `mailtos://example.com?user=username&pass=password&to=myspy@example.com&format=text` +1. For developers, your call to `notify()` to include should include the `body_format` value set: + ```python + # one more include to keep your code clean + from apprise import NotifyFormat + + apobj.notify( + body=message, + title='My Notification Title', + body_format=NotifyFormat.TEXT, + ) + ``` +1. For developers, you can actually make a global variable out of the `body_format` so you don't have to keep setting it every time you call `notify` (in-case you intend to call this throughout your code in several locations): + ```python + import apprise + from apprise import NotifyFormat + from apprise import AppriseAsset + + # Create your Apprise Asset + asset = apprise.Asset(body_format=apprise.NotifyFormat.TEXT) + + # Create your Apprise object (pass in the asset): + apobj = apprise.Apprise(asset=asset) + + # Add your objects (like you're already doing) + apobj.add('mailtos://example.com?user=username&pass=password&to=myspy@example.com') + + # And your multi-line message + message = """ + This message will self-destruct in 10 seconds... + + Or not... (... yeah it probably won't at all) + + Chris + """ + + # The big difference here is now all calls to notify already have the body_format + # set to be TEXT. Apprise knows everything you're feeding it will always be this + # You can still specify body_format here in the future and over-ride if you ever + # need to, but your notify stays simple like you had it (but the multi line will work + # this time): + apobj.notify( + body=message, + title='My Notification Title', + ) + ``` +**What it boils down to is:** +* Developers can use the `body_format` tag which is telling Apprise what the **INPUT source** is. If a Apprise knows this it can go ahead and make special accommodations for the services that are expecting another format. By default the `body_format` is `None` and no modifications to the data fed to Apprise is touched at all (it's just passed right through to the upstream provider). +* End User can modify their URL to specify a `format=` which can be either `text`, `markdown`, or `html` which sets the **OUTPUT source**. Notification Plugins can use this information to accommodate the data it's being fed and behave differently to help accommodate your situation.