{"_id":"5635b292d209b50d0031dfcb","category":{"_id":"5635b291d209b50d0031dfc6","version":"5635b290d209b50d0031dfc4","pages":["5635b292d209b50d0031dfcb","5635b292d209b50d0031dfcc","5635b292d209b50d0031dfcd","5635b292d209b50d0031dfce","5635b292d209b50d0031dfcf","5635b292d209b50d0031dfd0"],"project":"550a7754635c660d0052808e","__v":1,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-06-11T00:04:28.030Z","from_sync":false,"order":1,"slug":"using-telescope","title":"Using Telescope"},"project":"550a7754635c660d0052808e","githubsync":"","__v":0,"user":"5469e5dfa3b67a0e00559b06","version":{"_id":"5635b290d209b50d0031dfc4","__v":1,"project":"550a7754635c660d0052808e","createdAt":"2015-11-01T06:34:56.868Z","releaseDate":"2015-11-01T06:34:56.868Z","categories":["5635b291d209b50d0031dfc5","5635b291d209b50d0031dfc6","5635b291d209b50d0031dfc7","5635b291d209b50d0031dfc8","5635b291d209b50d0031dfc9","5635b291d209b50d0031dfca"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.25.0","version":"0.25"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-06-04T01:47:36.595Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":9,"body":"Telescope features a simple yet powerful email template system that automatically themes all outgoing emails with your app's colors and branding. \n\nNote that this section refers specifically to sending in-app emails like notifications and password resets. For the newsletter, refer to the [Sending Newsletters](doc:sending-newsletters) section.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Email Terminology\"\n}\n[/block]\nWeb apps can generally send three distinct types of emails: **transactional emails**, **behavioral emails**, and **mass emails**. \n\n**Transactional emails** are one-off, single-recipient emails for things like notifications, invitations, or password resets, and are sent immediately after a user performs an action.\n\n**Behavioral emails** are triggered by specific events, but are not necessarily sent immediately after the event. A common example would be automatically emailing users when they haven't been active on your site for over a week. Note that Telescope does not currently handle any behavioral emails. \n\nFinally, **mass emails** or **email campaigns** are emails you send to a list of multiple users, such as daily or weekly newsletters for example. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Email Setup\"\n}\n[/block]\nIf you host your app on Meteor.com, transactional emails (notifications, password reset, etc.) should work out of the box. \n\nIf not, you'll need to configure `MAIL_URL`, either through an environment variable (specified in your `mup.json` file for example) or through the Telescope settings panel. \n\nYour `MAIL_URL` should be of the form:\n\n`smtp://username:password:::at:::host:port/`\n\nFor example:\n\n`smtp://postmaster%40telescope.mailgun.org:238hdh2dx@smtp.mailgun.org:587/`\n\n**Troubleshooting**\n\n- Note that if your username contains an `@` sign, you'll have to replace it with `%40`. \n- Make sure to include the trailing `/` in your URL. \n- Do not use Gmail as your email provider. We recommend [Mailgun](http://www.mailgun.com/) instead. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Testing Email\"\n}\n[/block]\nYou can fire off a test email by logging in as an admin and calling `Meteor.call('testEmail')` in your browser console.\n\nNote that emails are sent on the server. So if you run into any issues, the relevant error will be displayed in your server logs, not in the browser console. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Email Templates\"\n}\n[/block]\nThe [emailWrapper](https://github.com/TelescopeJS/Telescope/blob/master/packages/telescope-email/lib/server/templates/emailWrapper.handlebars) template contains the main email wrapper that will enclose all outgoing emails. This template is responsible for styling, which means you only need so specify the body contents of the emails you want to send. \n\nFor example, this is what the [account approved email template](https://github.com/TelescopeJS/Telescope/blob/master/packages/telescope-email/lib/server/templates/emailAccountApproved.handlebars) looks like:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<span class=\\\"heading\\\">{{username}}, welcome to {{siteTitle}}!</span><br><br>\\n\\nYou've just been invited. <a href=\\\"{{siteUrl}}\\\">Start posting</a>.<br><br>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nSince Telescope's email templates use the [handlebars-server](https://github.com/EventedMind/meteor-handlebars-server) package, you can create them using the same Handlebars syntax you're already familiar with. \n\nYou can read more about customizing email templates in the [Custom Templates](doc:custom-templates) section.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"CSS Inlining & Text Emails\"\n}\n[/block]\nTelescope will automatically inline all CSS found in a template. This means you can style each email template separately if you need to. For example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<style>\\n  .heading{\\n    color: green;\\n  }\\n</style>\\n\\n<span class=\\\"heading\\\">\\n  {{username}}, welcome to {{siteTitle}}!\\n</span><br><br>\\n\\nYou've just been invited. \\n<a href=\\\"{{siteUrl}}\\\">Start posting</a>.\\n<br><br>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nAdditionally, Telescope will also generate text versions of your emails for you.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Sending Email\"\n}\n[/block]\nTo send an email, you can use the `Telescope.email.buildAndSend` server-side function. It takes 4 arguments:\n\n- `to`: the email address to send to.\n- `subject`: the subject of the email.\n- `template`: the name of the handlebars template to use.\n- `properties`: an object containing the properties to use inside the template.\n\nFor example, assuming you have an `emailWelcome.handlebars` server-side template:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var user = {\\n  firstName: 'Liam',\\n  lastName: 'Neeson',\\n  setOfSkills: 'special',\\n  email: 'liamneeson@gmail.com'\\n}\\nvar subject = \\\"Welcome to Telescope, \\\" + user.firstName;\\nTelescope.email.buildAndSend(user.email, subject, 'emailWelcome', user);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Test Routes\"\n}\n[/block]\nIf you want to test your email templates without having to manually trigger events every time, you can preview them at the following routes:\n\n- **Notifications**: [/email/notification/:notificationId](http://localhost:3000/email/notification/:notificationId)\n- **New User Created**: [/email/new-user/:userId](http://localhost:3000/email/new-user/:userId)\n- **New Post**: [/email/new-post/:postId](http://localhost:3000/email/new-post/:postId)\n- **Post Approved**: [/email/post-approved/:postId](http://localhost:3000/email/post-approved/:postId)\n- **New Comment**: [/email/new-comment/:commentId](http://localhost:3000/email/new-comment/:commentId)\n- **New Reply**: [/email/new-reply/:commentId](http://localhost:3000/email/new-reply/:commentId)\n- **Account Approved**: [/email/account-approved/:userId](http://localhost:3000/email/account-approved/:userId)\n- **Newsletter Campaign**: [/email/campaign](http://localhost:3000/email/campaign)\n\nIn each case, replace the `:id` parameter with the object's actual `_id`. So for the first route, you'd find any notification in your database and replace `:notificationId` with its `_id` property.","excerpt":"","slug":"email","type":"basic","title":"Sending Emails"}
Telescope features a simple yet powerful email template system that automatically themes all outgoing emails with your app's colors and branding. Note that this section refers specifically to sending in-app emails like notifications and password resets. For the newsletter, refer to the [Sending Newsletters](doc:sending-newsletters) section. [block:api-header] { "type": "basic", "title": "Email Terminology" } [/block] Web apps can generally send three distinct types of emails: **transactional emails**, **behavioral emails**, and **mass emails**. **Transactional emails** are one-off, single-recipient emails for things like notifications, invitations, or password resets, and are sent immediately after a user performs an action. **Behavioral emails** are triggered by specific events, but are not necessarily sent immediately after the event. A common example would be automatically emailing users when they haven't been active on your site for over a week. Note that Telescope does not currently handle any behavioral emails. Finally, **mass emails** or **email campaigns** are emails you send to a list of multiple users, such as daily or weekly newsletters for example. [block:api-header] { "type": "basic", "title": "Email Setup" } [/block] If you host your app on Meteor.com, transactional emails (notifications, password reset, etc.) should work out of the box. If not, you'll need to configure `MAIL_URL`, either through an environment variable (specified in your `mup.json` file for example) or through the Telescope settings panel. Your `MAIL_URL` should be of the form: `smtp://username:password@host:port/` For example: `smtp://postmaster%40telescope.mailgun.org:238hdh2dx@smtp.mailgun.org:587/` **Troubleshooting** - Note that if your username contains an `@` sign, you'll have to replace it with `%40`. - Make sure to include the trailing `/` in your URL. - Do not use Gmail as your email provider. We recommend [Mailgun](http://www.mailgun.com/) instead. [block:api-header] { "type": "basic", "title": "Testing Email" } [/block] You can fire off a test email by logging in as an admin and calling `Meteor.call('testEmail')` in your browser console. Note that emails are sent on the server. So if you run into any issues, the relevant error will be displayed in your server logs, not in the browser console. [block:api-header] { "type": "basic", "title": "Email Templates" } [/block] The [emailWrapper](https://github.com/TelescopeJS/Telescope/blob/master/packages/telescope-email/lib/server/templates/emailWrapper.handlebars) template contains the main email wrapper that will enclose all outgoing emails. This template is responsible for styling, which means you only need so specify the body contents of the emails you want to send. For example, this is what the [account approved email template](https://github.com/TelescopeJS/Telescope/blob/master/packages/telescope-email/lib/server/templates/emailAccountApproved.handlebars) looks like: [block:code] { "codes": [ { "code": "<span class=\"heading\">{{username}}, welcome to {{siteTitle}}!</span><br><br>\n\nYou've just been invited. <a href=\"{{siteUrl}}\">Start posting</a>.<br><br>", "language": "html" } ] } [/block] Since Telescope's email templates use the [handlebars-server](https://github.com/EventedMind/meteor-handlebars-server) package, you can create them using the same Handlebars syntax you're already familiar with. You can read more about customizing email templates in the [Custom Templates](doc:custom-templates) section. [block:api-header] { "type": "basic", "title": "CSS Inlining & Text Emails" } [/block] Telescope will automatically inline all CSS found in a template. This means you can style each email template separately if you need to. For example: [block:code] { "codes": [ { "code": "<style>\n .heading{\n color: green;\n }\n</style>\n\n<span class=\"heading\">\n {{username}}, welcome to {{siteTitle}}!\n</span><br><br>\n\nYou've just been invited. \n<a href=\"{{siteUrl}}\">Start posting</a>.\n<br><br>", "language": "html" } ] } [/block] Additionally, Telescope will also generate text versions of your emails for you. [block:api-header] { "type": "basic", "title": "Sending Email" } [/block] To send an email, you can use the `Telescope.email.buildAndSend` server-side function. It takes 4 arguments: - `to`: the email address to send to. - `subject`: the subject of the email. - `template`: the name of the handlebars template to use. - `properties`: an object containing the properties to use inside the template. For example, assuming you have an `emailWelcome.handlebars` server-side template: [block:code] { "codes": [ { "code": "var user = {\n firstName: 'Liam',\n lastName: 'Neeson',\n setOfSkills: 'special',\n email: 'liamneeson@gmail.com'\n}\nvar subject = \"Welcome to Telescope, \" + user.firstName;\nTelescope.email.buildAndSend(user.email, subject, 'emailWelcome', user);", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Test Routes" } [/block] If you want to test your email templates without having to manually trigger events every time, you can preview them at the following routes: - **Notifications**: [/email/notification/:notificationId](http://localhost:3000/email/notification/:notificationId) - **New User Created**: [/email/new-user/:userId](http://localhost:3000/email/new-user/:userId) - **New Post**: [/email/new-post/:postId](http://localhost:3000/email/new-post/:postId) - **Post Approved**: [/email/post-approved/:postId](http://localhost:3000/email/post-approved/:postId) - **New Comment**: [/email/new-comment/:commentId](http://localhost:3000/email/new-comment/:commentId) - **New Reply**: [/email/new-reply/:commentId](http://localhost:3000/email/new-reply/:commentId) - **Account Approved**: [/email/account-approved/:userId](http://localhost:3000/email/account-approved/:userId) - **Newsletter Campaign**: [/email/campaign](http://localhost:3000/email/campaign) In each case, replace the `:id` parameter with the object's actual `_id`. So for the first route, you'd find any notification in your database and replace `:notificationId` with its `_id` property.