{ "info": { "author": "Tony Landis", "author_email": "tony.landis@gmail.com", "bugtrack_url": null, "classifiers": [], "description": "PonyExpress\n===========\n\nHigh performance, transactional email message queuing, logging, \nand multi-lingual HTML and plain text templates management.\n\nPonyExpress offers great flexibility so that it can be used by non-python applications:\n\n* Send JSON to the REST interface (language and platform agnostic)\n* Create a Couchdb document (language and platform agnostic)\n* Send JSON to a Gearman job (gearman libraries exist for numerous languages)\n* Use the PonyExpress class (python) \n\nManaging Email Copy and Translations\n------------------------------------\n\nHardcoding email copy into application code is very messy, and does not provide a mechanism\nfor non-developers to make changes to the copy or for translators to do their work. \n\nPonyExpress provides a web interface to free programmers from the mess of maintaining email\ncopy in their code base. It also allows an extremely simple mechanism for sending an email\nfrom anywhere in the application, complete with variable replacement, and custom tags for reporting.\n\n\nQueues, Performance, Scalability, and Load Balancing\n----------------------------------------------------\n\nFor high performance applications, waiting for an SMTP connection and response is a big performance hit.\n\nPonyExpress enables applications to distribute email processing load by providing a queue that messages\ncan be pushed to asynchronously.\n\nMessages can be queued to Couchdb, which has has excellent replication capabilities.\n\nAlso, PonyExpress offers a Gearman interface, which is higher performance and also uses\nCouchdb for logging the messages and any errors.\n\nThe simplest approach to get up and running with PonyExpress is to use the Couchdb\nqueue method. It is also the most fault tolerant, as Couchdb is the only service that\nneeds to be running in order for the queue insertion.\n\nOnly applications that need to be able to hand off an email to the queue in a few milliseconds\nor less would see an advantage to implementing Gearman, as the trade off for that quick transaction\nis the requirement that a Gearman server and the worker daemon to be up and running, \nin addition to Couchdb which is still used for message and error logging.\n\n\nError Handling\n--------------\n\nWhen PonyExpress cannot send a message, for example, because the SMTP service is down or times out,\nit creates a log in Couchdb with the error and the details needed to resend the message.\n\nThis frees developers from creating their own email failure routines, as\nwell as providing a simple way to see what messages have failed and for what reason.\n\n\nMessage Logging\n---------------\n\nPonyExpress logs all emails sent, and provides reports that free developers from writing more\nreports and logging the data themselves. Custom tags can be passed into each message sent, and\nused in reporting later.\n\n\nLanguage and Platform Independent\n---------------------------------\n\nThe ability add a message to the queue simply by creating a Couchdb document is a great way\nto get all the features of PonyExpress regardless of the language being used, or the platform\nbeing developed on.\n\n\n\nGetting Started with PonyExpress\n================================\n\nTo get started, clone the git repo and run setup.py\n\n\tgit clone git@github.com:tony-landis/PonyExpress.git\n\tcd PonyExpress\n\tpython setup.py install\n\tcp default_settings.cfg settings.cfg\n\nOn linux/unix:\n\n\texport PONYEXPRESS_CFG=`pwd`/settings.cfg\n\nOr on windows:\n\n\tset PONYEXPRESS_CFG=\\FULL PATH TO\\settings.cfg\n\nEdit settings.cfg and set the SMTP string to a valid host and port:\n\n\tSMTP_STRING = \"mail.server.com|25\"\n\nIf SMTP authentication is required, then set the SMTP_STRING like this:\n\n\tSMTP_STRING = \"mail.server.com|25|user|password\"\n\n\nStarting the PonyExpress Server\n-------------------------------\n\nYou can now startup the PonyExpress web server (http://packages.python.org/Flask-Actions/)\n\n\texport PONYEXPRESS_CFG=`pwd`/settings.cfg\n\tpython ponyexpress/__init__.py\n\nYou should see:\n\n * Running on http://0.0.0.0:4000/\n * Restarting with reloader...\n\nYou can now go to http://127.0.0.1:4000/ with your web browser. Here you can manage\nemail templates and view reports. If you are running a gearman server, the ping time,\njobs, and workers will be summarized there.\n\n\nSending Your First Email\n------------------------\n\nHere is an example to send an email via the REST API for immediate delivery:\n\ncurl -X PUT http://localhost:4000/send \\\n\t-H \"Content-Type: application/json\" \\\n\t-d '{\"id\":\"test\", \"replacements\":{\"name\":\"Your Name\", \"from\":\"Pony Express\", \"sig\":\"This is my signature\\nLine of Signature\"}, \"tags\":[\"pony\",\"express\"], \"recipient_name\":\"Your Name\", \"recipient_address\":\"you@you.com\", \"sender_name\":\"Pony Express\", \"sender_address\":\"you@you.com\"}'\n\nIf all went well, we should see a response similar to this, where id is the couchdb doc._id of the message log.\n\n\t{\n \t \"id\": \"1cbb1b9400396a1b7cb0e7b35b1eecd4\", \n \t \"result\": true\n\t}\n\nYou can view the message doc here:\n\n\thttp://ponyexpress.couchone.com/ponyexpress/1cbb1b9400396a1b7cb0e7b35b1eecd4\n\n\nConfiguring Couchdb\n-------------------\n\nThe example above used the free couchone database I set up for demonstration purpose.\n\nYou will need to open settings.cfg again and update COUCH_CONN to your own couch database now.\n\nTo add the couchdb views required for the reports and lists, run this:\n\n\texport PONYEXPRESS_CFG=`pwd`/settings.cfg\n\tpython manage.py couch_sync\n\nYou can then restart the PonyExpress server and add your own e-mail templates.\n\n\nManaging Email Templates\n------------------------\n\nWith the PonyExpress Server running, you can vist http://127.0.0.1:4000/add_template to add an email template.\n\n\tTag: This is the id that you will pass later when actually sending an email\n\tName: A name to help you remember the function of the template later\n\tContent Type: If you are entering HTML into the body, select HTML, otherwise select Plain Text\n\tDefault Language: The default language for this template. en, es, etc...\n\tSubject: The subject line for the email\n\tBody: The full email body\n\nAfter saving the template, you will be given the opportunity to add translations for other languages.\n\nYou can use replacements in the Subject and Body, and any keys passed in the replacements dictionary\nwhen sending a message will be replaced with the values.\n\nFor example:\n\n\tTemplate Body: \n\t--------------\n\tHello $name,\n\tYour balance is now $new_balance after your purchase of $purchase.\n\tThank you,\n\t$sig\n\n\n\tReplacement Dict:\n\t-----------------\n\t{ \n\t\t'name': 'John',\n\t\t'new_balance': '$25',\n\t\t'puchase': '5 Widgets',\n\t\t'sig': 'The Widget Team\\n1-800-222-3333'\n\t}\n\n\n\tRendered Body:\n\t--------------\n\tHello John,\n\tYour balance is now $25 after your purchase of 5 Widgets.\n\tThank you,\n\tThe Widget Team\n\t1-800-222-3333'\n\n\nAdding Messages to the Couchdb Queue (python method)\n----------------------------------------------------\n\nThe simplest method to start queuing messages is with the python library.\n\nHere is an example, this message will be stored in couchdb for later processing.\n\n\tfrom ponyexpress.core import PonyExpress\n\tpony = PonyExpress(\n\t\tid='test', # The template doc._id\n\t\tsender_name = 'The Widget Team',\n\t\tsender_address = 'sales@widgets.com',\n\t\trecipient_name = 'John Doe',\n\t\trecipient_address = 'john@gmail.com',\n\t\tlang = 'es',\n\t\treplacements = dict(name='John', new_balance=25, purchase='5 Widgets'),\n\t\ttags = ['newbalance','someothertag']\n\t)\n\t\"\"\"\n\tif your couchdb does not use the defaults of 127.0.0.1:5984, database 'ponyexpress'\n\tthen you will need to pass that with the to_couchdb() call. Otherwise do not pass\n\ta config value.\n\t\"\"\"\n\tconfig = {'COUCH_CONN':'http://127.0.0.1:5984', 'COUCH_DB':'ponyexpress'}\n\tdoc = pony.to_couchdb(config=config)\n\tprint doc._id\n\n\nAdding Messages to the Couchdb Queue (non-python method)\n--------------------------------------------------------\n\nYou can achieve the same result as above without using the python library.\n\nJust put the a document in your couchdb using this structure:\n\n\tcurl -X POST http://127.0.0.1:5984/ponyexpress/ \\\n\t\t-H \"Content-Type: application/json\" \\\n\t\t-d '{\"doc_type\": \"PonyExpressMessage\", \n\t \t\t\"template\": \"test\", \n \t \t\t\"status\": \"queued\", \n\t\t\t\t\"sender_name\": \"The Widget Team\",\n\t\t\t\t\"sender_address\": \"sales@widgets.com\", \n\t\t\t\t\"recipient_name\": \"John Doe\", \n\t\t\t\t\"recipient_address\": \"john@gmail.com\", \n\t\t\t\t\"lang\": \"en\", \n\t\t\t\t\"replacements\": { \"name\":\"John\", \"new_balance\":\"$25\", \"purchase\":\"5 Widgets\" }, \n\t\t\t\t\"tags\":[\"newbalance\", \"someothertag\"]}'\n\n\nProcessing the Couchdb Queue\n----------------------------\n\nAfter adding emails into the queue using one of the couchdb methods below, \nthe next step is to process the queue. To do so, simply run the following command:\n\n\texport PONYEXPRESS_CFG=`pwd`/settings.cfg\n\tpython manage.py queue\n\nYou should see something like this:\n\n\tConnecting to Couchdb...\n\tSuccess: 1bc02b88ef8125a9ea72f1c54692bab9\n\tFinished processing 1 messages\n\n\nSending Messages without Queueing (python method)\n-------------------------------------------------\n\nIf you want to send a message withough putting it in a queue,\nyou must use the python library:\n\n\tfrom ponyexpress.core import PonyExpress\n\tpony = PonyExpress(\n\t\tid='test', # The template doc._id\n\t\tsender_name = 'The Widget Team',\n\t\tsender_address = 'sales@widgets.com',\n\t\trecipient_name = 'John Doe',\n\t\trecipient_address = 'john@gmail.com',\n\t\tlang = 'es',\n\t\treplacements = dict(name='John', new_balance=25, purchase='5 Widgets'),\n\t\ttags = ['newbalance','someothertag']\n\t)\n\n\t\"\"\"\n\tIf your couchdb does not use the defaults of 127.0.0.1:5984, database 'ponyexpress'\n\tthen you will need to pass that with the send() call.\n\n\tAlso, if you use something other than localhost:25 for SMTP or need to provide \n\tSMTP auth, you will need to pass that in the config.\n\t\n\tOtherwise do not pass a config value.\n\t\"\"\"\n\tconfig = {'COUCH_CONN':'http://127.0.0.1:5984', 'COUCH_DB':'ponyexpress', 'SMTP_STRING':'mail.some.com|25|user|pass'}\n\trs = pony.send(config=config)\n\tprint rs\n\n\n\nUsing Gearman for High Performance \n----------------------------------\n\nTo utilize gearman for high performance messaging, you must first start \nthe python worker script for gearman. This assumes you have already configured\nthe correct gearman ip:port in settings.cfg and have a gearmand service running\nat that ip:port.\n\n\texport PONYEXPRESS_CFG=`pwd`/settings.cfg\n\tpython run_gearman.py\n\nYou can now hand off jobs to gearman, here is an example for Python:\n\t\n\tfrom ponyexpress.gearman_interface import PonyExpressClient\n\tpony = PonyExpressClient(\n\t\tid='test', # The template doc._id\n\t\tsender_name = 'The Widget Team',\n\t\tsender_address = 'sales@widgets.com',\n\t\trecipient_name = 'John Doe',\n\t\trecipient_address = 'john@gmail.com',\n\t\tlang = 'es',\n\t\treplacements = dict(name='John', new_balance=25, purchase='5 Widgets'),\n\t\ttags = ['newbalance','someothertag']\n\t)\n\n\t# send in background, non blocking\n\trs = pony.to_gearman(['localhost:4730'], background=True, wait_until_complete=False)\n\tprint \"Status: %s\" % rs.get('result')\n\tprint \"Doc Id: %s\" % rs.get('id')\n\n\t# send and wait for response\n\trs = pony.to_gearman(['localhost:4730'])\n\tprint \"Status: %s\" % rs.get('result')\n\tprint \"Doc Id: %s\" % rs.get('id')", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/tony-landis/PonyExpress", "keywords": null, "license": "Creative Commons Attribution-Noncommercial-Share Alike license", "maintainer": null, "maintainer_email": null, "name": "PonyExpress", "package_url": "https://pypi.org/project/PonyExpress/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/PonyExpress/", "project_urls": { "Download": "UNKNOWN", "Homepage": "https://github.com/tony-landis/PonyExpress" }, "release_url": "https://pypi.org/project/PonyExpress/0.14stable/", "requires_dist": null, "requires_python": null, "summary": "High performance, transactional email message queuing, logging,\t\tand multi-lingual HTML and plain text templates management.", "version": "0.14stable" }, "last_serial": 784934, "releases": { "0.11dev": [ { "comment_text": "", "digests": { "md5": "f39a05807b4ae5278d2360b99a0607af", "sha256": "2cf6d0e7d16b75cf7edf7573da63a47d0d4ec5b4a4b5dea0d63335998bb64501" }, "downloads": -1, "filename": "PonyExpress-0.11dev.tar.gz", "has_sig": false, "md5_digest": "f39a05807b4ae5278d2360b99a0607af", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 4457, "upload_time": "2011-02-07T01:25:58", "url": "https://files.pythonhosted.org/packages/e5/ff/f6678b0fbd3c7ba506b2deb5d682966834e989004d2d70666f1efa9c235c/PonyExpress-0.11dev.tar.gz" } ], "0.12dev": [ { "comment_text": "", "digests": { "md5": "d80cb601b05996cbefd7ebaa4598518c", "sha256": "dbe988c877ffa838b7c40f4c7ed0430e58563a2916e51a79a461562ce43e234a" }, "downloads": -1, "filename": "PonyExpress-0.12dev.tar.gz", "has_sig": false, "md5_digest": "d80cb601b05996cbefd7ebaa4598518c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 4491, "upload_time": "2011-02-07T01:28:42", "url": "https://files.pythonhosted.org/packages/40/2a/dff01783afe04a2b1f416ac5c77e9ccdd89665575c462450441171961c88/PonyExpress-0.12dev.tar.gz" } ], "0.13stable": [ { "comment_text": "", "digests": { "md5": "353beb4ef48a92ac4f923d5cf0a4d667", "sha256": "8c20b8a04fed822e9a3162c0ebf9c716f1342e54783a67e31c06d4e2f0441249" }, "downloads": -1, "filename": "PonyExpress-0.13stable.tar.gz", "has_sig": false, "md5_digest": "353beb4ef48a92ac4f923d5cf0a4d667", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 5908, "upload_time": "2011-09-15T23:38:15", "url": "https://files.pythonhosted.org/packages/e4/cd/a0b79258e6b160a7558fc20f0bfbe18a79dd2646cd7905ef80f9baf5f1df/PonyExpress-0.13stable.tar.gz" } ], "0.14stable": [ { "comment_text": "built for Darwin-10.8.0", "digests": { "md5": "da1e9a0265d97396b402646be03a83bc", "sha256": "659ad6467cf0eae1aee659954820f046fb226b8016631af10acaffb05be89483" }, "downloads": -1, "filename": "PonyExpress-0.14stable.macosx-10.3-fat.tar.gz", "has_sig": false, "md5_digest": "da1e9a0265d97396b402646be03a83bc", "packagetype": "bdist_dumb", "python_version": "any", "requires_python": null, "size": 18091, "upload_time": "2011-09-16T03:29:58", "url": "https://files.pythonhosted.org/packages/df/c7/f85006a0fc3f314bd395d36d4cd5b665fc9967cd4e25796e8fa5fd046ce7/PonyExpress-0.14stable.macosx-10.3-fat.tar.gz" } ], "0.1dev": [ { "comment_text": "", "digests": { "md5": "a677c2074511a9ab83fbbaabcaada98b", "sha256": "83fd2c97c262b91d628c23063eab17ca132b1ddfe4a375d1fa02e74a34d2484e" }, "downloads": -1, "filename": "PonyExpress-0.1dev.tar.gz", "has_sig": false, "md5_digest": "a677c2074511a9ab83fbbaabcaada98b", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 4457, "upload_time": "2011-02-07T01:23:30", "url": "https://files.pythonhosted.org/packages/43/12/2d5df004f501ccc8983b0145a960f0eb278cb0027d447621d8dda3fecd4d/PonyExpress-0.1dev.tar.gz" } ] }, "urls": [ { "comment_text": "built for Darwin-10.8.0", "digests": { "md5": "da1e9a0265d97396b402646be03a83bc", "sha256": "659ad6467cf0eae1aee659954820f046fb226b8016631af10acaffb05be89483" }, "downloads": -1, "filename": "PonyExpress-0.14stable.macosx-10.3-fat.tar.gz", "has_sig": false, "md5_digest": "da1e9a0265d97396b402646be03a83bc", "packagetype": "bdist_dumb", "python_version": "any", "requires_python": null, "size": 18091, "upload_time": "2011-09-16T03:29:58", "url": "https://files.pythonhosted.org/packages/df/c7/f85006a0fc3f314bd395d36d4cd5b665fc9967cd4e25796e8fa5fd046ce7/PonyExpress-0.14stable.macosx-10.3-fat.tar.gz" } ] }