Email routers

An email router plugin is a plugin that can be associated to a send email node in an automation, allowing you to manage the connection with an external email router.

If you don't know what a plugin is, you can find complete documentation in the specific section.

If you're looking to customizing your emails, you should look at the email renderer plugin type.

Endpoints to implement

Email routers need to implement two endpoints.

Send an email to the router

POST myworker/v1/email_routing

This endpoint is called any time a user goes through a send email node in an automation.

Request Body

Name	Type	Description
data	object	PluginEmailData. See Email renderer.
content	object	PluginEmailContent. See Email renderer.
meta	object	PluginEmailMeta. See Email renderer.
user_identifiers	object	The available user identifiers for the user.
datamart_id	string	The ID of the datamart.
blast_id	string	The ID of the campaign blast.
campaign_id	string	The ID of the campaign.
creative_id	string	The ID of the email template.
context	string	The email call context. One of LIVE, STAGE or PREVIEW.
call_id	string	The email call ID.
email_router_id	string	The ID of the email router plugin instance. Used to retrieve the instance properties.

200

{
    "result": true
}

500

{
  "error": "..."
}

See Plugin Instances to learn why you should use the email_router_id parameter to retrieve the instance properties.

Check email channel

POST /v1/email_router_check

The endpoint is called before sending an email to do preliminary checks. In particular, to check if it is possible to send an email with the provided identifiers.

Request Body

Name	Type	Description
user_identifiers	object	The available user identifiers for the user.
email_router_id	string	The ID of the email router plugin instance. Used to retrieve the instance properties.

200

{
    "result": true
}

500

{
    "error": "..."
}

Available outbound services

The code of the email router can call the following API endpoint to retrieve its instance context.

Retrieve the instance properties

GET https://api.mediarithmics.com/v1/email_routers/:id/properties

Get the properties associated with the email router plugin instance.

Path Parameters

Name	Type	Description
id	string	ID of the email router plugin instance, typically theemail_router_id from the incoming request.

200

{
  "status": "ok",
  "data": [
    {
      "technical_name": "provider",
      "value": { "value": "mediarithmics" },
      "property_type": "STRING",
      "origin": "PLUGIN_STATIC",
      "writable": true,
      "deletable": false
    },
    {
      "technical_name": "name",
      "value": { "value": "Email router example" },
      "property_type": "STRING",
      "origin": "PLUGIN_STATIC",
      "writable": false,
      "deletable": false
    }
  ]
}

Creating an email router plugin

See the plugins documentation to see how plugins are created and deployed.

An email router plugin has the EMAIL_ROUTER plugin type. Its group id should be {domain.organisation.email-router} (for example com.mediarithmics.email-router).

Its artifact id should be the name of the email router plugin, i.e. example-email-router.

Use our Plugin SDK to create your email router plugin in Node.js: the required routes are already defined and you only have to override specific functions.

You can find a sample email router plugin in the examples folder of the plugin SDK.

We can provide you with a "Hello World" project using our SDK. Please contact your support in order to have access to it.

The project structure and files work as with every other plugin.

Interfaces to implement

Your should extend EmailRouterPlugin class and implement the onEmailRouting and onEmailCheck functions from the plugin SDK.

The onEmailRouting function is called every time a user runs through a send email node in an automation. It is responsible for sending the email.

Don't forget to catch your errors. You should log / respond with the appropriate message to facilitate debugging.

import { core } from '@mediarithmics/plugins-nodejs-sdk';

export class MyEmailRouterPlugin extends core.EmailRouterPlugin {
  constructor() {
    super();
  }

  protected async onEmailRouting(
    request: core.EmailRoutingRequest,
    instanceContext: core.EmailRouterBaseInstanceContext
  ): Promise<core.EmailRoutingPluginResponse> {
    const identifier = request.user_identifiers.find(identifier => {
      return (
        identifier.type === 'USER_EMAIL' &&
        !!(identifier as core.UserEmailIdentifierInfo).email
      );
    }) as core.UserEmailIdentifierInfo;

    if (!identifier) {
      throw Error('No clear email identifiers were provided');
    }

    const payload = this.buildMyEmailRouterPayload(
      request.creative_id,
      identifier.hash
    );

    await this.sendToMyEmailRouter(payload); 
    return { result: true };
  }

  protected async onEmailCheck(
    request: core.CheckEmailsRequest,
    instanceContext: core.EmailRouterBaseInstanceContext
  ): Promise<core.CheckEmailsPluginResponse> {
    // If your router does not have a route to check its status, you can use this
    return Promise.resolve({result: true});
  }
}

Debugging

Plugin logs and metrics

You can monitor email router plugins as you do with all plugins.