{"_id":"54504d643c6f700800a9b4de","user":"5432d74e8780d4080074d772","category":{"_id":"54bb05cf9741c81500078f73","pages":["54bc3666e55d192000a62ef1","54bc89693e9c780c00303844","561454290ab2550d00166d9d","5614eaac8113d20d00082e6d"],"project":"53844557a43e08da4677be0e","version":"53844558a43e08da4677be12","__v":4,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-01-18T01:01:03.808Z","from_sync":false,"order":1,"slug":"integration-by-email-type","title":"Integration by email type"},"project":"53844557a43e08da4677be0e","version":{"_id":"53844558a43e08da4677be12","__v":8,"project":"53844557a43e08da4677be0e","createdAt":"2014-05-27T07:57:12.136Z","releaseDate":"2014-05-27T07:57:12.136Z","categories":["53844558a43e08da4677be13","538619e1ef91f96d49aa1a0b","541e82877eb16bb64f83c0ca","5445a073c3eb3808000c76b2","5445a098c3eb3808000c76b3","54bb05ab522f03150054d9e8","54bb05cf9741c81500078f73","55b7d0e5568be2230092bb92"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"false","version_clean":"1.0.0","version":"1.0"},"is_link":false,"__v":16,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2014-10-29T02:13:56.958Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"basic_auth":false,"results":{"codes":[]},"settings":"","try":true,"auth":"never","params":[],"url":""},"isReference":false,"order":0,"body":"At Knowtify, we power all your automated email needs - from highly engaging, recurring Digest emails, to one-off newsletters or announcements, to real-time Transactional emails. This post will help you deliver your Transactional or Notification emails.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"What are Transactional/Notification emails?\"\n}\n[/block]\nTransactional or Notification emails are emails that are triggered by a specific event or happening in your product. This could include:\n\n- Purchase confirmations\n- Connection requests\n- Direct messages\n- Social activity (likes, comments, etc)\n- New listings\n- And many, many more (you can learn more about Notification email best practices [in this post](http://blog.knowtify.io/the-art-of-the-notification-email/))\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"HOW TO TRIGGER THESE EMAILS IN KNOWTIFY\"\n}\n[/block]\nYou can trigger your Transactional emails a few ways:\n\n- You can send an event trigger via our [REST API](http://api.knowtify.io/docs/knowtify-api-basics)\n- You can send an event trigger via our [JavaScript API](http://api.knowtify.io/docs/javascript-widget)\n- You can trigger via an event sent through our [Segment integration](http://api.knowtify.io/docs/segmentio) \n\nSee below for more detail on each method...\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Triggering a Transactional email via the API\"\n}\n[/block]\nWhen an event occurs in your app that should trigger an email, you will make a call that looks like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST http://www.knowtify.io/api/v1/contacts/upsert\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"event\\\":\\\"purchase\\\",  //this is the tag for the email in Knowtify\\n  \\\"contacts\\\": [\\n        {\\n            \\\"email\\\":\\\"marty:::at:::mcfly.io\\\", //this is to whom the email will be delivered\\n          \\t\\\"data\\\":{\\n              \\\"PurchasedItem\\\":\\\"Flux Capacitor 2000\\\", //this is all sample data that will populate the body of the email \\n              \\\"ItemImage\\\":\\\"/fluxcapacitor2000.jpg\\\",\\n              \\\"ItemDescription\\\": \\\"The most advanced Capacitor yet!\\\",\\n              \\\"PurchasePrice\\\":\\\"$1,299\\\"\\n            }\\n        }\\n   \\t]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe important elements for this call include: \n\n1. The tag of the email in Knowtify (see below). This should be inserted as the value to an \"event\" key in the API call.\n2. The email address of the person receiving the email. This is a key/value pair under \"Contacts\".\n3. The content of the email. Any data that will serve as the content of the email should also be inserted under \"Contacts...Data\". Make sure that the key names you create here match the variables you enter into your email template in Knowtify.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Triggering a Transactional Email via JavaScript widget\"\n}\n[/block]\nAlong with triggering a transactional email with our standard API, you can also user our [JavaScript widget](http://api.knowtify.io/v1.0/docs/javascript-widget) to trigger these emails. \n\nSimply adding the tag or the ID of the email template you want to trigger as a value in the \"event\" key in the JavaScript call. You can see it here:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script>\\n\\tknowtifyApi('update_contact',{\\n\\t\\t\\\"public_token\\\":\\\"xxx\\\",\\n\\t\\t\\\"email\\\":\\\"joe@test.com\\\",\\n\\t\\t\\\"name\\\":\\\"Joe\\\",\\n\\t\\t\\\"event\\\":\\\"low_credits\\\",\\n\\t\\t\\\"data\\\":{\\n\\t\\t\\t\\\"id\\\":123,\\n\\t\\t\\t\\\"credits\\\":10\\n\\t\\t}\\n\\t});\\n</script>\\n<script src=\\\"http://js.knowtify.io/api.js\\\" type=\\\"text/javascript\\\" defer></script>\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nIt's very important that you take great care when triggering your event emails via the JavaScript widget. It is very easy to send multiple emails in error. Take care when using this method to insure that you are triggering emails as you intend. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Triggering transactional emails directly from Segment\"\n}\n[/block]\nWith our integration with [Segment.com](http://api.knowtify.io/docs/segmentio), you can ship transactional/notification emails directly from events shipped to Knowtify via Segment. You can learn more about how to do that [in this dedicated post](http://api.knowtify.io/v1.0/docs/transactional-emails-with-segment).\n[block:api-header]\n{\n  \"type\": \"basic\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"CREATING AND ACTIVATING AN EMAIL TEMPLATE\"\n}\n[/block]\nOnce you have your triggers set (or you can do this part first), you can create an email template for this email. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creating the Email Template\"\n}\n[/block]\nYou will use our email designer to create a template for your transactional emails (be sure to select a Notification email).\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/rntLaNQrqtzn8gJxl9ww_skitch.png\",\n        \"skitch.png\",\n        \"1239\",\n        \"671\",\n        \"#e75054\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nYou will be inserting {merge_tags} for any variable, personalized content that will be contained in the event data. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Add an Event tag?\"\n}\n[/block]\nYou will need to add the name of the Event that you have specified in your call as an Event tag on the Delivery tab of your email.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/e8dIeSn6VmBsoB4Di3gZ_skitch.png\",\n        \"skitch.png\",\n        \"1276\",\n        \"614\",\n        \"#c45169\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"(Optional) Filter Recipients with Rules\"\n}\n[/block]\nIf you want, you can create rules to filter who should receive your notifications (ie - only people with a user-type of Admin, or only people who haven’t logged in in 2 days, etc), you can do that here as well. \n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/SByRDCkSaiOOoRnRUB8g_skitch.png\",\n        \"skitch.png\",\n        \"595\",\n        \"368\",\n        \"#a3543b\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Set it Live!\"\n}\n[/block]\nThe only thing left is to set your email to Live and let 'er fly!\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ocKCjQDQau6Qmn2TnmmQ_skitch.png\",\n        \"skitch.png\",\n        \"1260\",\n        \"555\",\n        \"#bb5668\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nVoila! Your Transactional/Notification emails will start shipping immediately.","excerpt":"Sending Transactional emails through Knowtify\n\n*Want a quick way to test our API? Check out our [Postman collection](http://api.knowtify.io/v1.0/docs/postman).\n*","slug":"sending-event-based-emails","type":"basic","title":"TRANSACTIONAL EMAILS"}

TRANSACTIONAL EMAILS

Sending Transactional emails through Knowtify *Want a quick way to test our API? Check out our [Postman collection](http://api.knowtify.io/v1.0/docs/postman). *

At Knowtify, we power all your automated email needs - from highly engaging, recurring Digest emails, to one-off newsletters or announcements, to real-time Transactional emails. This post will help you deliver your Transactional or Notification emails. [block:api-header] { "type": "basic", "title": "What are Transactional/Notification emails?" } [/block] Transactional or Notification emails are emails that are triggered by a specific event or happening in your product. This could include: - Purchase confirmations - Connection requests - Direct messages - Social activity (likes, comments, etc) - New listings - And many, many more (you can learn more about Notification email best practices [in this post](http://blog.knowtify.io/the-art-of-the-notification-email/)) [block:api-header] { "type": "basic", "title": "HOW TO TRIGGER THESE EMAILS IN KNOWTIFY" } [/block] You can trigger your Transactional emails a few ways: - You can send an event trigger via our [REST API](http://api.knowtify.io/docs/knowtify-api-basics) - You can send an event trigger via our [JavaScript API](http://api.knowtify.io/docs/javascript-widget) - You can trigger via an event sent through our [Segment integration](http://api.knowtify.io/docs/segmentio) See below for more detail on each method... [block:api-header] { "type": "basic", "title": "Triggering a Transactional email via the API" } [/block] When an event occurs in your app that should trigger an email, you will make a call that looks like this: [block:code] { "codes": [ { "code": "POST http://www.knowtify.io/api/v1/contacts/upsert", "language": "text" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"event\":\"purchase\", //this is the tag for the email in Knowtify\n \"contacts\": [\n {\n \"email\":\"marty@mcfly.io\", //this is to whom the email will be delivered\n \t\"data\":{\n \"PurchasedItem\":\"Flux Capacitor 2000\", //this is all sample data that will populate the body of the email \n \"ItemImage\":\"/fluxcapacitor2000.jpg\",\n \"ItemDescription\": \"The most advanced Capacitor yet!\",\n \"PurchasePrice\":\"$1,299\"\n }\n }\n \t]\n}", "language": "json" } ] } [/block] The important elements for this call include: 1. The tag of the email in Knowtify (see below). This should be inserted as the value to an "event" key in the API call. 2. The email address of the person receiving the email. This is a key/value pair under "Contacts". 3. The content of the email. Any data that will serve as the content of the email should also be inserted under "Contacts...Data". Make sure that the key names you create here match the variables you enter into your email template in Knowtify. [block:api-header] { "type": "basic", "title": "Triggering a Transactional Email via JavaScript widget" } [/block] Along with triggering a transactional email with our standard API, you can also user our [JavaScript widget](http://api.knowtify.io/v1.0/docs/javascript-widget) to trigger these emails. Simply adding the tag or the ID of the email template you want to trigger as a value in the "event" key in the JavaScript call. You can see it here: [block:code] { "codes": [ { "code": "<script>\n\tknowtifyApi('update_contact',{\n\t\t\"public_token\":\"xxx\",\n\t\t\"email\":\"joe@test.com\",\n\t\t\"name\":\"Joe\",\n\t\t\"event\":\"low_credits\",\n\t\t\"data\":{\n\t\t\t\"id\":123,\n\t\t\t\"credits\":10\n\t\t}\n\t});\n</script>\n<script src=\"http://js.knowtify.io/api.js\" type=\"text/javascript\" defer></script>", "language": "json" } ] } [/block] It's very important that you take great care when triggering your event emails via the JavaScript widget. It is very easy to send multiple emails in error. Take care when using this method to insure that you are triggering emails as you intend. [block:api-header] { "type": "basic", "title": "Triggering transactional emails directly from Segment" } [/block] With our integration with [Segment.com](http://api.knowtify.io/docs/segmentio), you can ship transactional/notification emails directly from events shipped to Knowtify via Segment. You can learn more about how to do that [in this dedicated post](http://api.knowtify.io/v1.0/docs/transactional-emails-with-segment). [block:api-header] { "type": "basic" } [/block] [block:api-header] { "type": "basic", "title": "CREATING AND ACTIVATING AN EMAIL TEMPLATE" } [/block] Once you have your triggers set (or you can do this part first), you can create an email template for this email. [block:api-header] { "type": "basic", "title": "Creating the Email Template" } [/block] You will use our email designer to create a template for your transactional emails (be sure to select a Notification email). [block:image] { "images": [ { "image": [ "https://files.readme.io/rntLaNQrqtzn8gJxl9ww_skitch.png", "skitch.png", "1239", "671", "#e75054", "" ] } ] } [/block] You will be inserting {merge_tags} for any variable, personalized content that will be contained in the event data. [block:api-header] { "type": "basic", "title": "Add an Event tag?" } [/block] You will need to add the name of the Event that you have specified in your call as an Event tag on the Delivery tab of your email. [block:image] { "images": [ { "image": [ "https://files.readme.io/e8dIeSn6VmBsoB4Di3gZ_skitch.png", "skitch.png", "1276", "614", "#c45169", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "(Optional) Filter Recipients with Rules" } [/block] If you want, you can create rules to filter who should receive your notifications (ie - only people with a user-type of Admin, or only people who haven’t logged in in 2 days, etc), you can do that here as well. [block:image] { "images": [ { "image": [ "https://files.readme.io/SByRDCkSaiOOoRnRUB8g_skitch.png", "skitch.png", "595", "368", "#a3543b", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Set it Live!" } [/block] The only thing left is to set your email to Live and let 'er fly! [block:image] { "images": [ { "image": [ "https://files.readme.io/ocKCjQDQau6Qmn2TnmmQ_skitch.png", "skitch.png", "1260", "555", "#bb5668", "" ] } ] } [/block] Voila! Your Transactional/Notification emails will start shipping immediately.