Automate inbox placement and review reports

JavaScript

import {
  ApiInboxPlacementTestControllerApi,
  Configuration,
  CreateInboxPlacementTestOptionsAddressFormatEnum,
  CreateInboxPlacementTestOptionsRequestedSegmentEnum,
  MailSlurp,
} from 'mailslurp-client';

export function createClients() {
  const apiKey = process.env.MAILSLURP_API_KEY;
  if (!apiKey) throw new Error('Set MAILSLURP_API_KEY');
  return {
    mailslurp: new MailSlurp({ apiKey }),
    placement: new ApiInboxPlacementTestControllerApi(new Configuration({ apiKey })),
  };
}

Python

import os
import time
from collections import Counter, defaultdict

import mailslurp_client


def create_client():
    api_key = os.environ.get("MAILSLURP_API_KEY")
    if not api_key:
        raise RuntimeError("Set MAILSLURP_API_KEY")
    configuration = mailslurp_client.Configuration()
    configuration.api_key["x-api-key"] = api_key
    return mailslurp_client.ApiClient(configuration)

Java

import com.mailslurp.apis.*;
import com.mailslurp.clients.ApiClient;
import com.mailslurp.clients.ApiException;
import com.mailslurp.models.*;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.UUID;

final class PlacementSetup {
    static ApiClient createClient() {
        String apiKey = System.getenv("MAILSLURP_API_KEY");
        if (apiKey == null || apiKey.trim().isEmpty()) {
            throw new IllegalStateException("Set MAILSLURP_API_KEY");
        }
        ApiClient client = new ApiClient();
        client.setApiKey(apiKey);
        client.setConnectTimeout(10_000);
        client.setReadTimeout(75_000);
        return client;
    }
}

C#

// The inbox placement endpoints are newer than the current NuGet SDK, so these helpers call the
// REST API with HttpClient. Sending uses the MailSlurp SDK. Both use your x-api-key.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;
using System.Threading.Tasks;
using mailslurp.Api;
using mailslurp.Client;
using mailslurp.Model;

public static class PlacementSetup
{
    public static HttpClient CreateHttpClient()
    {
        var http = new HttpClient { BaseAddress = new Uri("https://api.mailslurp.com"), Timeout = TimeSpan.FromSeconds(75) };
        http.DefaultRequestHeaders.Add("x-api-key", ApiKey());
        return http;
    }

    public static Configuration CreateConfiguration()
    {
        var configuration = new Configuration { Timeout = TimeSpan.FromSeconds(75) };
        configuration.ApiKey.Add("x-api-key", ApiKey());
        return configuration;
    }

    private static string ApiKey()
    {
        var apiKey = Environment.GetEnvironmentVariable("MAILSLURP_API_KEY");
        if (string.IsNullOrWhiteSpace(apiKey))
            throw new InvalidOperationException("Set MAILSLURP_API_KEY");
        return apiKey;
    }
}

JavaScript

export async function createTest(placement, senderDomain, fromEmail) {
  // A test gives you seed addresses at Gmail, Outlook, Yahoo and other providers.
  const run = await placement.createInboxPlacementTest({
    createInboxPlacementTestOptions: {
      requestedSegment: CreateInboxPlacementTestOptionsRequestedSegmentEnum.ALL_INBOXES,
      senderDomain,
      fromEmail,
      publicShareRequested: false,
      addressFormat: CreateInboxPlacementTestOptionsAddressFormatEnum.COMMA,
    },
  });
  // Keep the tracking token: the campaign you send must include it.
  return { testId: run.id, trackingToken: run.trackingToken, seedAddresses: run.seedAddresses };
}

Python

def create_test(api_client, sender_domain, from_email):
    # A test gives you seed addresses at Gmail, Outlook, Yahoo and other providers.
    run = mailslurp_client.ApiInboxPlacementTestControllerApi(api_client).create_inbox_placement_test(
        mailslurp_client.CreateInboxPlacementTestOptions(
            requested_segment="ALL_INBOXES",
            sender_domain=sender_domain,
            from_email=from_email,
            public_share_requested=False,
            address_format="COMMA",
        )
    )
    # Keep the tracking token: the campaign you send must include it.
    return run.id, run.tracking_token, run.seed_addresses

Java

public static InboxPlacementTestRunDto createTest(ApiClient client, String senderDomain, String fromEmail) throws ApiException {
    // A test gives you seed addresses at Gmail, Outlook, Yahoo and other providers, and a
    // tracking token that the campaign you send must include.
    return new ApiInboxPlacementTestControllerApi(client).createInboxPlacementTest(new CreateInboxPlacementTestOptions()
        .requestedSegment(CreateInboxPlacementTestOptions.RequestedSegmentEnum.ALL_INBOXES)
        .senderDomain(senderDomain)
        .fromEmail(fromEmail)
        .publicShareRequested(false)
        .addressFormat(CreateInboxPlacementTestOptions.AddressFormatEnum.COMMA)).execute();
}

C#

public static async Task<(string TestId, string TrackingToken, List<string> SeedAddresses)> CreateTest(
    HttpClient http, string senderDomain, string fromEmail)
{
    // A test gives you seed addresses at Gmail, Outlook, Yahoo and other providers, and a
    // tracking token that the campaign you send must include.
    var response = await http.PostAsJsonAsync("/inbox-placement-tests", new
    {
        requestedSegment = "ALL_INBOXES",
        senderDomain,
        fromEmail,
        publicShareRequested = false,
        addressFormat = "COMMA",
    });
    response.EnsureSuccessStatusCode();
    var run = await response.Content.ReadFromJsonAsync<JsonElement>();
    var seeds = run.GetProperty("seedAddresses").EnumerateArray().Select(seed => seed.GetString()).ToList();
    return (run.GetProperty("id").GetString(), run.GetProperty("trackingToken").GetString(), seeds);
}

JavaScript

export async function sendToSeeds(mailslurp, placement, senderInboxId, test) {
  // Send your real campaign to every seed address with the test's tracking token in the subject.
  // In production, send through your own ESP from the domain you are testing; a MailSlurp inbox
  // is used here to keep the example short.
  await mailslurp.sendEmail(senderInboxId, {
    to: test.seedAddresses,
    subject: `Spring sale: 20% off everything ${test.trackingToken}`,
    body: '<h1>Spring sale</h1><p>20% off everything this week.</p>',
    isHTML: true,
  });
  // Confirm only after the send succeeded, so MailSlurp starts watching the seed inboxes.
  await placement.confirmInboxPlacementTestSent({ id: test.testId });
}

Python

def send_to_seeds(api_client, sender_inbox_id, test_id, tracking_token, seed_addresses):
    # Send your real campaign to every seed address with the test's tracking token in the subject.
    # In production, send through your own ESP from the domain you are testing; a MailSlurp inbox
    # is used here to keep the example short.
    mailslurp_client.InboxControllerApi(api_client).send_email(
        sender_inbox_id,
        mailslurp_client.SendEmailOptions(
            to=seed_addresses,
            subject=f"Spring sale: 20% off everything {tracking_token}",
            body="<h1>Spring sale</h1><p>20% off everything this week.</p>",
            is_html=True,
        ),
    )
    # Confirm only after the send succeeded, so MailSlurp starts watching the seed inboxes.
    mailslurp_client.ApiInboxPlacementTestControllerApi(api_client).confirm_inbox_placement_test_sent(test_id)

Java

public static void sendToSeeds(ApiClient client, UUID senderInboxId, InboxPlacementTestRunDto test) throws ApiException {
    // Send your real campaign to every seed address with the test's tracking token in the subject.
    // In production, send through your own ESP from the domain you are testing; a MailSlurp inbox
    // is used here to keep the example short.
    new InboxControllerApi(client).sendEmail(senderInboxId, new SendEmailOptions()
        .to(test.getSeedAddresses())
        .subject("Spring sale: 20% off everything " + test.getTrackingToken())
        .body("<h1>Spring sale</h1><p>20% off everything this week.</p>")
        .isHTML(true)).execute();
    // Confirm only after the send succeeded, so MailSlurp starts watching the seed inboxes.
    new ApiInboxPlacementTestControllerApi(client).confirmInboxPlacementTestSent(test.getId()).execute();
}

C#

public static async Task SendToSeeds(Configuration configuration, HttpClient http, Guid senderInboxId,
    string testId, string trackingToken, List<string> seedAddresses)
{
    // Send your real campaign to every seed address with the test's tracking token in the subject.
    // In production, send through your own ESP from the domain you are testing; a MailSlurp inbox
    // is used here to keep the example short.
    new InboxControllerApi(configuration).SendEmail(senderInboxId, new SendEmailOptions(
        to: seedAddresses,
        subject: $"Spring sale: 20% off everything {trackingToken}",
        body: "<h1>Spring sale</h1><p>20% off everything this week.</p>",
        isHTML: true));
    // Confirm only after the send succeeded, so MailSlurp starts watching the seed inboxes.
    var confirmed = await http.PostAsync($"/inbox-placement-tests/{testId}/confirm-sent", null);
    confirmed.EnsureSuccessStatusCode();
}

JavaScript

export async function waitForResults(placement, testId) {
  // Seeds report as messages arrive; poll until the test completes (usually a few minutes).
  for (let attempt = 0; attempt < 40; attempt += 1) {
    const run = await placement.getInboxPlacementTest({ id: testId });
    if (run.completedAt) {
      return { inbox: run.inboxTargets, spam: run.spamTargets, missing: run.notReceivedTargets, total: run.totalTargets };
    }
    await new Promise(resolve => setTimeout(resolve, 15_000));
  }
  throw new Error(`Inbox placement test ${testId} is still running`);
}

Python

def wait_for_results(api_client, test_id):
    # Seeds report as messages arrive; poll until the test completes (usually a few minutes).
    placement = mailslurp_client.ApiInboxPlacementTestControllerApi(api_client)
    for _ in range(40):
        run = placement.get_inbox_placement_test(test_id)
        if run.completed_at:
            return {"inbox": run.inbox_targets, "spam": run.spam_targets,
                    "missing": run.not_received_targets, "total": run.total_targets}
        time.sleep(15)
    raise TimeoutError(f"Inbox placement test {test_id} is still running")

Java

public static InboxPlacementTestRunDto waitForResults(ApiClient client, UUID testId) throws Exception {
    // Seeds report as messages arrive; poll until the test completes (usually a few minutes).
    ApiInboxPlacementTestControllerApi placement = new ApiInboxPlacementTestControllerApi(client);
    for (int attempt = 0; attempt < 40; attempt++) {
        InboxPlacementTestRunDto run = placement.getInboxPlacementTest(testId).execute();
        if (run.getCompletedAt() != null) {
            System.out.println("Inbox " + run.getInboxTargets() + ", spam " + run.getSpamTargets()
                + ", missing " + run.getNotReceivedTargets());
            return run;
        }
        Thread.sleep(15_000);
    }
    throw new IllegalStateException("Inbox placement test " + testId + " is still running");
}

C#

public static async Task<JsonElement> WaitForResults(HttpClient http, string testId)
{
    // Seeds report as messages arrive; poll until the test completes (usually a few minutes).
    for (var attempt = 0; attempt < 40; attempt++)
    {
        var run = await http.GetFromJsonAsync<JsonElement>($"/inbox-placement-tests/{testId}");
        if (run.TryGetProperty("completedAt", out var completedAt) && completedAt.ValueKind != JsonValueKind.Null)
        {
            Console.WriteLine($"Inbox {run.GetProperty("inboxTargets")}, spam {run.GetProperty("spamTargets")}, " +
                              $"missing {run.GetProperty("notReceivedTargets")}");
            return run;
        }
        await Task.Delay(TimeSpan.FromSeconds(15));
    }
    throw new TimeoutException($"Inbox placement test {testId} is still running");
}

JavaScript

export async function placementByProvider(placement, testId) {
  // Count where each provider put the email: INBOX, SPAM or not received.
  const { results } = await placement.getInboxPlacementTestResults({ id: testId });
  const byProvider = {};
  for (const target of results?.targets ?? []) {
    const folder = target.placementFolder ?? 'NOT_RECEIVED';
    byProvider[target.provider] ??= {};
    byProvider[target.provider][folder] = (byProvider[target.provider][folder] ?? 0) + 1;
  }
  return byProvider;
}

Python

def placement_by_provider(api_client, test_id):
    # Count where each provider put the email: INBOX, SPAM or not received.
    results = mailslurp_client.ApiInboxPlacementTestControllerApi(
        api_client
    ).get_inbox_placement_test_results(test_id).results
    by_provider = defaultdict(Counter)
    for target in (results.targets if results else []):
        by_provider[target.provider][target.placement_folder or "NOT_RECEIVED"] += 1
    return dict(by_provider)

Java

public static Map<String, Map<String, Integer>> placementByProvider(ApiClient client, UUID testId) throws ApiException {
    // Count where each provider put the email: INBOX, SPAM or not received.
    InboxPlacementRemoteResultsDto results = new ApiInboxPlacementTestControllerApi(client)
        .getInboxPlacementTestResults(testId).execute().getResults();
    Map<String, Map<String, Integer>> byProvider = new HashMap<>();
    if (results == null) return byProvider;
    for (InboxPlacementTargetResultDto target : results.getTargets()) {
        String folder = target.getPlacementFolder() == null ? "NOT_RECEIVED" : target.getPlacementFolder();
        byProvider.computeIfAbsent(target.getProvider(), key -> new HashMap<>()).merge(folder, 1, Integer::sum);
    }
    return byProvider;
}

C#

public static async Task<Dictionary<string, Dictionary<string, int>>> PlacementByProvider(HttpClient http, string testId)
{
    // Count where each provider put the email: INBOX, SPAM or not received.
    var response = await http.GetFromJsonAsync<JsonElement>($"/inbox-placement-tests/{testId}/results");
    var byProvider = new Dictionary<string, Dictionary<string, int>>();
    if (!response.TryGetProperty("results", out var results) || results.ValueKind == JsonValueKind.Null) return byProvider;
    foreach (var target in results.GetProperty("targets").EnumerateArray())
    {
        var provider = target.GetProperty("provider").GetString();
        var folder = target.TryGetProperty("placementFolder", out var value) && value.ValueKind == JsonValueKind.String
            ? value.GetString() : "NOT_RECEIVED";
        if (!byProvider.TryGetValue(provider, out var counts)) byProvider[provider] = counts = new Dictionary<string, int>();
        counts[folder] = counts.TryGetValue(folder, out var count) ? count + 1 : 1;
    }
    return byProvider;
}