Email API and message workflows

JavaScript

import { MailSlurp } from 'mailslurp-client';

export function createClient() {
  const apiKey = process.env.MAILSLURP_API_KEY;
  if (!apiKey) throw new Error('Set MAILSLURP_API_KEY');
  return new MailSlurp({ apiKey });
}

Python

import base64
import os

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.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.Collections;
import java.util.List;
import java.util.UUID;

final class EmailSetup {
    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#

using System;
using System.Collections.Generic;
using System.Text;
using mailslurp.Api;
using mailslurp.Client;
using mailslurp.Model;

public static class EmailSetup
{
    public static Configuration CreateConfiguration()
    {
        var apiKey = Environment.GetEnvironmentVariable("MAILSLURP_API_KEY");
        if (string.IsNullOrWhiteSpace(apiKey))
            throw new InvalidOperationException("Set MAILSLURP_API_KEY");
        var configuration = new Configuration { Timeout = TimeSpan.FromSeconds(75) };
        configuration.ApiKey.Add("x-api-key", apiKey);
        return configuration;
    }
}

JavaScript

export async function sendHtml(mailslurp, inboxId, to) {
  // sendEmailAndConfirm returns the sent email record once MailSlurp accepts it.
  return mailslurp.inboxController.sendEmailAndConfirm({
    inboxId,
    sendEmailOptions: {
      to: [to],
      subject: 'Your order has shipped',
      body: '<h1>On its way</h1><p>Track it at <a href="https://example.com/track">example.com</a></p>',
      isHTML: true,
    },
  });
}

Python

def send_html(api_client, inbox_id, to):
    # send_email_and_confirm returns the sent email record once MailSlurp accepts it.
    return mailslurp_client.InboxControllerApi(api_client).send_email_and_confirm(
        inbox_id,
        mailslurp_client.SendEmailOptions(
            to=[to],
            subject="Your order has shipped",
            body='<h1>On its way</h1><p>Track it at <a href="https://example.com/track">example.com</a></p>',
            is_html=True,
        ),
    )

Java

public static SentEmailDto sendHtml(ApiClient client, UUID inboxId, String to) throws ApiException {
    // sendEmailAndConfirm returns the sent email record once MailSlurp accepts it.
    return new InboxControllerApi(client).sendEmailAndConfirm(inboxId, new SendEmailOptions()
        .to(Collections.singletonList(to))
        .subject("Your order has shipped")
        .body("<h1>On its way</h1><p>Track it at <a href=\"https://example.com/track\">example.com</a></p>")
        .isHTML(true)).execute();
}

C#

public static SentEmailDto SendHtml(Configuration configuration, Guid inboxId, string to)
{
    // SendEmailAndConfirm returns the sent email record once MailSlurp accepts it.
    return new InboxControllerApi(configuration).SendEmailAndConfirm(inboxId, new SendEmailOptions(
        to: new List<string> { to },
        subject: "Your order has shipped",
        body: "<h1>On its way</h1><p>Track it at <a href=\"https://example.com/track\">example.com</a></p>",
        isHTML: true));
}

JavaScript

export async function sendAttachment(mailslurp, inboxId, to) {
  // Upload the file first, then send its attachment ID with the email.
  const [attachmentId] = await mailslurp.attachmentController.uploadAttachment({
    uploadAttachmentOptions: {
      base64Contents: Buffer.from('id,total\n1001,49.00\n').toString('base64'),
      contentType: 'text/csv',
      filename: 'invoice.csv',
    },
  });
  return mailslurp.inboxController.sendEmailAndConfirm({
    inboxId,
    sendEmailOptions: { to: [to], subject: 'Invoice attached', body: 'See attached.', attachments: [attachmentId] },
  });
}

Python

def send_attachment(api_client, inbox_id, to):
    # Upload the file first, then send its attachment ID with the email.
    attachment_ids = mailslurp_client.AttachmentControllerApi(api_client).upload_attachment(
        mailslurp_client.UploadAttachmentOptions(
            base64_contents=base64.b64encode(b"id,total\n1001,49.00\n").decode(),
            content_type="text/csv",
            filename="invoice.csv",
        )
    )
    return mailslurp_client.InboxControllerApi(api_client).send_email_and_confirm(
        inbox_id,
        mailslurp_client.SendEmailOptions(
            to=[to], subject="Invoice attached", body="See attached.", attachments=attachment_ids
        ),
    )

Java

public static SentEmailDto sendAttachment(ApiClient client, UUID inboxId, String to) throws ApiException {
    // Upload the file first, then send its attachment ID with the email.
    List<String> attachmentIds = new AttachmentControllerApi(client).uploadAttachment(new UploadAttachmentOptions()
        .base64Contents(Base64.getEncoder().encodeToString("id,total\n1001,49.00\n".getBytes(StandardCharsets.UTF_8)))
        .contentType("text/csv")
        .filename("invoice.csv")).execute();
    return new InboxControllerApi(client).sendEmailAndConfirm(inboxId, new SendEmailOptions()
        .to(Collections.singletonList(to))
        .subject("Invoice attached")
        .body("See attached.")
        .attachments(attachmentIds)).execute();
}

C#

public static SentEmailDto SendAttachment(Configuration configuration, Guid inboxId, string to)
{
    // Upload the file first, then send its attachment ID with the email.
    var attachmentIds = new AttachmentControllerApi(configuration).UploadAttachment(new UploadAttachmentOptions(
        base64Contents: Convert.ToBase64String(Encoding.UTF8.GetBytes("id,total\n1001,49.00\n")),
        contentType: "text/csv",
        filename: "invoice.csv"));
    return new InboxControllerApi(configuration).SendEmailAndConfirm(inboxId, new SendEmailOptions(
        to: new List<string> { to }, subject: "Invoice attached", body: "See attached.",
        attachments: attachmentIds));
}

Javascript

// send an email 5 seconds from now
await mailslurp.inboxController.sendWithSchedule({
  inboxId: inbox.id,
  sendAtNowPlusSeconds: 5,
  validateBeforeEnqueue: true,
  sendEmailOptions: {
    to: [inbox.emailAddress],
    subject: 'test-schedule-123',
    body: '🌭',
    filterBouncedRecipients: true,
    validateEmailAddresses:
      SendEmailOptionsValidateEmailAddressesEnum.VALIDATE_FILTER_REMOVE_INVALID,
  },
});

Javascript

const template = await mailslurp.templateController.createTemplate({
  createTemplateOptions: {
    name: 'Welcome email',
    content: 'Hello {{firstName}}. Welcome to {{brandName}}.',
  },
});
expect(template.id).toBeTruthy();
expect(template.variables).toEqual([
  {
    name: 'firstName',
    variableType: TemplateVariableVariableTypeEnum.STRING,
  },
  {
    name: 'brandName',
    variableType: TemplateVariableVariableTypeEnum.STRING,
  },
]);

Javascript

const templateObject = await mailslurp.templateController.getTemplate({
  templateId,
});
expect(templateObject.content).toContain(
  'Hello {{firstName}}. Welcome to {{brandName}}.'
);
const sent = await mailslurp.sendEmail(inboxId, {
  to: [emailAddress],
  subject: 'Welcome {{firstName}}',
  template: templateId,
  templateVariables: {
    firstName: 'Sally',
    brandName: 'My Company',
  } as any,
});

Javascript

// send an email 5 minutes in future using a date
const milliseconds = 5 * 60 * 1000;
const timeObject = new Date(new Date().getTime() + milliseconds);
await mailslurp.inboxController.sendWithSchedule({
  inboxId: inbox.id,
  sendAtTimestamp: timeObject,
  validateBeforeEnqueue: true,
  sendEmailOptions: {
    to: [inbox.emailAddress],
    subject: 'test-schedule-later',
    body: '⏰',
    filterBouncedRecipients: true,
  },
});

Javascript

await mailslurp.inboxController.sendEmailWithQueue({
  inboxId: inboxId,
  sendEmailOptions: {
    to: [recipient],
    subject: 'Sent with a queue',
    body:
      'Use queues to allow recovery of failed email ' +
      'sending when account reaches limits or has payment issues',
  },
  // validate before adding to queue to fail early
  validateBeforeEnqueue: false,
});

Javascript

// create an inbox using MailSlurp client
const mailslurp = new MailSlurp({ apiKey: process.env.API_KEY! });
const inbox = await mailslurp.createInboxWithOptions({
  inboxType: CreateInboxDtoInboxTypeEnum.SMTP_INBOX,
});
// get smtp access details for mailbox
const server = await mailslurp.inboxController.getImapSmtpAccess({
  inboxId: inbox.id,
});
// Create auth plain transport
const transport = nodemailer.createTransport({
  host: server.smtpServerHost,
  port: server.smtpServerPort,
  secure: false,
  auth: {
    user: server.smtpUsername,
    pass: server.smtpPassword,
    type: 'PLAIN',
  },
});
// Send email
const sent = await transport.sendMail({
  from: inbox.emailAddress,
  to: inbox.emailAddress,
  subject: 'Test outbound email',
  text: 'Can I send on behalf?',
  html: '<b>Hello world</b>',
});

Javascript

const sentEmails = await mailslurp.sentController.getSentEmails({
  inboxId: inbox.id,
});
expect(sentEmails!!.content!!.length).toBeDefined();

Javascript

const emails = await mailslurp.inboxController.getEmails({
    inboxId: inbox.id,
    unreadOnly: true,
});
expect(emails.length).toBeDefined();

JavaScript

export async function getEmail(mailslurp, emailId) {
  const email = await mailslurp.emailController.getEmail({ emailId });
  return { from: email.from, subject: email.subject, body: email.body, attachments: email.attachments };
}

Python

def get_email(api_client, email_id):
    email = mailslurp_client.EmailControllerApi(api_client).get_email(email_id)
    return {"from": email._from, "subject": email.subject, "body": email.body,
            "attachments": email.attachments}

Java

public static Email getEmail(ApiClient client, UUID emailId) throws ApiException {
    Email email = new EmailControllerApi(client).getEmail(emailId).execute();
    System.out.println(email.getFrom() + " " + email.getSubject());
    return email;
}

C#

public static Email GetEmail(Configuration configuration, Guid emailId)
{
    var email = new EmailControllerApi(configuration).GetEmail(emailId);
    Console.WriteLine($"{email.From} {email.Subject}");
    return email;
}

JavaScript

export async function linksAndCodes(mailslurp, emailId) {
  // MailSlurp parses links and one-time codes from the email body for you.
  const { links } = await mailslurp.emailController.getEmailLinks({ emailId });
  const codes = await mailslurp.emailController.getEmailCodes({ emailId });
  return { links, codes };
}

Python

def links_and_codes(api_client, email_id):
    # MailSlurp parses links and one-time codes from the email body for you.
    emails = mailslurp_client.EmailControllerApi(api_client)
    links = emails.get_email_links(email_id).links
    codes = emails.get_email_codes(email_id)
    return links, codes

Java

public static List<String> linksAndCode(ApiClient client, UUID emailId) throws ApiException {
    // MailSlurp parses links and one-time codes from the email body for you.
    EmailControllerApi emails = new EmailControllerApi(client);
    List<String> links = emails.getEmailLinks(emailId).execute().getLinks();
    ExtractCodesResult codes = emails.getEmailCodes(emailId).execute();
    if (Boolean.TRUE.equals(codes.getFound())) System.out.println("Code: " + codes.getCode());
    return links;
}

C#

public static List<string> LinksAndCode(Configuration configuration, Guid emailId)
{
    // MailSlurp parses links and one-time codes from the email body for you.
    var emails = new EmailControllerApi(configuration);
    var links = emails.GetEmailLinks(emailId).Links;
    var codes = emails.GetEmailCodes(emailId);
    if (codes.Found) Console.WriteLine($"Code: {codes.Code}");
    return links;
}

JavaScript

export async function downloadAttachment(mailslurp, emailId) {
  const email = await mailslurp.emailController.getEmail({ emailId });
  const attachmentId = email.attachments[0];
  const file = await mailslurp.attachmentController.downloadAttachmentAsBase64Encoded({ attachmentId });
  return { contentType: file.contentType, bytes: Buffer.from(file.base64FileContents, 'base64') };
}

Python

def download_attachment(api_client, email_id):
    email = mailslurp_client.EmailControllerApi(api_client).get_email(email_id)
    attachment_id = email.attachments[0]
    file = mailslurp_client.AttachmentControllerApi(api_client).download_attachment_as_base64_encoded(
        attachment_id
    )
    return file.content_type, base64.b64decode(file.base64_file_contents)

Java

public static byte[] downloadAttachment(ApiClient client, UUID emailId) throws ApiException {
    Email email = new EmailControllerApi(client).getEmail(emailId).execute();
    String attachmentId = email.getAttachments().get(0);
    DownloadAttachmentDto file = new AttachmentControllerApi(client)
        .downloadAttachmentAsBase64Encoded(attachmentId).execute();
    return Base64.getDecoder().decode(file.getBase64FileContents());
}

C#

public static byte[] DownloadAttachment(Configuration configuration, Guid emailId)
{
    var email = new EmailControllerApi(configuration).GetEmail(emailId);
    var attachmentId = email.Attachments[0];
    var file = new AttachmentControllerApi(configuration).DownloadAttachmentAsBase64Encoded(attachmentId);
    return Convert.FromBase64String(file.Base64FileContents);
}

JavaScript

export async function reply(mailslurp, emailId) {
  // Replies keep the original thread headers and send from the receiving inbox.
  return mailslurp.emailController.replyToEmail({
    emailId,
    replyToEmailOptions: { body: 'Thanks, received.', isHTML: false },
  });
}

Python

def reply(api_client, email_id):
    # Replies keep the original thread headers and send from the receiving inbox.
    return mailslurp_client.EmailControllerApi(api_client).reply_to_email(
        email_id, mailslurp_client.ReplyToEmailOptions(body="Thanks, received.", is_html=False)
    )

Java

public static SentEmailDto reply(ApiClient client, UUID emailId) throws ApiException {
    // Replies keep the original thread headers and send from the receiving inbox.
    return new EmailControllerApi(client).replyToEmail(emailId, new ReplyToEmailOptions()
        .body("Thanks, received.")
        .isHTML(false)).execute();
}

C#

public static SentEmailDto Reply(Configuration configuration, Guid emailId)
{
    // Replies keep the original thread headers and send from the receiving inbox.
    return new EmailControllerApi(configuration).ReplyToEmail(emailId,
        new ReplyToEmailOptions(body: "Thanks, received.", isHTML: false));
}

Javascript

// fetch the email and review spam analysis
expect(email.analysis?.dkimVerdict).toEqual('PASS');
expect(email.analysis?.spamVerdict).toEqual('PASS');
// other verdicts available
expect(email.analysis?.dmarcVerdict).toBeDefined();
expect(email.analysis?.spfVerdict).toBeDefined();
expect(email.analysis?.virusVerdict).toBeDefined();

Javascript

const user = await myApp.signUp(testInbox.emailAddress!);

// verify that confirmation email was sent by your app
const timeout = 30000;
const email = await mailslurp.waitForLatestEmail(testInbox.id, timeout);

// confirm the user using the code
const [_, verificationCode] = /your code is "([0-9]{6})"/g.exec(
  email.body!
)!;

// do something with code like verifying an account
await myApp.confirmUser(verificationCode);

Javascript

const matchingEmails = await mailslurp.waitForMatchingEmails(
  {
    // match for emails with no attachments
    conditions: [
      {
        condition: ConditionOptionConditionEnum.HAS_ATTACHMENTS,
        value: ConditionOptionValueEnum.FALSE,
      },
    ],
    // match for emails from a specific email address
    matches: [
      {
        field: MatchOptionFieldEnum.FROM,
        should: MatchOptionShouldEnum.CONTAIN,
        value: inbox.emailAddress,
      },
    ],
  },
  1,
  inbox.id,
  timeout,
  unreadOnly
);

Javascript

await mailslurp.webhookController.createWebhook({
  inboxId: inbox.id,
  createWebhookOptions: {
    eventName: CreateWebhookOptionsEventNameEnum.NEW_EMAIL,
    url: slackIncomingWebhookUrl,
    // custom request body for slack uses {{subject}} to insert
    // the subject from the standard NEW_EMAIL payload
    requestBodyTemplate: `{"text":"New message: {{subject}}"}`,
  },
});