This post is written by Kevin Wang, Chief Instructor at Tealeaf Academy. Tealeaf Academy is an online school for developers, and offers intensive, project based online bootcamps on web development. If you think this post is useful, you should check them out!

At Tealeaf Academy, creating a “Study Together, Progress Together” experience for our students is at core of our way of teaching.  One of our core tools is the discussion board where students ask questions, share ideas, collaborate on homework assignments, and teachers quickly jump in to help students get unstuck on problems. One of our recent priorities was to reduce friction in discussion board usage and encourage more discussions with a complementary email notification and a “reply-to email to post on discussion board” workflow.  Once we implemented the below code using the Mailgun Routes API, activity on our discussion board increased three fold, and questions are now typically getting answered within an hour, sometimes even minutes, and students are able to move on the next set of tasks a lot quicker. Here’s how we did it:

Our workflow would go as the following:

1. When a post (most likely, a question) is created, all course participants are notified by email notification
2. Course participants can reply to the email notifications directly from their email inbox, without having to sign into the course
3. That reply will be posted on the online discussion board, and are also sent to other course participants, to keep the conversation going.

Why we choose Mailgun

The key piece of this workflow is to receive and parse inbound email messages. We looked around for several email service providers, and in the end picked Mailgun because:

1. It is very developer friendly - We are developers, and Mailgun speaks to us. The APIs expose a lot of low level options that allows tweaking. We like the Routes in particular - It’s a nice layer of abstraction that makes integration with apps very easy. (see how we use it below)
2. It is the most feature complete service we have found - we can use Mailgun for transactional emails, campaigns as well as email lists - it’s nice to have just one service provider to handle everything we need.
3. The price is reasonable and the upgrading path to dedicated IP and custom DKIM is nice, even we do not need it yet.
4. The support is top notch. There is a live chat that I can talk to their developers directly on issues and it has been very useful for us to get issues resolved.

Setting up the email infrastructure

• The first step was to create a new domain on Mailgun. In our case, it’s messaging.gotealeaf.com which we use for sending and receiving emails.
• Next, we created a MailgunGateway as our wrapper for Mailgun’s API. This wrapper takes care of all our interactions with Mailgun through our account. Here we use Mailgun’s send_batch_messages API to send HTML emails. It allows us to send a message to multiple receivers with a single API call. We keep our API key as environment variables on the server for extra security. There is also a simple delivery filter such that no emails are sent in the development environment; On staging, all emails are sent to Chris (my co-founder) and myself, so we can test out things without fearing to spam our users; Only on the production environment emails are sent to real users.

class MailgunGateway
 def send_batch_message(options={})
 RestClient.post(messaging_api_end_point,
 from: default_sender,
 to: delivery_filter(options[:to]),
 subject: options[:subject],
 html: options[:body],
 :"h:Reply-To" => options[:reply_to],
 :"recipient-variables" => options[:recipient_variables]
 ) if Rails.env.staging? || Rails.env.production?
 end
 end
 private
 def default_sender
 "Tealeaf Academy "
 end
 def api_key
 @api_key ||= ENV['mailgun_api_key']
 end
 def messaging_api_end_point
 @messaging_api_end_piont ||= "https://api:#{api_key}@api.mailgun.net/v2/messaging.gotealeaf.com/messages"
 end
 def delivery_filter(emails)
 Rails.env.production? ? emails : "kevin@gotealeaf.com, chris@gotealeaf.com"
 end
end

Add tracking token for posts to identify the “thread” that comments should be collated to

Every post carries a tracking token, which will be included in the “Reply-To” header in the email to collate inbound email replies to the corresponding thread.  This method makes it very easy to post the correct reply to the correct thread.

class Post < ActiveRecord::Base
 include Tokenable
 belongs_to :user
 belongs_to :course
 has_many :comments, order: "created_at ASC", dependent: :destroy
 ...
end
module Tokenable
 extend ActiveSupport::Concern
 included do
 after_create do
 self.token = Digest::MD5.hexdigest(Time.now.to_s.split(//).sort_by {rand}.join).first(8)
 self.save
 end
 end
end
class Comment < ActiveRecord::Base
 belongs_to :user
 belongs_to :post, touch: true
 delegate :token, to: :post
 def commenter_name
 user.name
 end
end

Send email notifications for new post or comment

Once a post or comment is created, we send an email notification to all course participants. We are sending emails synchronously for now, but as we have more users, we’ll probably want to offload this to a background job.

class Courses::PostsController < AuthenticatedController
 expose(:course)
 expose(:posts) { course.posts }
 expose(:post)
 def create
 post.user = current_user
 post.save
 CourseNotifier.new(course).notify_course_participants_on_new_discussion(post)
 redirect_to course_home_path(course)
 end
 ...
end
class Courses::Posts::CommentsController < AuthenticatedController
 expose(:course)
 expose(:posts) { course.posts }
 expose(:post)
 expose(:comments) { post.comments }
 expose(:comment)
 def create
 comment.user = current_user
 comment.save
 CourseNotifier.new(course).notify_course_participants_on_new_discussion(comment)
 redirect_to course_home_path(course)
 end
 ...
end

The CourseNotifier is the class where we put our application specific logic on notifications. Note that MailgunGateway is injected in as the default gateway - this is from when we used to have multiple email service providers for campaigning, lists and transactional emails. It is less of a need now that we consolidated all email delivery needs to Mailgun!

class CourseNotifier
 attr_reader :course, :gateway
 def initialize(course, gateway=MailgunGateway.new)
 @course = course
 @gateway = gateway
 end
 def notify_course_participants_on_new_discussion(discussion)
 gateway.send_batch_message(
 to: notification_recipients(discussion).map(&:email).join(", "),
 subject: notification_subject(discussion),
 body: discussion_notification_text(discussion),
 reply_to: reply_to_address(discussion),
 recipient_variables: recipient_variables(
 notification_recipients(discussion)
 )
 )
 end
 ...
 private
 def notification_recipients(discussion)
 course.participants.reject {|participant| participant.email == discussion.user.email }
 end
 def notification_subject(discussion)
 discussion.is_a?(Post) ?
 "[Tealeaf Academy] #{discussion.user.name} Posted a New Message on the Discussion Board" :
 "[Tealeaf Academy] #{discussion.user.name} Replied to a Message on the Discussion Board"
 end
 def reply_to_address(discussion)
 "reply+#{discussion.token}@messaging.gotealeaf.com"
 end
 def recipient_variables(recipients)
 vars = recipients.map do |recipient|
 "\"#{recipient.email}\": {\"name\":\"#{recipient.name}\"}"
 end
 "{#{vars.join(', ')}}"
 end
 def discussion_notification_text(discussion)
<<-EMAIL
<html><body>
Hi %recipient.name%,
<p>#{discussion.user.name} says on the course dicussion board:</p>
"#{discussion.text}"
<br/>
<p>Reply to this email directly or <a href="http://www.gotealeaf.com/courses/#{course.slug}/home">view it on the discussion board</a></p>
</body></html>
EMAIL
 end
end

The reply_to_address is where we insert the post token into the “Reply-To” header. The content of the emails are quite simple so we just put them here in the class. If we had a more elaborate email style, we would have used template rendering to handle it. With Mailgun’s send_batch_message API, we can call the API just once to send to multiple recipients, and the recipient_variables method is where we customize email messages for each receiver to include their names to add a personal touch.

Handling inbounding messages in the application

Heading over to Mailgun, under “Routes” in the Control Panel, we created a route as the following:

• Filter Expression: match_recipient(“reply\+(.*)@messaging.gotealeaf.com”)
• Action: forward(“http://www.gotealeaf.com/api/incoming_messages/?post_token=\1”)

When a user replies to an email, they reply it to an email address such as “reply+fj42gq4v@messaging.gotealeaf.com”, and this route will forward the email to a web hook that we expose to handle incoming messages.

class Api::IncomingMessagesController < ApplicationController
 skip_before_filter :verify_authenticity_token
 def create
 user = User.where(email: params['sender']).first
 post = Post.where(token: params['post_token']).first
 text = params["stripped-text"]
 if post && user && text.present?
 comment = post.comments.create(user: user, text: text)
 CourseNotifier.new(post.course).notify_course_participants_on_new_discussion(comment)
 end
 head(200)
 end
end

Here, we use the sender’s email to find the author, and use the post token to find the post that this reply should be collated under. Mailgun gives us the very useful stripped text which strips away the original message part to only contain the actual reply! In the end, we return a 200 header to tell Mailgun that this interaction is successful, otherwise Mailgun will think our server is down and will faithfully keep trying to call our webhook.

The result from implementing this workflow is impressive - activity on our discussion board increased three fold, and questions are now typically getting answered within an hour, sometimes even minutes, students are able to move on the next set of tasks a lot quicker and we are very happy how this turned out.

Facebook is one of the best at turning new users into active users. With 1/6th of the world a Facebook user, Facebook has set a high bar for activation and its team is rapidly spreading the gospel of growth (here are some notes on Facebook’s overall growth strategy from the Growth Hacker’s Conference). 

Every good activation strategy optimizes the new user experience (“NUX”) to reach the “magic moment” as fast as possible. The “magic moment” is a point in the NUX when a user surpasses a metric and is far more likely to be retained. This metric varies from product to product. For Facebook, the magic moment is seven friends in ten days for a new user. 

In the following paragraphs, I will break out Facebook’s on-boarding and activation strategy to see how they motivate new users to reach the magic moment as fast as possible. 

The signup Facebook landing page is straight forward and contains a naked long signup form. Most inbound marketers and product gurus would probably revolt if this was their landing page. The form feels long. There is no compelling call-to-action and the design is uninspiring. 

Despite the landing page’s rough appearance, Facebook has an advantage that other startups do not have: a household name. Most likely, the majority of Facebook’s new users are converting through a user-to-user action and not through the above landing page. Any visitor that stumbles onto this landing page has already been primed by Facebook’s billion active user base. 

The focus of this landing page is the login form via top-right of the page. When a visitor lands on this page, the cursor moves to the email submission field in the login form. This cursor movement denotes that this landing page is designed to convert users not visitors to a action (to log in not to signup).

If a visitor does convert into a new user from this landing page, they will enter a robust on-boarding flow. After a visitor fills out the naked form, the next ask in the funnel is to search your address book to find email addresses that matches a Facebook user’s email address. 

In a clever UX move, Facebook passes the email address from the previous step and places the address in the relevant email hosting service. For example, I signed up with GMail thus, Facebook placed my email in the GMail address book search. All it takes is one click to search. The call-to-action to search uses the phrase “Find Friends” which is mentally in-line with the purpose of the page. 

As a tidbit, take a look at the use of the phrase “Save and Continue” as the progress button. In the far right, the normal Facebook avatar appears as if you were an active user. This word choice and the avatar sends a sense of ownership in the NUX.

If the search fails, an infographic appears that explains how to manually upload a file of emails. 

Since the GMail account I was using to register did not have any contacts, Facebook did not pull in a list of suggested friends in the following step of the flow. If I did have an address book full of contacts, Facebook would immediately suggest possible friends to ask to be their friend.

Rather than displaying “No friends on Facebook” (because that just sounds lame and lonely), Facebook moves on to the next step to recommend friends based upon more targeted data. 

Based upon a new user’s networks and general demographic information, Facebook suggests possible friends in the following flow. In example below, I submitted Princeton as my school network and received the following friend results.

As opposed to shooting from the hip with the cheap data from the landing page, Facebook gathers more information from a new user who does not have an address book  to produce relevant suggestions. The most pressing goal in activation is to form connections on Facebook as fast as possible. Irrelavant or zero friend suggestions sends negative feedback to a new user. A new user will probably think in their mind, “None of my friends are on here. Why should I be on here then?”.

After adding a profile photo (which is very important for retention), the on-boarding process places a new user in Facebook’s core product with some growth tweaks. Facebook alters the experience to drive home to the magic moment: seven friends in ten days.

The step-by-step guide proceeding the on-boarding flow walks a new user through the privacy settings on posting and adding friends. On the top right bar next to the user’s avatar, a “Find Friends” call-to-action is added. The inherently distracting chat screen and mini-facebook are minimized.

By selecting “Home”, Facebook’s ad bar is removed and replaced with a “People You May Know” suggestion box. The UI has a larger than normal call-to-action and user photo when compared to a retained Facebook user’s friend suggestions UI. It is more important for a new user to add friends now, rather than later. 

Facebook also uses feature call outs to educate a new user. These features also have a retention focus. For example, Facebook called out a Princeton Facebook group and auto opted me into the group. I identified Princeton as my university in on-boarding. I guess Facebook has not strayed far away from the importance of college connections in activation.  

The “Find Friends” button in the top bar links to an in-product email address book search that is similar to the one found in the on-boarding process. 

Facebook expands the number of channels a new user can search for existing friend on Facebook, even including Skype as an option to search. In this flow, the right side bar is removed and replaced with motivational text to reduce distractions.

When a new user returns to Facebook, the newsfeed is re-structured with friend suggestions, probably until that magic number is reached. At this point in the screenshot below, “Becca” (my new user) is several weeks old with three friends in non-concentric networks. Notice the additional motivational text of using my existing friend network to form connections. Facebook is using social recollection to encourage you to connect by narrowing the possibilities. 

Timeline also includes a “People You May Know” box at the top.

Despite the number of scenarios, the on-boarding and activation flow have a single focus: get you to form connections on Facebook as fast as possible. Once those connections are formed on Facebook, Facebook uses email notifications and social exhaust from your friend network to pull you back into the service. Their strategy is thoughtful and very detailed. This is what it takes to get to a billion users in less than a decade.