Sendmarc partner scoring widget setup guide

This article provides instructions on how to create and setup the Sendmarc Partner Scoring Widget on your website.

 Sections in the article:

Set up your scoring widget

Here are the steps needed:

  • Step 1: Get your unique widget identifier/token
  • Step 2: Embed the script code on your website
  • Step 3: Create the form

Step 1: Get your unique widget identifier/token


Your widget has a unique identifier code (widget token) that is tied into your account on the Partner Portal and to the website that you choose to embed it on. All submissions will be available on the Partner Portal and each submission will also be sent via an email notification to an email address or addresses that you specify. For this reason, you need to set up your widget token first, which will look something like this:

5de3f4d0-c5br-4f6d-bf14-98ab790b3df1

To create your widget token, follow these 5 steps below:

NB: Log into your account on the partner portal.

1.1. Go to the “Partners” tab located on the left navigation.

Partner-Tab

1.2. Choose which partner you would like to create a widget for and click the pencil (edit) icon on the right:

Partner-Edit

1.3. Click the “Widget” button and a modal will open on the right of the screen. Select the “Create One?” link:

Create-One

1.4. Add the relevant domain name in the text field and the email address/es where you would like the submission notifications to be sent to. Click the “+” (add) icon after each entry to capture the data. You can add more than one email address for notifications. Click save.

Add-Domain-and-email

1.5. Your widget token will appear above on the same modal. You can copy and paste this from here to use when setting up your scoring widget on a website or landing page. You can always find the token here if needed.

Token

Step 2: Embed the widget script code on your website

Once you have your unique widget token, you can then embed the widget code in your site. The widget script code is given below. 

Copy this code and paste it in the page on your site where you wish the widget to appear. Replace the text WIDGET-IDENTIFIER-GOES-HERE with your unique widget identifier/token. You can also change the config variable to change how you wish the widget to show on your site, as well as to match the styling of your site. The configuration options are detailed at the end of this article.

<script>

(function(w, d, s, o, f, js, fjs) {

w['SendmarcWidget'] = o;

w[o] = w[o] || function() {

(w[o].q = w[o].q || []).push(arguments)

};

js = d.createElement(s), fjs = d.getElementsByTagName(s)[0];

js.id = o;

js.src = f;

js.async = 1;

fjs.parentNode.insertBefore(js, fjs);

}(window, document, 'script', 'smConfig', 'https://madox.sendmarc.com/widget.js'));

const params = new URLSearchParams(window.location.search);


// The config below is an example that you can use to get started. Change any of the configuration options below to style the widget according to your site

config = {


  target: 'sendmarc-widget-form',
  placement: 'modal',
  modelWidth: '450px',
  styles: {
      success: {
          primary: '#16a34a',
          secondary: '#86efac',
          icon: 'M4.5 12.75l6 6 9-13.5',
          },
      warning: {
          primary: '#ca8a04',
          secondary: '#fde047',
          icon: 'M14.857 17.082a23.848 23.848 0 005.454-1.31A8.967 8.967 0 0118 9.75v-.7V9A6 6 0 006 9v.75a8.967 8.967 0 01-2.312 6.022c1.733.64 3.56 1.085 5.455 1.31m5.714 0a24.255 24.255 0 01-5.714 0m5.714 0a3 3 0 11-5.714 0M3.124 7.5A8.969 8.969 0 015.292 3m13.416 0a8.969 8.969 0 012.168 4.5',
          },
       danger: {
           primary: '#dc2626',
          secondary: '#fca5a5',
          icon: 'M6 18L18 6M6 6l12 12',
          },
    },

  call_to_action: {
      title: 'Secure domain now ?',
      href: 'http://sendmarc.com',
      threshold: 4,
      classes: '_sm-call-to-action-button',
  },
}

smConfig('WIDGET-IDENTIFIER-GOES-HERE', config);

</script>

You can use the scoring page on the Sendmarc site as an example of the kind of content that works for a page like this. Example text is given at the end of this article.

Step 3: Create the form

The next step is to create the form on the same page as the code from Step 2. This is the form that will accept an email address and provide a form submit button. You can use the code below.

<form id="sendmarc-widget-form" novalidate>
<input type="email" class="form-control" name="email" placeholder="you@example.com">
<button type="submit"> Check score </button>
</form>

NOTE: keep the form id as shown above.

If you would like to collect additional contact information, you can do so by using additional input fields. The names of the fields that can store and then pass through to you via email are :

  1. first_name,
  2. last_name,
  3. contact_number,
  4. company_name,

A form with all of these could look like this:

<form id="sendmarc-widget-form" novalidate>
<input type="email" class="form-control" name="email" placeholder="you@example.com">
<input type="text" class="form-control" name="first_name" placeholder="First name">
<input type="text" class="form-control" name="last_name" placeholder="Last name">
<input type="text" class="form-control" name="contact_number" placeholder="Contact number">
<input type="text" class="form-control" name="company_name" placeholder="Company name">
<button type="submit"> Check score </button>
</form>

Viewing widget submissions


All submissions through the widget are 

  1. sent via email to the recipients provided in Step 1; and
  2. available to view on Sendmarc's Partner Portal, which can be accessed at partner.sendmarc.com

Widget Configuration


There are numerous ways to style the widget to fit in with the design of your website. These options are given below. 

All config options should be added to the script code from Step 2 where CONFIG-OPTIONS-HERE appears.

Styling


The styles object defines the colors and icons to be used for success, warning, and danger notifications. 

Option Description
success.primary The primary color for success notifications. This color is used for the background color of the notification.
success.secondary The secondary color for success notifications. This color is used for the border color of the notification.
success.icon The icon to use for success notifications.
warning.primary The primary color for warning notifications. This color is used for the background color of the notification.
warning.secondary The secondary color for warning notifications. This color is used for the border color of the notification.
warning.icon The icon to use for warning notifications.
danger.primary The primary color for danger notifications. This color is used for the background color of the notification.
danger.secondary The secondary color for danger notifications. This color is used for the border color of the notification.
danger.icon The icon to use for danger notifications.

Call to action


The call to object defines the options to handle domain score falls below a certain threshold.

Option Description
title A string that represents the title of the call-to-action button that will be displayed to the user. 
href A string that represents the URL to which the call-to-action button will navigate when clicked. 
threshold An integer that represents the email score threshold. If the domain email score falls below this threshold, the call-to-action button will be shown. The threshold is a score out of 5
classes A string that represents the CSS classes to be applied to the call-to-action button.

Widget Placement options

Option Description
placement

This option specifies the placement of the widget scoring results in the form. It can have one of the following values:

modal: The widget scoring results will be displayed as a modal dialog on top of the form.

replace: The widget scoring results will replace the form entirely, taking up the same space.

appends: The widget scoring results will be inserted under the form.

NOTE: you can also set this placement option to the id of any div on your page and it will be appended to that page. For example:

placement: 'widget-scoring-result'

will result in the results being appended to the div with the id of "widget-scoring-result". 

modelWidth This option specifies the width of the widget when it is displayed as a modal dialog
target This option specifies the div that contains the form  to submit the widget submission

Widget Example Configuration


Below is an example of how a configuration might look:

config = {

  target: 'sendmarc-widget-form',
  placement: 'modal',
  modelWidth: '450px',
  styles: {
      success: {
          primary: '#16a34a',
          secondary: '#86efac',
          icon: 'M4.5 12.75l6 6 9-13.5',
          },
      warning: {
          primary: '#ca8a04',
          secondary: '#fde047',
          icon: 'M14.857 17.082a23.848 23.848 0 005.454-1.31A8.967 8.967 0 0118 9.75v-.7V9A6 6 0 006 9v.75a8.967 8.967 0 01-2.312 6.022c1.733.64 3.56 1.085 5.455 1.31m5.714 0a24.255 24.255 0 01-5.714 0m5.714 0a3 3 0 11-5.714 0M3.124 7.5A8.969 8.969 0 015.292 3m13.416 0a8.969 8.969 0 012.168 4.5',
          },
       danger: {
           primary: '#dc2626',
          secondary: '#fca5a5',
          icon: 'M6 18L18 6M6 6l12 12',
          },
    },

  call_to_action: {
      title: 'Secure domain now ?',
      href: 'http://sendmarc.com',
      threshold: 4,
      classes: '_sm-call-to-action-button',
  },
}

Showing the score results on a new page

The widget also allows you to show the results of the scoring on a separate page. To do this, you need to do the following:

Starting page:

  1. In the form tag, change the form submission method from POST to GET, and set the action parameter to the url of the page you wish to show the results on;
  2. Set the name of the input field to "domain_score";
  3. Set the 'placement' key on the widget config to a unique name, such as "widget-results". You will be using this on the results page.
  4. Remove the id="sendmarc-widget-form" from the form tag so that the javascript doesn't intercept the call and the form can then post correctly to the new page.

Here is a basic example of the form:

<form method="GET" action="/score-results"> 
<input type="email" class="form-control" name="domain_score" placeholder="you@example.com">
<button type="submit"> Check score </button
</form>

Results Page:

  1. Include the widget javascript on the score results page. NOTE: you only need the javascript on the results page - you do not need to include a form.
  2. Add a div to your score results page that the form will be shown in. Set the id to the unique name you set in your widget config, i.e. "widget-results".
<div id="widget-results">
<p>This is where the widget will be placed</p>
</div>

Example text to use on the scoring page


Use the Sendmarc https://sendmarc.com/know-your-score page as an example of what a fully styled example page could look like.

Intro Text

"Understanding your score"


Everyone is at risk from email fraudsters. How do we score your domain safety?

Sendmarc has developed an algorithm that rates an organisation’s exposure to fraudulent email activities such as impersonation, phishing and spoofing, and the risk their current domain poses to the cyber security of their company.


A score between 0 and 5 is assigned to an organisation.

5 A score of five (5) indicates a company has a very low risk of their name being used by criminals in fraudulent email activities. Domains with a score of 5 are 100% DMARC compliant and are protected from impersonation and phishing attacks.
4 A score of four (4) requires one more change. Deliverability of rightful email may be affected by being sent to spam or junk folders and savvy criminals could impersonate your domain.
0-3 A score of three (3) or less indicates no protection at all of their name, and the highest probability that their name will be hijacked by criminals and used in fraudulent email activities.