Setup Transactional Emails

A great path to start using OneSignal Email Messaging is to begin delivering transactional emails (such as welcome emails, password resets, etc) through OneSignal. This offers a few key benefits:

  1. You can easily track delivery, click, and open statistics on your transactional emails from the OneSignal Dashboard, alongside your push notifications and marketing emails.

  2. If you don't yet use an email service provider for these emails, you gain the benefit of increased deliverability and reliability of an email service provider without the headache of adding another dependency and API in your app.

  3. You can create great-looking, cross-platform email templates within the OneSignal Dashboard and use them to send personalized transactional emails.

Migrate your existing transactional emails

You can easily migrate your existing transactional email templates for delivery in OneSignal by sending them through the OneSignal API. Most backends (e.g. rails, node) use some form of basic emailer service that you can swap out for delivery through the OneSignal API. Below is sample API code you can use to send an existing HTML transactional email:

params = {
  "app_id" => "5eb5a37e-b458-11e3-ac11-000c2940e62c", 
  "email_subject" => "Welcome to Cat Facts!",
  "email_body" => "<html><head>Welcome to Cat Facts</head><body><h1>Welcome to Cat Facts<h1><h4>Learn more about everyone's favorite furry companions!</h4><hr/><p>Hi Nick,</p><p>Thanks for subscribing to Cat Facts! We can't wait to surprise you with funny details about your favorite animal.</p><h5>Today's Cat Fact (March 27)</h5><p>In tigers and tabbies, the middle of the tongue is covered in backward-pointing spines, used for breaking off and gripping meat.</p><a href='https://catfac.ts/welcome'>Show me more Cat Facts</a><hr/><p><small>(c) 2018 Cat Facts, inc</small></p><p><small><a href='[unsubscribe_url]'>Unsubscribe</a></small></p></body></html>",
  "include_player_ids" => ["6392d91a-b206-4b7b-a620-cd68e32c3a76"],
}
uri = URI.parse('https://onesignal.com/api/v1/notifications')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path,
                              'Content-Type'  => 'application/json;charset=utf-8',
                              'Authorization' => "Basic NGEwMGZmMjItY2NkNy0xMWUzLTk5ZDUtMDAwYzI5NDBlNjJj")
request.body = params.as_json.to_json
response = http.request(request) 
puts response.body
import requests
import json

header = {"Content-Type": "application/json; charset=utf-8",
          "Authorization": "Basic NGEwMGZmMjItY2NkNy0xMWUzLTk5ZDUtMDAwYzI5NDBlNjJj"}

payload = {"app_id": "5eb5a37e-b458-11e3-ac11-000c2940e62c",
           "include_player_ids": ["6392d91a-b206-4b7b-a620-cd68e32c3a76"],
           "email_subject": "Welcome to Cat Facts!",
           "email_body": "<html><head>Welcome to Cat Facts</head><body><h1>Welcome to Cat Facts<h1><h4>Learn more about everyone's favorite furry companions!</h4><hr/><p>Hi Nick,</p><p>Thanks for subscribing to Cat Facts! We can't wait to surprise you with funny details about your favorite animal.</p><h5>Today's Cat Fact (March 27)</h5><p>In tigers and tabbies, the middle of the tongue is covered in backward-pointing spines, used for breaking off and gripping meat.</p><a href='https://catfac.ts/welcome'>Show me more Cat Facts</a><hr/><p><small>(c) 2018 Cat Facts, inc</small></p><p><small><a href='[unsubscribe_url]'>Unsubscribe</a></small></p></body></html>" }
 
req = requests.post("https://onesignal.com/api/v1/notifications", headers=header, data=json.dumps(payload))
 
print(req.status_code, req.reason)
var sendNotification = function(data) {
  var headers = {
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": "Basic NGEwMGZmMjItY2NkNy0xMWUzLTk5ZDUtMDAwYzI5NDBlNjJj"
  };
  
  var options = {
    host: "onesignal.com",
    port: 443,
    path: "/api/v1/notifications",
    method: "POST",
    headers: headers
  };
  
  var https = require('https');
  var req = https.request(options, function(res) {  
    res.on('data', function(data) {
      console.log("Response:");
      console.log(JSON.parse(data));
    });
  });
  
  req.on('error', function(e) {
    console.log("ERROR:");
    console.log(e);
  });
  
  req.write(JSON.stringify(data));
  req.end();
};

var message = { 
  app_id: "5eb5a37e-b458-11e3-ac11-000c2940e62c",
  "include_player_ids": ["6392d91a-b206-4b7b-a620-cd68e32c3a76"],
  "email_subject": "Welcome to Cat Facts!",
  "email_body": "<html><head>Welcome to Cat Facts</head><body><h1>Welcome to Cat Facts<h1><h4>Learn more about everyone's favorite furry companions!</h4><hr/><p>Hi Nick,</p><p>Thanks for subscribing to Cat Facts! We can't wait to surprise you with funny details about your favorite animal.</p><h5>Today's Cat Fact (March 27)</h5><p>In tigers and tabbies, the middle of the tongue is covered in backward-pointing spines, used for breaking off and gripping meat.</p><a href='https://catfac.ts/welcome'>Show me more Cat Facts</a><hr/><p><small>(c) 2018 Cat Facts, inc</small></p><p><small><a href='[unsubscribe_url]'>Unsubscribe</a></small></p></body></html>"
};

sendNotification(message);

In every email you send, you must include an unsubscribe link. You can insert this by adding [unsubscribe_url] in a link within your emails.


Create new transactional email templates

OneSignal supports the ability to create email templates in the OneSignal Dashboard that you can use to send personalized transactional emails. This will give you greater visibility into and control over your transactional emails for several reasons:

  1. Templates can be easily modified directly from the OneSignal Dashboard, so you won't have to edit code each time you want to make a change.

  2. OneSignal's template editor takes care of cross-platform compatibility automatically, so you won't have to worry about how your emails look on different email clients.

  3. Just like push templates, you can get aggregate statistics on email templates, so you won't have to instrument your emails or dive into yet another analytics package to see how each transactional email is performing.

params = {
  "app_id" => "5eb5a37e-b458-11e3-ac11-000c2940e62c",
  "template_id" => "e59b3a5e-ccc4-44ff-b39e-aa4c668fe6c1",
  "include_player_ids" => ["6392d91a-b206-4b7b-a620-cd68e32c3a76"],
  "email_subject" => "Your Email Subject"
}
uri = URI.parse('https://onesignal.com/api/v1/notifications')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path,
                              'Content-Type'  => 'application/json;charset=utf-8',
                              'Authorization' => "Basic NGEwMGZmMjItY2NkNy0xMWUzLTk5ZDUtMDAwYzI5NDBlNjJj")
request.body = params.as_json.to_json
response = http.request(request) 
puts response.body
{
  "app_id": "YOUR_ONESIGNAL_APP_ID",
  "include_player_ids": ["6392d91a-b206-4b7b-a620-cd68e32c3a76"],
  "email_subject": "Your Email Subject",
  "template_id": "e59b3a5e-ccc4-44ff-b39e-aa4c668fe6c1"
}