We’ve been busy adding a few quality-of-life features to our Messaging API that we think you’ll love!Here’s a quick list – read below for more details on the Mailinator API update.
| 1. Scheduled Delete | Schedule deletion of any message you retrieve with the API with &delete= |
| 2. Cursor Pagination | New way to paginate through your messages with &cursor= |
| 3. Expanding the Fetch Inbox API | You can now retrieve multiple, full messages for any inbox or domain in one API call with &full=true |
| 4. Wait for the next message | An API call that waits until a message arrives for a specific inbox or domain using &wait= |
| 5. Streaming !!!! | A New Stream API to get every message that arrives in your Private inbox through a persistent connection |
Mailinator has a lot of API Endpoints, but the two stars of the show for this Mailinator API Update are API call for Fetching an Inbox and Fetching a Message. The Inbox API has historically returned a list of “Message Summaries”, that is, the things you’d expect to see in any email system’s inbox. Things like from, to, subject, message-id, etc. – but notably, not any full messages.
Customers have typically called the Inbox API to get the list of available messages, then parse the Message Id’s and then fetched those messages with the Message API (using the ID as a key).
We have watched how our Customers have used our API and have added some features to make life easier! As you might guess, these new features are in Beta for now and only available to our paid plans. (Send bug reports please! support@manybrain.com)
Scheduled Delete
Pretty darn cool
The simplest pattern we see is that a Customer will fetch an email and then immediately follow that API call with another call to Delete the message. We have added a query parameter to help you do that.
// delete message 1 minute after this message retrieval
https://api.mailinator.com/api/v2/domains/private/messages/test-123-123&delete=1m
As always, this API call will fetch the full body of the test-123-123 message from your Private inbox.
That delete=1m parameter will schedule the deletion of the test-123-123 message for a minute from now. (That deletion value should be treated as a minimum, not a precise value). The delete= parameter accepts hours, minutes, or even seconds as in 1h, 5m, 10s. Note that the delete= parameter also works with the Inbox API. But be careful, it’s very easy to schedule the deletion of dozens of messages at once!
Cursor (Pagination)
Should have had this a long time ago
Mailinator has long supported skip and limit to navigate through your Message library. The Inbox API now returns a new value &cursor= . If you include that cursor value in your next Inbox API call, you’ll get the messages starting from that point. Every call to the Inbox API returns the cursor value for you to use in your next call.
// start inbox retrieval at where we left off from last call
https://api.mailinator.com/api/v2/domains/private/inboxes?cursor=373A382B
You can iterate multiple Inbox API calls with subsequent cursors to go through your entire message library.
Expanding the Inbox API to Full Messages
Saving you lots of API calls
The existing Inbox API looks something like this:
// current way to pull inboxes Summaries
https://api.mailinator.com/api/v2/domains/private/inboxes/joe*
The joe* at the end is optional. Without it, the call would pull the last 50 Message Summaries (id, to, from, subject, time) from your Private Inbox (from any and all of your Private Domains). With joe*, it fetches 50 Message Summaries from any inbox starting with joe*.
Great. But what if you wanted more than Message Summaries – what if you wanted the full messages?
// New: Pull multiple full messages from Private Domains (and/or specific inboxes)
https://api.mailinator.com/api/v2/domains/private/inboxes/joe*?full=true
Adding the full=true parameter (which for the Inbox API call is default false), you’ll get the entire messages, not just a Summaries. No need to call the Message API after this at all !
There’s a few things you need to be aware of with this call. Fetching multiple full messages can get heavy fast (and of course, each message counts toward your Subscription Plan’s daily total). Email messages vary in size greatly – from just a few bytes to several Megabytes.
A few hundred megabyte response to a single API call would probably be an unwanted surprise for everyonel The default limit for this API call is 1 with a current max of 5. Let’s see how that goes.
Waiting for the Next Message
Fetch from the Future
Historically, it’s been send the email first, fetch it second. What about the opposite? How about an API call that waits for email to arrive?
// Wait for the next message to arrive
https://api.mailinator.com/api/v2/domains/private/inboxes/joe*?wait=60s
https://api.mailinator.com/api/v2/domains/private/inboxes/?wait=120s
The wait= parameter tells the inbox API call to wait for future messages, instead of pulling from the past (it’s default behavior). The above calls will block until an email arrives that satisfies the query (or the wait interval times out). In the first example, it must be an email to any of my private domains and an inbox that must start with joe.
When the email arrives, the email is pushed to this query and the connection is closed. The limit is default 1 for this query, but can be increased up to 5. That is, the query will block until either the connection times-out, or 5 messages are received on the server. Any emails (up to 5) that were received until the timeout will be returned, even if it’s less than the limit. Also, the &full=true parameter works here too – you can get just Summaries or whole Messages depending on that parameter.
Note also that not all Http clients are ready to wait 2 minutes for a result. So you might have to tell certain clients to be able to wait longer without timeout.
As a reminder, Mailinator allows for trillions of different inboxes in your private domain. Using different inboxes really lets you demarcate your email usage – and especially for this type of Waiting API call. If it works in your workflow, always use a new and different inbox. You’ll never have to worry about colliding messages when parsing your test results.
Streaming
This is way cool…
Ok, what if you want ALL the messages? Near realtime, as they arrive. The Stream API Call opens a persistent connection that streams every incoming message (or summary) that matches the query to you, right now. One JSON payload per line (delimited by /r/n).
// stream every message summary arriving in any of your private domains
https://api.mailinator.com/api/v2/domains/private/stream/
https://api.mailinator.com/api/v2/domains/private/stream/joe
You can further modify this query with these query parameters:
| full | true or false, just like always for full Messages or Summaries (default: false) |
| limit | Close the connection after this many messages are delivered |
| throttleInterval | Rate limit the stream to sending once per some Interval (in milliseconds) |
| delete | format: 1h, 5m, etc. Each delivered message will be scheduled for deletion |
As you can imagine, streaming can send you a lot of messages very fast. If you are sending email at a high rate, use the throttleInterval=10s to send just a sampling of the incoming messages (in this case, 1 per 10 seconds). The system also includes built-in rate-limiters based on your Subscription plan.