Welcome to the docs

Signing up to Imitate Email is easy...

If you're setting up a new account sign up on the home page or the pricing page.

To sign up for an existing account, as part of your organisation, you will need to be sent an invitation by your account administrator.

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.

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.

Host/Server

smtp.imitate.email

Port

587

Username

<your tenant id>

Password

<your mailbox secret>

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.

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:

1. Go to Settings -> SMTP & API Info
2. Then click
3. Give your key a description
4. ensure that Test Key is ticked
5. then tick Only allow this key to use certain API calls
6. 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).

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.

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

1. Locate the secret key for your mailbox

   This can be found in Settings > Projects for team mailboxes and in Settings > My Mailbox for personal mailboxes (the password).

2. Locate your tenant identifier

   This can be found in Settings > Tenants as well as the address bar

3. 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 your secret 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.

4. 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>
   

For our multi-user plans, the appearance of the widget can be customized.

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.