Quickstart - Sending emails from custom domain

In this quickstart you'll create an endpoint on your web server at <yourdomain>.com/email_webhook. When you're finished UserKit will be able to make requests to your server at that endpoint whenever it needs to have an email sent out.

1. Create a webhook endpoint on your server

On your server, create an endpoint for the following url: /email_webhook. Whenever UserKit needs to send an email it will make a POST request to that endpoint containing the following JSON in the request body:

{
	"email_key": "eml_MgXuRwRr0hIX-JSHgzKetRJGOv5qB5"
}

In this example we'll be using mailgun to send the email. Here's a function which handles requests to the /email_webhook endpoint. It get's the email data using the email_key UserKit sends in the request body:

import json
import requests
import userkit

uk = userkit.UserKit("<YOUR_APP_SECRET_KEY>")


# This function handles requests to /email_webhook
def email_handler(request, response):
  json_body = json.loads(request.body)
  email_key = json_body['email_key']
  
  # Fetch the actual email data UserKit wants to have sent
  email = uk.emails.get_pending_email(email_key)
  if not email:
    # Something is wrong with the email (it may have been sent
    # already, or this may be a malicious request). Abort.
    response.set_status(400)
    return

  # Send the email
  resp = send_email(email)
  
  if resp.status_code == 200:
    # Notify UserKit that everything went well
    response.set_status(200)
  else:
    # Something went wrong
    response.set_status(500)

    
def send_email(email):
  # Send the email using MailGun. Remember to replace
  # <YOUR_EMAIL_DOMAIN_NAME>, <YOUR_MAILGUN_API_KEY> and
  # <YOUR_EMAIL@YOUR_DOMAIN.COM>
  return requests.post(
    'https://api.mailgun.net/v3/<YOUR_EMAIL_DOMAIN_NAME>/messages',
    auth=('api', '<YOUR_MAILGUN_API_KEY>'),
    data={'from': '<YOUR_EMAIL@YOUR_DOMAIN.COM>,
      		'to': email.to,
      		'subject': email.subject,
      		'text': email.body})

<?php

$uk = new UserKit('<YOUR_APP_SECRET_KEY>');

// Portions of following snippet are pseudo code
// This function handles requests to /email_webhook
function email_handler($request, $response)
{
  global $uk;

  // convert the body response to a json array type 
  $json_body = json_decode($response->body, true);

  $email_key = $json_body['email_key'];
  
  // Fetch the actual email data UserKit wants to have sent
  $email = $uk->emails->getPendingEmail($email_key);
  if (!$email)
  {
    // Something is wrong with the email (it may have been sent
    // already, or this may be a malicious request). Abort.
    $response->set_status(400);
    return;
  }
  
  // Send the email
  $resp = send_email($email);
  
  if($resp->status_code == 200)
  {
    // Notify UserKit that everything went well
    $response->set_status(200);
  }
  else
  {
    // Something went wrong
    $response->set_status(500);
  }
}

function send_mail($email)
{
  // Send the email using MailGun. Remember to replace
  // <YOUR_EMAIL_DOMAIN_NAME>, <YOUR_MAILGUN_API_KEY> and
  // <YOUR_EMAIL@YOUR_DOMAIN.COM>

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, 'api:' . <YOUR_MAILGUN_API_KEY>);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
  curl_setopt($ch, CURLOPT_URL, 'https://api.mailgun.net/v2/' . <YOUR_EMAIL_DOMAIN_NAME> .'/messages');
  curl_setopt($ch, CURLOPT_POSTFIELDS, array(
    'from' => 'Open ' . '<YOUR_EMAIL@YOUR_DOMAIN.COM>',
    'to' => $email,
    'subject' => $email->subject,
    'html' => $email->body
  ));

  $result = curl_exec($ch);
  curl_close($ch);
  return $result;
}

2. Tell UserKit where your email endpoint is

In the UserKit dashboard select your app, then go to settings and in Email webhook enter the full URL to the endpoint you created in step 1. For example, https://.com/email_webhook.