Contents
Welcome to the docs
You should find everything you're looking for here but if not, please get in touch with us and we'll do our very best to help.
Getting Started
Signing Up
Concepts
When you sign up to Imitate Email you create a tenant, in which your account lives, and then we set up a personal mailbox for you. This lets individuals get going straight away - every new user gets a personal mailbox.
You are then able to send emails to that personal mailbox, either via SMTP or via an API.
For individuals, having the single personal mailbox is probably sufficient most of the time - it is what you get on the developer tier.
When you start using Imitate Email inside a team or an organisation it makes sense to have multiple projects and mailboxes.
Projects let you put different mailboxes in to logical groups which is useful as you can manage permissions at the project or mailbox level.
Users each get their own personal mailbox and then it is possible to create extra (non-personal) mailboxes.
To give an example, imagine a software development company that writes software for various clients. They would have a single tenant with a project per client and then probably a team mailbox per environment per project i.e. 1 for QA and 1 for staging.
The developers would each use their own personal mailboxes for their local development.
Alternatively, if you use "User Filters" you can just use a single mailbox for all developers.
Sending Emails
SMTP
Providing a sandbox SMTP server is the main point of Imitate Email.
Our SMTP server doesn't actually send any emails, it merely stores them so that you, and your team, can check the content of them and test larger workflows.
The SMTP Server that we provide supports the standard SMTP protocol and uses STARTTLS for secure authentication.
Sending email, in any programming language, is usually quite a standard part of the language.
User Filter
Whether you're developing software or testing it, you're probably making up fake user accounts as you go. When there's only one of you working on a particular environment (for example, your dev machine or a dedicated environment) it's easy to know that the emails you see in Imitate Email are ones that you have sent.
However, when multiple people are working on a single instance of your software (for example, multiple testers) it would be nice to differentiate the emails that originate from each user.
Obviously, you can't do that my looking at the sender or recipient of the email as they've been made up.
This is where a user filter comes in. We provide filtering by email address when you enable user filtering for that project, by toggling the functionality in Settings > Projects.
Once enabled you can then start sending a Header through with your emails named X-User-Email
and the value equal to the email address of the user.
Mandrill
Part of Imitate Email's offering is the ability to mock (or fake) various email sending APIs provided by popular email sending products.
For our mandrill wrapper you can communicate with our API as if you were you sending Http requests to the mandrill API.
The only change required is to modify your Mandrill client library so that it sends requests to https://imitate.email/
.
All of Mandrill's endpoints are at https://mandrillapp.com/api/1.0
.
For Imitate Email, send the requests to https://imitate.email/mandrill/api/1.0
instead.
You will also need to send us credentials for your requests by changing the key
property that you send in your Mandrill requests.
For a personal mailbox, you can find the key in Settings -> My Mailbox and then clicking the link at the bottom of the page.
For a team mailbox, go the projects page and click the icon next to the mailbox you want to send email to.
Using Mandrill Templates
If you use templates when you send email to Mandrill you will need to provide us with a Mandrill API key, so that we can render the emails using your templates.
To create an API key that we can use, log in to Mandrill and:
- Go to Settings -> SMTP & API Info
- Then click
- Give your key a description
- ensure that
Test Key
is ticked - then tick
Only allow this key to use certain API calls
-
From the drop down that appears select
Render only
By doing that, we're only able to call render using content that you provide us. We can't get access to anything else in your Mandrill account.
Once you have generated your API key, copy and paste it in to the same screen that contained your Imitate Email mandrill key (see above).
Widget
Installation
Including the Imitate Email widget in your app is as simple as including the following script in your app
<script src="https://imitate.email/imitate-widget.min.js" async ></script>
This should appear in the bottom right corner of your app

You will be asked to login to Imitate Email. For users of your app outside of developers, please see the Single Sign On section.
Single Sign On / Widget Users
For small projects, it is feasible for every developer or tester of your app to also be a user in Imitate Email, and being logged in to Imitate will allow the widget to know who the user is.
However, for other use cases, particularly if you are using Imitate for hands-on demos or user testing with third parties, you'll want to use our JWT-based authentication.
By authenticating through a signed JWT you will not require people to have user accounts in Imitate Email and can provide the service without them being aware of Imitate Email.
When you authenticate via a signed JWT you are effectively telling us the user and mailbox that they can access and, as long as the signing key matches, we will allow access to that mailbox.
Generate your JWT token
-
Locate the secret key for your mailbox
This can be found inSettings > Projects
for team mailboxes and inSettings > My Mailbox
for personal mailboxes (the password). -
Locate your tenant identifier
This can be found inSettings > Tenants
as well as the address bar -
Generate your JWT string
The payload fields should contain "email", "sub" (same as email), "given_name", "project" and "mailbox". You should also include a "exp" field for when the token should expire:// payload { "sub": "your_user@email.com", "email": "your_user@email.com", "given_name": "Testy McTestface", "exp": "<seconds since 1970>", "project", "<project name>", "mailbox", "<mailbox name>", }
The JWT should then be signed with the HMACSHA256 of the header and payload with yoursecret key
.
For example, generating the full JWT string in C#using System.Security.Claims; using Microsoft.IdentityModel.JsonWebTokens; using Microsoft.IdentityModel.Tokens; public class Example { public static string GenerateImitateJwt(string email, string userName, string secretSigningKey) { var handler = new JsonWebTokenHandler(); var token = handler.CreateToken( new SecurityTokenDescriptor { Subject = new ClaimsIdentity( new[] { new Claim(JwtRegisteredClaimNames.Sub, email), new Claim(JwtRegisteredClaimNames.Email, email), new Claim(JwtRegisteredClaimNames.GivenName, userName), new Claim(JwtRegisteredClaimNames.Exp, DateTimeOffset.UtcNow.AddMinutes(20).ToUnixTimeSeconds().ToString()), new Claim("project", projectName), new Claim("mailbox", mailboxName) }), SigningCredentials = new SigningCredentials( new SymmetricSecurityKey(Encoding.UTF8.GetBytes(secretSigningKey)), SecurityAlgorithms.HmacSha256, SecurityAlgorithms.Sha256Digest) }); return token; } }
To create a signed JWT in another language please consult jwt.io/libraries to find a library that works for your programming language.
-
Include the SSO attributes in the widget script
You now modify the widget script tag so that it contains the token and the mailbox that you would like to provide access to:<script src="https://imitate.email/imitate-widget.min.js" data-project="<project name>" data-mailbox="<mailbox name>" data-tenant="<tenant identifier>" data-access-token="<signed JWT>" async ></script>
Branding
For our multi-user plans, the appearance of the widget can be customized.
Settings > Widget
you can choose a custom logo and accent colour to suit your application.

Why isn't the widget working?
Below are some of the common reasons for the widget not working
[Firefox] The widget prompts me to login even though I already have?
If you are using Firefox, try turning off Enhanced Tracking Protection
. This can be done by clicking on the shield icon in the address bar and turning the toggle off.