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 they do, they will either not be delivered, or have their 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. either one your 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
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 systesm.
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 = joe THEN Post Webhook To https://mywebsite.com/endpoint
For a given Private domain, all emails that arrive to the "joe" inbox will be converted to JSON, and HTTP Posted to the designated endpoint.
For more information on configuring Rules, see the Rules API documentation below (The Mailinator Web interface is merely a front-end for this API).
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 (yes, already) have a Private domain. Every conceivable inbox 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 Mailinator was created and assigned to your account as your private domain. For example, your initial private domain would be something like @you-yourcompany.mailinator.com. So any email to anything@you-yourcompany.mailinator.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 stream.
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 the DNS record MX 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.
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 streams 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.
[Note: The V1 API will remain active. See the old documentation here: HERE]
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 / Streams
Domains (aka Streams) 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.
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"
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://api.mailinator.com/v2/domains/private/inboxes/testinbox?limit=2&sort=descending"
HTTP Request
GET https://api.mailinator.com/v2/domains/:domain/inboxes/:inbox
The above command returns the list of messages for the Inbox joe. It returns JSON structured like this:
{
"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
}
],
}
}
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://api.mailinator.com/v2/domain/private/inboxes/testinbox/messages/testinbox-1570635306-12914603"
The above command returns JSON structured like this:
{
"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
}
HTTP Request
GET https://api.mailinator.com/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://api.mailinator.com/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://api.mailinator.com/v2/domain/private/inboxes/testinbox/messages/testinbox-1570635306-12914603/attachments"
The above command returns JSON structured like this:
{
"attachments": [
{
"filename": "notes.pdf",
"content-disposition": "attachment; filename=\"notes.pdf\"",
"content-transfer-encoding": "base64",
"content-type": "application/pdf",
"attachment-id": 0
}
]
}
HTTP Request
GET https://api.mailinator.com/v2/domains/:domain/inboxes/:inbox/messages/:message_id/attachments
Fetch Attachment
This endpoint retrieves a list of attachments for a message. Note attachments are expected to be in Email format.
curl "https://api.mailinator.com/v2/domain/private/inboxes/testinbox/messages/testinbox-1570635306-12914603/attachments/nodes.pdf"
The above command returns the attachment file. In this example, it would return a pdf.
HTTP Request
GET https://api.mailinator.com/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)
This endpoint deletes ALL messages from a Private Domain. Caution: This action is irreversible.
curl -X DELETE "https://api.mailinator.com/v2/domains/private/inboxes/"
The above command returns JSON structured like this:
{
"status" : "ok",
"messages_deleted" : 1048
}
DELETE https://api.mailinator.com/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://api.mailinator.com/v2/domains/private/inboxes/testinbox"
The above command returns JSON structured like this:
{
"status" : "ok",
"messages_deleted" : 11
}
DELETE https://api.mailinator.com/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://api.mailinator.com/v2/domains/private/inboxes/testinbox/messages/testinbox-1570635306-12914603"
The above command returns JSON structured like this:
{
"status" : "ok",
"messages_deleted" : 1
}
DELETE https://api.mailinator.com/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://api.mailinator.com/v2/domains/private/inboxes/testinbox/"
The above command returns JSON structured like this:
{
"status" : "ok",
"id" : "testinbox-3282929-109191"
}
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://api.mailinator.com/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 |
Streams API
Several Streams are automatically created for you including ALL, SMS, and one for each of your private domains. You can also access streams without explicitly creating them, however you cannot assign rules to adhoc streams. You may add or replace Private Domains in your Team Settings panel.
Get All Streams
curl "https://api.mailinator.com/streams"
The above command returns JSON showing the newly created Stream:
{
"streams" :
[
{
"_id": "5c9602f5e881b5fbe91c754a",
"description": "Stream representing some testing",
"enabled": true,
"name": "my.test.stream",
"ownerid": "59188558619b4f3879751781",
"rules": []
}
]
}
The endpoint fetches a list of all your streams.
HTTP Request
GET https://api.mailinator.com/streams/
Get Stream
curl "https://api.mailinator.com/streams/:stream_id"
The above command returns JSON showing the newly created Stream:
{
"_id": "5c9602f5e881b5fbe91c754a",
"description": "Stream representing some testing",
"enabled": true,
"name": "my.test.stream",
"ownerid": "59188558619b4f3879751781",
"rules": []
}
The endpoint fetches a specific stream
HTTP Request
GET https://api.mailinator.com/streams/:stream_id
PATH
Parameter | Default | Required | Description |
---|---|---|---|
:stream_id | (none) | true | This must be the Stream name or the Stream id |
Rules API
You may define stream-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/streams/:stream_id/rules/"
-d "@data.json"
file: data.json
{
"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",
"action_data": {
"url" : "https://www.mywebsite.com/restendpoint"
}
}
]
}
The above command returns the created Rule:
{
"_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",
"action_data": {
"url" : "https://www.mywebsite.com/restendpoint"
}
}
]
}
This endpoint allows you to create a Rule. Note that in the examples, ":stream_id" can be one of your private domains.
HTTP Request
POST https://api.mailinator.com/streams/:stream_id/rules/
PATH
Parameter | Default | Description |
---|---|---|
:stream_id | (none) | This must be the Stream name or the Stream 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/streams/:stream_id/rules/:rule_id/enable"
The above command returns JSON::
{
"status": "ok"
}
This endpoint allows you to enable an existing Rule
HTTP Request
PUT https://api.mailinator.com/streams/:stream_id/rules/:rule_id/enable
PATH
Parameter | Default | Required | Description |
---|---|---|---|
:stream_id | (none) | true | This must be the Stream name or the Stream id |
:rule_id | (none) | true | This must be the Rule name or the Stream id |
Disable Rule
curl -X PUT "https://api.mailinator.com/streams/:stream_id/rules/:rule_id/disable"
The above command returns JSON::
{
"status": "ok"
}
This endpoint allows you to disable an existing Rule
HTTP Request
PUT https://api.mailinator.com/streams/:stream_id/rules/:rule_id/disable
PATH
Parameter | Default | Required | Description |
---|---|---|---|
:stream_id | (none) | true | This must be the Stream name or the Stream id |
:rule_id | (none) | true | This must be the Rule name or the Stream id |
Get All Rules
curl "https://api.mailinator.com/streams/:stream_id/rules/"
{
"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",
"field": "to",
"value": "test1"
},
{
"operation": "EQUALS",
"field": "to",
"value": "test2"
}
],
"actions" : [
{
"action" : "WEBHOOK",
"action_data": {
"url" : "https://www.mywebsite.com/restendpoint"
}
},
{
"action" : "DROP"
}
]
}
]
}
This endpoint fetches all Rules for a Stream
HTTP Request
GET https://api.mailinator.com/streams/:stream_id/rules/
PATH
Parameter | Default | Description |
---|---|---|
:stream_id | (none) | This must be the Stream name or the Stream id |
Get Rule
curl "https://api.mailinator.com/streams/:stream_id/rules/:rule_id"
{
"_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",
"field": "to",
"value": "test1"
},
{
"operation": "EQUALS",
"field": "to",
"value": "test2"
}
],
"actions" : [
{
"action" : "WEBHOOK",
"action_data": {
"url" : "https://www.mywebsite.com/restendpoint"
}
},
{
"action" : "DROP"
}
]
}
This endpoint fetches a Rules for a Stream
HTTP Request
GET https://api.mailinator.com/streams/:stream_id/rules/:rule_id
PATH
Parameter | Default | Description |
---|---|---|
:stream_id | (none) | This must be the Stream name or the Stream id |
:rule_id | (none) | This must be the rule name or the Rule id |
Delete Rule
curl -X DELETE "https://api.mailinator.com/streams/:stream_id/rules/:rule_id"
{
"status" : "ok"
}
This endpoint deletes a specific Rule from a Stream
HTTP Request
DELETE https://api.mailinator.com/streams/:stream_id/rules/:rule_id
PATH
Parameter | Default | Description |
---|---|---|
:stream_id | (none) | This must be the Stream name or the Stream id |
:rule_id | (none) | This must be the rule name or the Rule id |