Mailinator
Whereas most email systems are bulit around the concept of "account/inbox ownership", Mailinator is an email system built around "entire domain-inbox ownership". This allows companies to have instant access to millions of email addresses for system and automation testing of their software.
Mailinator also provides a "public" domain for personal use where all email addresses (@mailinator.com) are completely public and usable by anyone.
Public Mailinator (all email @mailinator.com)
The Public Mailinator system (i.e. every possible email address @mailinator.com) creates inboxes when email arrives for them. All inboxes (and emails) are in the public domain. They are readable and deleteable by anyone. By design, there is NO privacy in the public Mailinator system and is intended for occasional, personal use.
In addition, all emails in the public Mailinator system auto-delete after a few hours. They are un-retrievable after this happens. Public Mailinator emails also may not contain attachments (if an attachment is sent, it will either not be delivered, or have the attachments stripped before delivery).
Finally, it's important to note that the Mailinator system is RECEIVE-ONLY. No one can send an email from Mailinator. (Any email appearing to have arrived from an @mailinator address has had it's "From" field forged to appear as such).
There is no need to sign-up to use the public Mailinator system. Simply go to the home page and enter an inbox name (i.e. anything you wish up to 50 characters) to check a particular inbox.
Again, the Public Mailinator is intended for personal and occasional use hence usage limits apply. Please see our Upgrade plans for corporate users.
Private Mailinator
Mailinator offers upgraded subscriptions for corporate users wishing to use the Mailinator system. This offers many benefits.
Subscribers receive one or more "Private Domains" which provide a private version of Mailinator. That is, you control all inboxes for a given domain (i.e. you can use a Domain you provide or the system will provide one for you). You may view all such inboxes in one "super inbox" which lists every email coming into the domain in realtime. Emails in Private domains are not automatically deleted until your team's storage is exhausted. At this time, new emails push out old emails. Otherwise, emails in private domains are persistent as long as the account is active.
In addition, Private users gain API access to messages within the Mailinator system. Subscribers may use the API to access all email in their Private Domain(s) in addition to the Public Mailinator system.
Message Delivery
Messages arrive in the Mailinator system several ways.
- SMS
- HTTP Post / Webhooks
The classic way is they arrive as email. However, messages may also enter the system via SMS (i.e. text message), or HTTP Post. Regardless of how a message arrives, it lands in a designated inbox and is then available for retrieval or manipulation/re-delivery via the rule system.
Message Access
Web
The Web Interface is available for all Public and Private email in the Mailinator system. Subscribers must login first in order to see their Private Team Inbox containing mail sent to their Private Domain(s). The Web interface will first attempt to show a message as an email. However, if the formatting of the message does not follow email conventions (i.e. maybe it arrived as an HTTP Post with a custom format), the message will be displayed in raw JSON.
API
Subscribers may use programmatic access to poll inboxes and retrieve emails in JSON format. Documentation for the API can be found below.
Rules
Instead of pulling emails via the API, Subscribers may set rules for Mailinator to "push" messages to them as they arrive. The rule system may be configured via the Web interface (i.e. Mailinator Routing Rules) or programmatically via the API (see API documentation below).
The Rule system allows subscribers to match on inbox and act upon every email that matches the conditional criteria.
For example, a rule might be:
IF TO == mytestinbox THEN POST Webhook To https://mywebsite.com/endpoint
For a given Private domain, all emails that arrive to the "mytestinbox" address will be converted to JSON, and HTTP Posted to the designated endpoint.
For more information on configuring Rules, see the Rules API documentation below.
Public Webhooks
Email is just one entry point for messages into the Mailinator system. Mailinator allows public users to setup webhooks (or HTTP Posts) from their own systems or from third-party systems to inject messages into the Mailinator system.
When a message is injected in this way, it will appear in the appropriate inbox and is readable just like any other message. The most notable difference is that the messages appear as pure JSON instead of parsed Email messages.
In this case, all that Mailinator provides is a public URL destination. As with other parts of the Public Mailinator system, no authentication or authorization is required. However, strict rate and count limits exist on public incoming webhooks. If you need this webhook functionality for your business, you are encouraged to Subscribe to gain privacy, authentication, higher rate limits, the rule-system and more.
Public Webhook URLS
This command will deliver the message to the "bob" inbox
curl -v -d '{"from":"MyMailinatorTest", "subject":"testing message", "text" : "hello world", "to" : "jack" }'
-H "Content-Type: application/json"
-X POST "https://www.mailinator.com/api/v2/domains/public/webhook/bob/"
This command will deliver the message to the "jack" inbox
curl -v -d '{"from":"MyMailinatorTest", "subject":"testing message", "text" : "hello world", "to" : "jack" }'
-H "Content-Type: application/json"
-X POST "https://www.mailinator.com/api/v2/domains/public/webhook/"
You may use these urls in your own systems, or give to third-party systems that deliver webhooks (i.e. Zapier, Twilio, IFTTT, etc.)
The urls take two forms:
HTTP Request
POST https://www.mailinator.com/api/v2/domains/public/webhook/:to
A JSON Payload delivered to this url will be put into the ":to" inbox.
You may also allow the webhook to determine which inbox to deliver the message so long as the incoming JSON contains a "to" field.
Note that if the Mailinator system cannot determine the destination inbox via the URL or a "to" field in the payload, the message will be rejected.
If the message contains a "from" and "subject" field, these will be visible on the inbox page.
Note: This section specifically describes Public Webhooks. Subscribers may also use webhooks to inject messages into their Private Domains which provide many more features. Please refer to that Documentation HERE.
Twilio Webhooks
If you have a Twilio account which receives incoming SMS messages. You may direct those messages through this facility to inject those messages into the Mailinator system.
Set the Webhook URL in your Twilio phone number to:
POST https://www.mailinator.com/api/v2/domains/public/twilio
The SMS message will arrive in the Public Mailinator inbox corresponding to the Twilio Phone Number. (only the digits, if a plus sign precedes the number it will be removed) If you wish the message to arrive in a different inbox, you may append the destination inbox to the URL.
POST https://www.mailinator.com/api/v2/domains/public/twilio/bob
Setting up your Mailinator Subscription
Thanks for being a Mailinator subscriber! This section will show you some immediate ways to get the most out of your Mailinator subscritpion.
You now have a Private domain (yes, already - check your Team Settings tab). Every conceivable inbox at that domain is waiting for you to send email to it. Unlike the public Mailinator system however, you won't run into rate-limits or filters. The email at that domain is private to you.
When your subscription became active, a subdomain of Testinator.com (i.e. a Mailinator testing domain) was created and assigned to your account as your private domain. For example, your initial private domain would be something like @you-yourcompany.testinator.com. So any email to anything@you-yourcompany.testinator.com will arrive in your private domain. On the left of the Web User Interface you'll see "Private Team Inbox". If you click that you'll be taken to the web interface for your private domain. Unlike Public Mailinator inboxes, you can see ALL incoming email to all inboxes at once! The inbox field in the upper right allows you to filter that incoming domain.
To see what your current Private Domain is, go the Team Settings section of the Web interface and you'll see it listed. You can leave it as is, change it to another subdomain, or even put in a domain you already own (you must change your MX DNS record of your domain to point to our servers for this to work).
On the Team Settings page, you'll also notice your API token. This token allows you to access all email in Mailinator (public and private) via API instead of the Web. See our API documentation below.
The Team Management screen allows you to add co-workers to your account so they too can access your private domain emails. Also, checkout the Message Routing Rules system. While it's great to read emails via the web or API, Mailinator will push emails to you via webhooks. You can set this up in the Rules System.
Single Sign-On
Mailinator Enterprise subscriptions support Single Sign-On (SSO) using SAML. Please contact support (support@manybrain.com) for more information or help with configuration.
Private Webhooks
Mailinator allows you to HTTP Post or Webhook messages into your Private Domain. This is extremely convenient for testing as now all your test emails, SMS messages, and Webhooks will reside in the same place and are accessible via same Web Interface, API, and Rule System.
This command will deliver the message to the "bob" inbox
curl -v -d '{"from":"someplace@xyz.com", "subject":"testing", "text" : "helloworld", "to" : "jack" }'
-H "Content-Type: application/json"
-X POST "https://www.mailinator.com/api/v2/domains/<your_webhook_token>/webhook/bob/"
There are several permutations of the Webhook URLS. Say your Private Domain is mypd.com then all of the following urls are identical:
https://www.mailinator.com/api/v2/domains/<wh-token>/webhook/
https://www.mailinator.com/api/v2/domains/mypd.com/webhook/?whtoken=<wh-token>
https://www.mailinator.com/api/v2/domains/private/webhook/?whtoken=<wh-token>
The incoming Webhook will arrive in the inbox designated by the "to" field in the incoming JSON payload. If the incoming payload does not contain a "to" field, or you wish to override the incoming destination, you may specify the desination inbox in the url:
https://www.mailinator.com/api/v2/domains/<token>/webhook/bob
Incoming Webhooks are delivered to Mailinator inboxes and from that point onward are not notably different than other messages in the system (i.e. emails). You may retrieve such messages via the Web Interface, the API, or the Rule System. See the following documentation on the Message API for more information.
As normal, Mailinator will list all messages in the Inbox page and via the Inbox API calls. If the incoming JSON payload does not contain a "from" or "subject", then dummy values will be inserted in these fields.
Twilio
Mailinator intends to apply specific mappings for certain services that commonly publish webhooks.
If you test incoming Messages to SMS numbers via Twilio, you may use this endpoint to correctly map "to", "from", and "subject" of those messages to the Mailinator system. By default, the destination inbox is the Twilio phone number. This may be overridden by specifying the destination inbox in the URL (second example below).
https://www.mailinator.com/api/v2/domains/<wh-token>/twilio/
https://www.mailinator.com/api/v2/domains/<wh-token>/twilio/someinbox
The Mailinator API
The Mailinator API provides programmatic access to the Mailinator system. This includes fetching and injecting messages into the Mailinator system and creating routing rules for specific message domains within the system. Messages are typically (and historically) email messages. Hence the format of messages tend to look like emails but in reality any message can be fed, routed, and read or delivered through the system. In a broader scope messages generally arrive via email, SMS, or direct HTTP Post.
Subscribers can read messages in both the Public and their own Private Mailinator email systems with the API. They may also route/inject messages but only to their Private Mailinator domains.
Access to the API (and messages in general) are subject to your subscription plan's rate limits.
Definitions
- Messages
Messages within Mailinator are typically thought of as emails - however, messages can enter the system in a variety of ways including email, SMS, or HTTP Post. In general, the schema of messages contains a TO, FROM, SUBJECT, and message body. Message bodies can be simple string of text or - as is allowed by email standards, a complicated multi-part, multi-encoded schema.
- Domains
Domains identify a specific source for messages. Emails automatically are assigned to the domain of their "to" address. Expectedly, each of your Private Domains represent a specific source for messages. Each Domain may have it's own set of rules.
SDK
Mailinator provides several official SDKs. Please select your language in the upper right to see examples in your preferred language.
Java:
https://github.com/manybrain/mailinator-java-client
Javascript:
https://github.com/manybrain/mailinator-javascript-client
C#:
https://github.com/manybrain/mailinator-csharp-client
Go:
https://github.com/manybrain/mailinator-go-client
Ruby:
https://github.com/manybrain/mailinator-ruby-client
Maven:
<dependencies>
<dependency>
<groupId>com.manybrain</groupId>
<artifactId>mailinator-client</artifactId>
<version>1.0</version>
</dependency>
</dependencies>
Gradle:
compile 'com.manybrain:mailinator-client:1.0'
API Authentication
To authorize, use this code:
# REST calls require your team's API token in every call
curl "https://api.mailinator.com/api_endpoint_here?token=YourTeamAPIToken"
or
curl --header "Authorization: YourTeamAPIToken"
"https://api.mailinator.com/api_endpoint_here"
MailinatorClient mailinatorClient = new MailinatorClient("YourTeamAPIToken");
const mailinatorClient = new MailinatorClient("YourTeamAPIToken");
MailinatorClient mailinatorClient = new MailinatorClient("YourTeamAPIToken");
mailinatorClient := mailinator.NewMailinatorClient("YourTeamAPIToken")
mailinatorClient = MailinatorClient::Client.new(auth_token: "YourTeamAPIToken")
Replace YourTeamAPIToken with the API Token found on your Team's settings page
Mailinator uses API tokens for authentication. All calls to the API must include the token query parameter OR included as an HTTP Authorization header.
Message API
Fetch Inbox (aka Fetch Message Summaries)
This endpoint retrieves a list of messages summaries. You can retreive a list by inbox, inboxes, or entire domain.
curl "https://mailinator.com/api/v2/domains/private/inboxes/testinbox?limit=2&sort=descending"
Response:
{
"domain": "yourprivatedomain.com",
"to": "testinbox"
"msgs": [
{
"subject": "this is a test email 1",
"domain": "yourprivatedomain.com",
"from": "Our Qa Tester <qatester@company.com>"
"id": "testinbox-1571155952-33840774",
"to": "testinbox",
"time": 1571155952000,
"seconds_ago": 258277
},
{
"subject": "This is my test email [with attachment]",
"domain": "yourprivatedomain.com",
"from": "Our Qa Tester <qatester@company.com>"
"id": "testinbox-1570635306-12914603",
"to": "testinbox",
"time": 1570635306000,
"seconds_ago": 778923
}
],
}
}
Inbox inbox = mailinatorClient.request(new GetInboxRequest("private"));
List<Message> messages = inbox.getMsgs();
for (Message m : messages) {
String subject = m.getSubject();
List<Part> parts = m.getParts();
// process message
}
mailinatorClient.request(new GetInboxRequest(domain.name))
.then(response => {
const result = response.result;
const msgs = result?.msgs;
if (msgs !== undefined) {
msgs.forEach((msg) => {
const subject = msg.subject;
const parts = msg.parts;
..
// process message
})
}
});
FetchInboxRequest fetchInboxRequest = new FetchInboxRequest()
{
Domain = "yourDomainNameHere",
Inbox = "yourInboxHere",
Skip = 0,
Limit = 20,
Sort = Sort.asc
};
FetchInboxResponse fetchInboxResponse = await mailinatorClient.MessagesClient.FetchInboxAsync(fetchInboxRequest);
res, err := mailinatorClient.FetchInbox(&FetchInboxOptions{Domain: "yourDomainNameHere", Inbox: "yourInboxHere"})
response = mailinatorClient.messages.fetch_inbox(domain:"yourDomainNameHere", inbox: "yourInboxHere", skip: 0, limit: 50, sort: "ascending", decodeSubject: false)
HTTP Request
GET https://mailinator.com/api/v2/domains/:domain/inboxes/:inbox
| Path Element | Value | Description |
|---|---|---|
| :domain | public | Fetch Message Summaries from the Public Mailinator System |
| private | Fetch Message Summaries from all Your Private Domains | |
| [your_private_domain.com] | Fetch Message Summaries from a specific Private Domain | |
| :inbox | null | Fetch All Messages summaries for an entire domain |
| * | Fetch All Messages summaries for an entire domain | |
| [inbox_name] | Fetch All Messages summaries for a given Inbox | |
| [inbox_name*] | Fetch All Messages summaries for a given Inbox Prefix |
Query Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| skip | 0 | no | skip this many emails in your Private Domain |
| limit | 50 | no | number of emails to fetch from your Private Domain |
| sort | descending | no | Sort results by ascending or descending |
| decode_subject | false | no | true: decode encoded subjects |
Fetch Message
This endpoint retrieves a specific message by id.
curl "https://mailinator.com/api/v2/domain/private/inboxes/testinbox/messages/testinbox-1570635306-12914603"
Response:
{
"fromfull": "Our Qa Tester <qatester.company.com>",
"headers": {
"mime-version": "1.0",
"date": "Tue, 15 Oct 2019 12:12:20 -0400",
"subject": "this is a test email 1",
"content-type": "multipart/mixed",
},
"subject": "this is a test email 1",
"parts": [
{
"headers": {
"content-type": "text/plain; charset=\"UTF-8\""
},
"body": "here is our test email\r\n"
},
{
"headers": {
"content-type": "text/html; charset=\"UTF-8\""
},
"body": "<div dir=\"ltr\"><div class=\"gmail_default\"
style=\"font-family:tahoma,sans-serif;font-size:large\">
here's the test email</div></div>\r\n"
},
{
"headers": {
"content-disposition": "attachment; filename=\"notes.pdf\"",
"content-transfer-encoding": "base64",
"content-type": "application/pdf; name=\"notes.pdf\"",
},
"body": "iVBO4JYRUE2VGk85o6MBpC9E1frV8djCh24TVzy6CdiTEFkJoFGwRxy0jeivb3t8f6+e+uo4P==="
}
],
"from": "Our Qa Tester",
"to": "testinbox",
"id": "testinbox-1570635306-12914603",
"time": 1571155952000,
"seconds_ago": 260276
}
// Message m = mailinatorClient.request(
// new GetMessageRequest("<domain>", "<inbox-name>", "<msg-id>"));
Message m = mailinatorClient.request(
new GetMessageRequest("private", "testinbox", "testinbox-1570635306-12914603"));
List<Parts> parts = m.getParts();
String subject = m.getSubject();
Map<String, Object> headers = m.getHeaders();
mailinatorClient.request(new GetMessageRequest("<domain>", "<inbox-name>", "<msg-id>"))
.then(response => {
const result = response.result;
const parts = result?.parts;
const subject = result?.subject;
const headers = result?.headers;
});
FetchMessageRequest fetchMessageRequest = new FetchMessageRequest()
{
Domain = "yourDomainNameHere",
Inbox = "yourInboxHere",
MessageId = "yourMessageIdHere"
};
FetchMessageResponse fetchMessageResponse = await mailinatorClient.MessagesClient.FetchMessageAsync(fetchMessageRequest);
res, err := mailinatorClient.FetchMessage(&FetchMessageOptions{"yourDomainNameHere", "yourInboxHere", "yourMessageIdHere"})
response = mailinatorClient.messages.fetch_message(domain:"yourDomainNameHere", inbox: "yourInboxHere", messageId: "yourMessageIdHere")
HTTP Request
GET https://mailinator.com/api/v2/domains/:domain/inboxes/:inbox/messages/:message_id
| Path Element | Value | Description |
|---|---|---|
| :domain | public | Fetch Message Summaries from the Public Mailinator System |
| private | Fetch Message Summaries from any Private Domains | |
| [your_private_domain.com] | Fetch Message from a specific Private Domain | |
| :inbox | [inbox_name] | Fetch Message for this inbox |
| :message_id | [msg_id] | Fetch Message with this ID (found via previous Message Summary call) |
Fetch an SMS Messages
SMS messages go into an inbox by the name of their phone number. Retrieving them is the same as any other message, simply use the phone number as the Inbox you are fetching.
HTTP Request
GET https://mailinator.com/api/v2/domains/:domain/inboxes/:YOUR_TEAM_SMS_NUMBER
Fetch List of Attachments
This endpoint retrieves a list of attachments for a message. Note attachments are expected to be in Email format.
curl "https://mailinator.com/api/v2/domain/private/inboxes/testinbox/messages/testinbox-1570635306-12914603/attachments"
Response:
{
"attachments": [
{
"filename": "notes.pdf",
"content-disposition": "attachment; filename=\"notes.pdf\"",
"content-transfer-encoding": "base64",
"content-type": "application/pdf",
"attachment-id": 0
}
]
}
List<Attachment> attachments = mailinatorClient.request(
new GetAttachmentsRequest("private", "testinbox", "testinbox-1570635306-12914603"));
mailinatorClient.request(new GetAttachmentsRequest("private", "testinbox", "testinbox-1570635306-12914603"))
.then(response => {
const result = response.result;
const attachments = result?.attachments;
if (attachments !== undefined) {
attachments.forEach((element)=>{
const filename = element.filename;
});
}
});
FetchAttachmentsRequest fetchAttachmentsRequest = new FetchAttachmentsRequest()
{
Domain = "yourDomainNameHere",
Inbox = "yourInboxHere",
MessageId = "yourMessageIdWithAttachmentHere"
};
FetchAttachmentsResponse fetchAttachmentsResponse = await mailinatorClient.MessagesClient.FetchAttachmentsAsync(fetchAttachmentsRequest);
res, err := mailinatorClient.FetchAtachments(&FetchAttachmentsOptions{"yourDomainNameHere", "yourInboxHere", "yourMessageIdWithAttachmentHere"})
response = mailinatorClient.messages.fetch_attachments(domain:"yourDomainNameHere", inbox: "yourInboxHere", messageId: "yourMessageIdWithAttachmentHere")
HTTP Request
GET https://mailinator.com/api/v2/domains/:domain/inboxes/:inbox/messages/:message_id/attachments
Fetch Links
This endpoint retrieves all links found within a given email
curl "https://mailinator.com/api/v2/domain/private/inboxes/testinbox/messages/testinbox-1570635306-12914603/links"
Response:
{
"links": [
"https://www.yoursite.com/activate",
"https://www.yoursite.com/privacy",
"https://www.facebook.com/oursitepage"
]
}
List<Links> links = mailinatorClient.request(
new GetLinksRequest("private", "testinbox", "testinbox-1570635306-12914603"));
mailinatorClient.request(new GetLinkssRequest("private", "testinbox", "testinbox-1570635306-12914603"))
.then(response => {
const result = response.result;
const links = result?.links;
if (links !== undefined) {
links.forEach((link)=>{
...
});
}
});
FetchLinksRequest fetchLinksRequest = new FetchLinksRequest()
{
Domain = "yourDomainNameHere",
Inbox = "yourInboxHere",
MessageId = "yourMessageIdWithAttachmentHere"
};
FetchLinksResponse fetchLinksResponse = await mailinatorClient.MessagesClient.FetchLinksAsync(fetchLinksRequest);
res, err := mailinatorClient.FetchMessageLinks(&FetchMessageLinksOptions{"yourDomainNameHere", "yourInboxHere", "yourMessageIdHere"})
response = mailinatorClient.messages.fetch_message_links(domain:"yourDomainNameHere", inbox: "yourInboxHere", messageId: "yourMessageIdHere")
HTTP Request
GET https://mailinator.com/api/v2/domains/:domain/inboxes/:inbox/messages/:message_id/links
Fetch Attachment
This endpoint retrieves a list of attachments for a message. Note attachments are expected to be in Email format.
curl "https://mailinator.com/api/v2/domain/private/inboxes/testinbox/messages/testinbox-1570635306-12914603/attachments/nodes.pdf"
// Attachment attachment = mailinatorClient.request(
// new GetAttachmentRequest("<domain>", "<inbox-name>", "<msg-id>", attachmentId));
Attachment attachment = mailinatorClient.request(
new GetAttachmentRequest("private", "testinbox", "testinbox-1570635306-12914603", 1));
const file = fs.createWriteStream("filename");
mailinatorClient.request(new GetAttachmentRequest("<domain>", "<inbox-name>", "<msg-id>", attachmentId))
.then(response => {
response.result!.pipe(file);
});
FetchAttachmentRequest fetchAttachmentRequest = new FetchAttachmentRequest()
{
Domain = "yourDomainNameHere",
Inbox = "yourInboxHere",
MessageId = "yourMessageIdWithAttachmentHere",
AttachmentId = "yourAttachmentIdHere"
};
FetchAttachmentResponse fetchAttachmentResponse = await mailinatorClient.MessagesClient.FetchAttachmentAsync(fetchAttachmentRequest);
res, err := mailinatorClient.FetchAttachment(&FetchAttachmentOptions{"yourDomainNameHere", "yourInboxHere", "yourMessageIdWithAttachmentHere", "yourAttachmentIdHere"})
response = mailinatorClient.messages.fetch_attachment(domain:"yourDomainNameHere", inbox: "yourInboxHere", messageId: "yourMessageIdWithAttachmentHere", attachmentId: "yourAttachmentIdHere")
HTTP Request
GET https://mailinator.com/api/v2/domains/:domain/inboxes/:inbox/messages/:message_id/attachments/:attachment_name
Note that alternatively, you specify the "attachment-id" value instead of the attachment name.
Delete ALL Messages (by Domain)
curl -X DELETE "https://mailinator.com/api/v2/domains/private/inboxes/"
Response:
{
"status" : "ok",
"messages_deleted" : 1048
}
DeletedMessages deletedMessages = mailinatorClient.request(
new DeleteDomainMessagesRequest("private"));
System.out.println(deletedMessages.getCount() + " messages deleted");
mailinatorClient.request(new DeleteDomainMessagesRequest("private"))
.then(response => {
const count = response.result!.count;
});
DeleteAllDomainMessagesRequest deleteAllDomainMessagesRequest = new DeleteAllDomainMessagesRequest()
{
Domain = "yourDomainNameHere"
};
DeleteAllDomainMessagesResponse deleteAllDomainMessagesResponse =
await mailinatorClient.MessagesClient.DeleteAllDomainMessagesAsync(deleteAllDomainMessagesRequest);
res, err := mailinatorClient.DeleteAllDomainMessages(&DeleteAllDomainMessagesOptions{"yourDomainNameHere"})
response = mailinatorClient.messages.delete_all_domain_messages(domain:"yourDomainNameHere")
DELETE https://mailinator.com/api/v2/domains/:domain/inboxes/
| Path Element | Value | Description |
|---|---|---|
| :domain | private | Delete ALL messages in all your private domains |
| [your_private_domain.com] | Delete all messages in a specific private domain | |
| :inbox | null | Delete from all inboxes, or |
| * | Delete from all inboxes |
Delete ALL Messages (by Inbox)
This endpoint deletes ALL messages from a specific private inbox.
curl -X DELETE "https://mailinator.com/api/v2/domains/private/inboxes/testinbox"
Response:
{
"status" : "ok",
"messages_deleted" : 11
}
DeletedMessages deletedMessages = mailinatorClient.request(new DeleteInboxMessagesRequest("private", "testinbox"));
System.out.println(deletedMessages.getCount() + " messages deleted");
mailinatorClient.request(new DeleteInboxMessagesRequest("private", "testinbox"))
.then(response => {
const count = response.result!.count;
});
DeleteAllInboxMessagesRequest deleteAllInboxMessagesRequest = new DeleteAllInboxMessagesRequest()
{
Domain = "yourDomainNameHere",
Inbox = "yourInboxHere"
};
DeleteAllInboxMessagesResponse deleteAllInboxMessagesResponse =
await mailinatorClient.MessagesClient.DeleteAllInboxMessagesAsync(deleteAllInboxMessagesRequest);
res, err := mailinatorClient.DeleteAllInboxMessages(&DeleteAllInboxMessagesOptions{"yourDomainNameHere", "yourInboxHere"})
response = mailinatorClient.messages.delete_all_inbox_messages(domain:"yourDomainNameHere", inbox: "yourInboxHere")
DELETE https://mailinator.com/api/v2/domains/:domain/inboxes/:inbox
| Path Element | Value | Description |
|---|---|---|
| :domain | private | Delete all messages from an inbox from any private domain |
| [your_private_domain.com] | Delete all messages from an inbox from a specific private domain | |
| :inbox | [inbox_name] | Delete all messages from a specific inbox |
Delete a Message
This endpoint deletes a specific messages
curl -X DELETE "https://mailinator.com/api/v2/domains/private/inboxes/testinbox/messages/testinbox-1570635306-12914603"
Response:
{
"status" : "ok",
"messages_deleted" : 1
}
mailinatorClient.request(new DeleteMessagesRequest("private"));
System.out.println(deletedMessages.getCount() + " messages deleted");
mailinatorClient.request(new DeleteMessageRequest("private", "testinbox", "testinbox-1570635306-12914603"))
.then(response => {
const count = response.result!.count;
});
DeleteMessageRequest deleteMessageRequest = new DeleteMessageRequest()
{
Domain = "yourDomainNameHere",
Inbox = "yourInboxHere",
MessageId = "yourMessageIdHere"
};
DeleteMessageResponse deleteMessageResponse = await mailinatorClient.MessagesClient.DeleteMessageAsync(deleteMessageRequest);
res, err := mailinatorClient.DeleteMessage(&DeleteMessageOptions{"yourDomainNameHere", "yourInboxHere", "yourMessageIdHere"})
response = mailinatorClient.messages.delete_message(domain:"yourDomainNameHere", inbox: "yourInboxHere", messageId: "yourMessageIdHere")
DELETE https://mailinator.com/api/v2/domains/:domain/inboxes/:inbox/messages/:message_id
| Path Element | Value | Description |
|---|---|---|
| :domain | private | Delete message from any private domain |
| [your_private_domain.com] | Delete message from a specific private domain | |
| :inbox | [inbox_name] | Delete message from a specific inbox |
| :message_id | [message_id] | Delete message with this ID |
Inject a Message (HTTP Post messages)
curl -d '{"from":"ourtest@xyz.com", "subject":"testing message", "text" : "hello world" }'
-H "Content-Type: application/json"
-X POST "https://mailinator.com/api/v2/domains/private/inboxes/testinbox/messages"
Response:
{
"status" : "ok",
"id" : "testinbox-3282929-109191"
}
MessageToPost msgToPost = new MessageToPost("subject", "from", "text_body");
mailinatorClient.request(new PostMessageRequest("private", "testinbox", msgToPost));
const msg = new MessageToPost("subject", "from", "text")
mailinatorClient.request(new PostMessageRequest("private", "testinbox", msg))
.then(response => {
const count = response.result!.id;
});
MessageToPost messageToPost = new MessageToPost()
{
Subject = "Testing message",
From = "test_email@test.com",
Text = "Hello World!"
};
InjectMessageRequest injectMessageRequest = new InjectMessageRequest()
{
Domain = "yourDomainNameHere",
Inbox = "yourInboxHere",
Message = messageToPost
};
InjectMessageResponse injectMessageResponse = await mailinatorClient.MessagesClient.InjectMessageAsync(injectMessageRequest);
message := MessageToPost{
Subject: "Testing message",
From: "test_email@test.com",
Text: "Hello World!",
}
res, err := mailinatorClient.InjectMessage(&InjectMessageOptions{"yourDomainNameHere", "yourInboxHere", message})
messageToPost = {
subject:"Testing ruby message",
from:"test_email_ruby@test.com",
text:"I love Ruby!"
}
response = mailinatorClient.messages.inject_message(domain:"yourDomainNameHere", inbox: "yourInboxHere", messageToPost: messageToPost)
This endpoint allows you to deliver a JSON message into your private domain. This is similar to simply emailing a message to your private domain, except that you use HTTP Post and can programmatically inject the message.
Note that injected JSON Messages can have any schema they choose. However, if you want the Web interface to display them, they must follow a general email format with the fields of From, Subject, and Parts (see "Fetch Message" above).
POST https://mailinator.com/api/v2/domains/:domain/inboxes/:inbox
| Path Element | Value | Description |
|---|---|---|
| :domain | private | Inject to any (i.e. first) private domain |
| [your_private_domain.com] | Inject to specific private domain | |
| :inbox | [inbox_name] | TO destination for injected message |
Stats API
You may retrieve usage information for your Team using this API.
Get All domains
curl "https://api.mailinator.com/api/v2/team/stats"
Response:
{
"stats": [
{
"date": "20200921",
"retrieved": {
"web_private": 1029,
"web_public": 0,
"api_email": 983
"api_error": 1,
},
"sent": {
"sms": 0,
"email": 1990
}
},
{
"date": "20200922",
"retrieved": {
"web_private": 829,
"web_public": 2,
"api_email": 800
"api_error": 0,
},
"sent": {
"sms": 3,
"email": 1402
}
}
]
}
ADD JAVASCRIPT
ADD JAVA
GetTeamStatsResponse response = await mailinatorClient.StatsClient.GetTeamStatsAsync();
res, err := mailinatorClient.GetTeamStats()
response = mailinatorClient.stats.get_team_stats
HTTP Request
GET https://api.mailinator.com/api/v2/team/stats
Domains API
You may add or replace Private Domains in your Team Settings panel.
Get Usage Statistica
curl "https://api.mailinator.com/api/v2/team/stats"
Response:
{
"domains" :
[
{
"_id": "5c9602f5e881b5fbe91c754a",
"description": "Domain representing some testing",
"enabled": true,
"name": "my.test.domain",
"ownerid": "59188558619b4f3879751781",
"rules": []
}
]
}
mailinatorClient.request(new GetDomainsRequest())
.then(r => {
const domains = r.result;
domains?.domains.forEach((domain) => {
const name = domain.name;
// ...
})
});
GetAllDomainsResponse getAllDomainsResponse = await mailinatorClient.DomainsClient.GetAllDomainsAsync();
res, err := mailinatorClient.GetDomains()
response = mailinatorClient.domains.get_domains
The endpoint fetches a list of all your domains.
HTTP Request
GET https://api.mailinator.com/domains/
Get Domain
curl "https://api.mailinator.com/api/v2/domains/:domain_id"
Response:
{
"_id": "5c9602f5e881b5fbe91c754a",
"description": "Domain representing some testing",
"enabled": true,
"name": "my.test.domain.com",
"ownerid": "59188558619b4f3879751781",
"rules": []
}
mailinatorClient.request(new GetDomainRequest("domain_id"))
.then(r => {
const domain = r.result;
const name = domain?.name;
// ...
});
GetDomainRequest getDomainRequest = new GetDomainRequest()
{
DomainId = "yourDomainIdHere"
};
GetDomainResponse getDomainResponse = await mailinatorClient.DomainsClient.GetDomainAsync(getDomainRequest);
res, err := mailinatorClient.GetDomain(&GetDomainOptions{"yourDomainIdHere"})
response = mailinatorClient.domains.get_domain(domainId:"yourDomainIdHere")
The endpoint fetches a specific domain
HTTP Request
GET https://api.mailinator.com/domains/:domain_id
PATH
| Parameter | Default | Required | Description |
|---|---|---|---|
| :domain_id | (none) | true | This must be the Domain name or the Domain id |
Rules API
You may define domain-specific rules to process incoming messages. Rules are executed in priority order (Rules with equal priority run simultaneously).
Rules contain one or more conditions and one or more actions.
Rules Schema
Example:
{
"_id": "5c9602f5e881b5fbe91c754a",
"description": "Rule to post all incoming mail starting with test* to my webhook",
"enabled": true,
"name": "testprefixpost",
"conditions": [
{
"operation": "PREFIX",
"field": "to",
"value": "test"
}
],
"actions": [
{
"action" : "WEBHOOK",
"destination": "my_webhook1"
}
]
}
| Field | User Modifiable | Description |
|---|---|---|
| _id | no | System generated, unique Rule Id. You may use this ID to query a specific rule |
| name | yes | Names must be lowercase and 1-20 characters. They may only contain alphanumeric, dot, and underscore. |
| description | yes | 1-255 characters |
| enabled | yes | Enabled rules are immediately active. |
| match | yes | Indicates condition matching type - must be ANY, ALL, or ALWAYS_MATCH |
| priority | yes | An Integer between 1-99999 governing rule execution order. 1 is the highest priority, 99999 is the lowest. |
| conditions | yes | Conditions must be an array Conditions objects - see below |
| actions | yes | Actions must be an array of Actions objects - see below |
Conditions Schema
Conditions are executed to determine if a particular incoming message matches this rule.
Match Type
| Match | Description |
|---|---|
| ANY | Matches if ANY of the conditions are true |
| ALL | Matches if ALL of the conditions are true |
| ALWAYS_MATCH | Always matches |
Conditions Schema
| Field | Description | Valid Values |
|---|---|---|
| operation | Comparison operation for field and value. | EQUALS, PREFIX |
| field | The message field to compare. | to |
| value | The value to compare. | Any - E.g., "joe", "bob" |
Condition Operations
| Operation | Description |
|---|---|
| EQUALS | Matches when the field (e.g. "to") exactly matches an inbox (e.g. "joe") |
| PREFIX | Matches when the field (e.g. "to") starts with a string (e.g. "test" matches "test", "test1", "test9999") |
Actions Schema
Actions are executed if the condition set returns true
Actions Schema
| Field | Description |
|---|---|
| action | Specific action to take if the rule condition was true |
| action_data | A JsonObject containting action specific data (see below) |
Actions
| Action | Description | Action Data |
|---|---|---|
| WEBHOOK | POST JSON version of message to HTTP Rest Endpoint | url : your HTTP Rest Endpoint url |
| DROP | Drop this email. No further rules will execute |
Create Rule
Create Rule
curl -H "content-type: application/json"
-X POST "https://api.mailinator.com/api/v2/domains/:domain_id/rules/"
-d "@data.json"
(data.json):
{
"description": "Rule to post all incoming mail starting with test* to my webhook",
"enabled": true,
"name": "testprefixpost",
"conditions": [
{
"operation": "PREFIX",
"condition_data": {
"field": "to",
"value": "test"
}
}
],
"actions": [
{
"action" : "WEBHOOK",
"action_data": {
"url" : "https://www.mywebsite.com/restendpoint"
}
}
]
}
Response:
{
"_id": "5c9602f5e881b5fbe91c754a",
"description": "Rule to post all incoming mail starting with test* to my webhook",
"enabled": true,
"name": "testprefixpost",
"conditions": [
{
"operation": "PREFIX",
"condition_data": {
"field": "to",
"value": "test"
}
}
],
"actions": [
{
"action" : "WEBHOOK",
"action_data": {
"url" : "https://www.mywebsite.com/restendpoint"
}
}
]
}
const actionData = new ActionData();
actionData.url = "https://www.mywebsite.com/restendpoint";
const action = new Action();
action.action = ActionType.WEBHOOK;
action.action_data = actionData;
const condition = new Condition();
condition.operation = OperationType.EQUALS;
condition.value = "raul";
const ruleToCreate = new RuleToCreate();
ruleToCreate.name = 'rule name';
ruleToCreate.priority = 15;
ruleToCreate.conditions = [condition];
ruleToCreate.actions = [action];
mailinatorClient.request(new CreateRuleRequest("domain_id", ruleToCreate))
.then(r => {
const rule = r.result;
const name = rule?.name;
// ...
});
RuleToCreate ruleToCreate = new RuleToCreate()
{
Name = "RuleName",
Priority = 15,
Description = "Description",
Conditions = new List<Condition>()
{
new Condition()
{
Operation = OperationType.PREFIX,
ConditionData = new ConditionData()
{
Field = "to",
Value = "raul"
}
}
},
Enabled = true,
Match = MatchType.ANY,
Actions = new List<ActionRule>() { new ActionRule() { Action = ActionType.WEBHOOK, ActionData = new ActionData() { Url = "https://www.google.com" } } }
};
CreateRuleRequest createRuleRequest = new CreateRuleRequest()
{
DomainId = "yourDomainIdHere",
Rule = ruleToCreate
};
CreateRuleResponse createRuleResponse = await mailinatorClient.RulesClient.CreateRuleAsync(createRuleRequest);
rule := RuleToCreate{
Name: "RuleName",
Priority: 15,
Description: "Description",
Conditions: []Condition{
Condition{
Operation: OperationType("PREFIX"),
ConditionData: ConditionData{
Field: "to",
Value: "raul",
},
},
},
Enabled: true,
Match: MatchType("ANY"),
Actions: []ActionRule{
ActionRule{
Action: ActionType("WEBHOOK"),
ActionData: ActionData{
Url: "https://www.google.com",
},
},
},
}
res, err := mailinatorClient.CreateRule(&CreateRuleOptions{"yourDomainIdHere", rule})
ruleToPost = {
name: "RuleName",
priority: 15,
description: "Description",
conditions: [
{
operation: "PREFIX",
condition_data: {
field: "to",
value: "raul"
}
}
],
enabled: true,
match: "ANY",
actions: [
{
action: "WEBHOOK",
action_data: {
url: "https://www.google.com"
}
}
]
}
response = mailinatorClient.rules.create_rule(domainId:"yourDomainIdHere", ruleToPost: ruleToPost)
This endpoint allows you to create a Rule. Note that in the examples, ":domain_id" can be one of your private domains.
HTTP Request
POST https://api.mailinator.com/api/v2/domains/:domain_id/rules/
PATH
| Parameter | Default | Description |
|---|---|---|
| :domain_id | (none) | This must be the Domain name or the Domain id (i.e. your private domain) |
POST Parameters
| Parameter | Default | Required | Description |
|---|---|---|---|
| name | (none) | true | Names must be lowercase and 1-15 characters. They may only contain alphanumeric, dot, and underscore. |
| description | (none) | false | 1-255 characters |
| enabled | true | false | Rules create enabled are immediately active. |
| match | ALL | false | Indicates condition matching type - must be ANY or ALL |
| priority | (none) | true | An Integer between 1-99999 governing rule execution order. 1 is the highest priority, 99999 is the lowest. |
| conditions | (none) | true | Conditions must be an array Conditions objects |
| actions | (none) | true | Actions must be an array of Actions objects |
Enable Rule
curl -X PUT "https://api.mailinator.com/api/v2/domains/:domain_id/rules/:rule_id?action=enable"
Response:
{
"status": "ok"
}
mailinatorClient.request(new EnableRuleRequest("domain_id", "rule_id"))
.then(r => {
const statusCode = r.statusCode;
// ...
});
EnableRuleRequest enableRuleRequest = new EnableRuleRequest()
{
DomainId = "yourDomainIdHere",
RuleId = "yourRuleIdHere"
};
EnableRuleResponse enableRuleResponse = await mailinatorClient.RulesClient.EnableRuleAsync(enableRuleRequest);
res, err := mailinatorClient.EnableRule(&EnableRuleOptions{"yourDomainIdHere", "yourRuleIdHere"})
response = mailinatorClient.rules.enable_rule(domainId:"yourDomainIdHere", ruleId: "yourRuleIdHere")
This endpoint allows you to enable an existing Rule
HTTP Request
PUT https://api.mailinator.com/api/v2/domains/:domain_id/rules/:rule_id?action=enable
PATH
| Parameter | Default | Required | Description |
|---|---|---|---|
| :domain_id | (none) | true | This must be the Domain name or the Domain id |
| :rule_id | (none) | true | This must be the Rule name or the Domain id |
Disable Rule
curl -X PUT "https://api.mailinator.com/api/v2/domains/:domain_id/rules/:rule_id/?action=disable"
Response:
{
"status": "ok"
}
mailinatorClient.request(new DisableRuleRequest("domain_id", "rule_id"))
.then(r => {
const statusCode = r.statusCode;
// ...
});
DisableRuleRequest disableRuleRequest = new DisableRuleRequest()
{
DomainId = "yourDomainIdHere",
RuleId = "yourRuleIdHere"
};
DisableRuleResponse disableRuleResponse = await mailinatorClient.RulesClient.DisableRuleAsync(disableRuleRequest);
res, err := mailinatorClient.DisableRule(&DisableRuleOptions{"yourDomainIdHere", "yourRuleIdHere"})
response = mailinatorClient.rules.disable_rule(domainId:"yourDomainIdHere", ruleId: "yourRuleIdHere")
This endpoint allows you to disable an existing Rule
HTTP Request
PUT https://api.mailinator.com/api/v2/domains/:domain_id/rules/:rule_id?action=disable
PATH
| Parameter | Default | Required | Description |
|---|---|---|---|
| :domain_id | (none) | true | This must be the Domain name or the Domain id |
| :rule_id | (none) | true | This must be the Rule name or the Domain id |
Get All Rules
curl "https://api.mailinator.com/api/v2/domains/:domain_id/rules/"
Response:
{
"rules" :
[
{
"_id": "5c9602f5e881b5fbe91c754a",
"description": "Rule to post all incoming mail to test1 or test2, then drop the email",
"enabled": true,
"match" : "ANY",
"name": "testprefixpost",
"conditions": [
{
"operation": "EQUALS",
"condition_data": {
"field": "to",
"value": "test1"
}
},
{
"operation": "EQUALS",
"condition_data": {
"field": "to",
"value": "test2"
}
}
],
"actions" : [
{
"action" : "WEBHOOK",
"action_data": {
"url" : "https://www.mywebsite.com/restendpoint"
}
},
{
"action" : "DROP"
}
]
}
]
}
mailinatorClient.request(new GetRulesRequest("domain_id"))
.then(r => {
const result = r.result;
const rules = result?.rules;
// ...
});
GetAllRulesRequest getAllRulesRequest = new GetAllRulesRequest()
{
DomainId = "yourDomainIdHere"
};
GetAllRulesResponse getAllRulesResponse = await mailinatorClient.RulesClient.GetAllRulesAsync(getAllRulesRequest);
res, err := mailinatorClient.GetAllRules(&GetAllRulesOptions{"yourDomainIdHere"})
response = mailinatorClient.rules.get_all_rules(domainId:"yourDomainIdHere")
This endpoint fetches all Rules for a Domain
HTTP Request
GET https://api.mailinator.com/api/v2/domains/:domain_id/rules/
PATH
| Parameter | Default | Description |
|---|---|---|
| :domain_id | (none) | This must be the Domain name or the Domain id |
Get Rule
curl "https://mailinator.com/api/v2/domains/:domain_id/rules/:rule_id"
Response:
{
"_id": "5c9602f5e881b5fbe91c754a",
"description": "Rule to post all incoming mail to test1 or test2, then drop the email",
"enabled": true,
"match" : "ANY",
"name": "testprefixpost",
"conditions": [
{
"operation": "EQUALS",
"condition_data": {
"field": "to",
"value": "test1"
}
},
{
"operation": "EQUALS",
"condition_data": {
"field": "to",
"value": "test2"
}
}
],
"actions" : [
{
"action" : "WEBHOOK",
"action_data": {
"url" : "https://www.mywebsite.com/restendpoint"
}
},
{
"action" : "DROP"
}
]
}
mailinatorClient.request(new GetRuleRequest("domain_id", "rule_id"))
.then(r => {
const result = r.result;
const name = result?.name;
// ...
});
GetRuleRequest getRuleRequest = new GetRuleRequest()
{
DomainId = "yourDomainIdHere",
RuleId = "yourRuleIdHere"
};
GetRuleResponse getRuleResponse = await mailinatorClient.RulesClient.GetRuleAsync(getRuleRequest);
res, err := mailinatorClient.GetRule(&GetRuleOptions{"yourDomainIdHere", "yourRuleIdHere"})
response = mailinatorClient.rules.get_rule(domainId:"yourDomainIdHere", ruleId: "yourRuleIdHere")
This endpoint fetches a Rules for a Domain
HTTP Request
GET https://api.mailinator.com/api/v2/domains/:domain_id/rules/:rule_id
PATH
| Parameter | Default | Description |
|---|---|---|
| :domain_id | (none) | This must be the Domain name or the Domain id |
| :rule_id | (none) | This must be the rule name or the Rule id |
Delete Rule
curl -X DELETE "https://api.mailinator.com/api/v2/domains/:domain_id/rules/:rule_id"
Response:
{
"status" : "ok"
}
mailinatorClient.request(new DeleteRuleRequest("domain_id", "rule_id"))
.then(r => {
const result = r.result;
const status = result?.status;
// ...
});
DeleteRuleRequest deleteRuleRequest = new DeleteRuleRequest()
{
DomainId = "yourDomainIdHere",
RuleId = "yourRuleIdHere"
};
DeleteRuleResponse deleteRuleResponse = await mailinatorClient.RulesClient.DeleteRuleAsync(deleteRuleRequest);
res, err := mailinatorClient.DeleteRule(&DeleteRuleOptions{"yourDomainIdHere", "yourRuleIdHere"})
response = mailinatorClient.rules.delete_rule(domainId:"yourDomainIdHere", ruleId: "yourRuleIdHere")
This endpoint deletes a specific Rule from a Domain
HTTP Request
DELETE https://api.mailinator.com/api/v2/domains/:domain_id/rules/:rule_id
PATH
| Parameter | Default | Description |
|---|---|---|
| :domain_id | (none) | This must be the Domain name or the Domain id |
| :rule_id | (none) | This must be the rule name or the Rule id |