@mailvideo/backend

This package is designed for server-side integration of MailVideo, facilitating actions like handling webhook events, creating JWT and processing custom videos for MailVideo users.

• Install
• Features
• Prerequisites
• Example
• Usage
• API
• Webhook Handling

Install

pnpm i @mailvideo/backend

Features

• Handle MailVideo webhook events.
• Create JWT for white label SDK users.
• Process videos and upload to S3.

Prerequisites

To use this package, a secret key from MailVideo is required. Please contact MailVideo to obtain your secret key.

Example

• GitHub Repository

Usage

Creating a JWT

import { MailVideo } from '@mailvideo/backend';

const mailvideo = new MailVideo({
	secret: process.env.MAILVIDEO_SECRET,
	verbose: process.env.NODE_ENV === 'development',
});

// create a jwt with info about the current user and tenant
const jwt = await mailvideo.createJWT({
	account: {
		id: 'account-id',
		firstName: 'John',
		lastName: 'Doe',
		email: '[e-mail]',
	},
	tenant: {
		id: tenantId,
		name: 'Tenant Name',
	},
});

// send JWT to client

Handling Webhooks

import { constructAndHandleMailVideoEvent } from '@mailvideo/backend';

const signature = request.headers['mailvideo-signature'];
if (!signature) {
	throw new Error('Missing signature');
}

await constructAndHandleMailVideoEvent({
	payload: request.body,
	signature,
	secret: process.env.MAILVIDEO_WEBHOOK_SECRET,
	actions: {
		'video-processed-success': (payload) => {
			// Handle successful video processing
		},
		'video-processed-failed': (payload) => {
			// Handle failed video processing
		},
		'video-viewed': (payload) => {
			// Handle video viewed event
		},
	},
});

API

Methods

• createJWT(options: CreateJWTOptions): Promise<CreateJWTResponse>
• processVideo(options: StartVideoProcessOptions): Promise<StartVideoProcessResponse>
• constructEvent(options: MailVideoConstructEventOptions): MailVideoEvent
• handleEvent(event: MailVideoEvent, actions: EventHandlerActions): Promise<void>
• constructAndHandleEvent(options: MailVideoConstructEventOptions & { actions: EventHandlerActions }): Promise<void>

Webhook Handling

When handling webhooks, use the constructAndHandleMailVideoEvent method to validate the event and process it with defined actions.

Interfaces

ViewerData

Metadata about the viewer that watches the video.

You can force strong typing by adding a d.ts file to your project.

Example:

declare namespace MailVideo {
	interface ViewerData {
		name: string;
		email: string;
	}
}

Configuring a Custom S3 Bucket for MailVideo

If you want to host the videos in your own Amazon S3 bucket. This setup is crucial to ensure that MailVideo can store and stream videos effectively.

Steps

1. Access Your S3 Bucket Go to the AWS Management Console and navigate to the S3 service. Select the bucket you intend to use with MailVideo.

2. Set Permissions Navigate to the Permissions tab of your selected S3 bucket.

3. Add a Bucket Policy Under the Bucket Policy section, you need to add the following policy:

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Principal": {
				"AWS": "arn:aws:iam::102512246328:root"
			},
			"Action": ["s3:GetObject", "s3:PutObject"],
			"Resource": "arn:aws:s3:::your-bucket-name/*"
		}
	]
}

Replace your-bucket-name with the actual name of your S3 bucket.

4. Configure CORS Navigate to the CORS configuration section in the S3 bucket settings. Add the following configuration:

[
	{
		"AllowedHeaders": ["Content-Type"],
		"AllowedMethods": ["PUT"],
		"AllowedOrigins": [
			"https://app.mailvideo.dev",
			"https://app.stage.mailvideo.com",
			"https://app.mailvideo.com"
		],
		"ExposeHeaders": ["ETag"],
		"MaxAgeSeconds": 3000
	}
]