Store(): A Temporary Mailbox For All Your Incoming Email

Mailgun Team

• 5 min read

Customers have recently approached us with a few use cases where the temporary storage of inbound emails would come in handy. In some cases, the attachments are large and cause time-outs when we try to POST the data to their servers. In other cases, there is a large volume of inbound email and customers would rather just run a GET request at some interval instead of having to handle multiple POSTs from us. Finally, it serves as redundancy in case their web service goes down and they can’t accept our POSTs.

These seem like good reasons to us, so we are pleased to announce the latest addition to Mailgun, Inbound Email Storage.

Storing Messages through Routes

You can store messages temporarily (up to 3 days) by creating a store() action using Routes. This action can be used in addition to the forward() or stop() actions with any filter.

The store action is available in the Routes tab of the admin panel or through the Routes API. When an incoming message matches a route with a store action, that message, and its attachments are stored on our servers for up to 3 days. If you provide a URL in the store action (using the notify keyword), then we will post the incoming message to it. This posted message will look like the ones received using the forward action except for the following changes.

The attachments will not be available under the attachment-x parameter and instead, a JSON blob under the attachments parameter will contain links to the attachments.
The content-id-map parameter is similarly changed; ids now map to attachment URLs instead of attachments.
The attachment-count parameter will not be available.

Here is an example of the attachments parameter.


1    [  
2       {
3  "url":"https://api.mailgun.org/v2/domains/mydomain.com/messages/WyJhOTM4NDk1ODA3Iiw/attachments/0",
4  "content-type":"image/jpeg",
5  "name":"my-attachment.jpeg",
6  "size":7465
7       }
8    ]

You can view the full list of parameters in the Storing and Retrieving Messages section of our User Manual.

Retrieving messages via events API

Every time a message is stored, a stored event is created and can be retrieved via the Events API. This way you can retrieve all your stored messages even if you don’t provide a webhook URL in the store action. The URL to retrieve the stored message will be in the data returned by the API. When you use that URL to get a stored message you will receive a JSON blob with the same parameters as the notify webhook from the store action except the token, timestamp, and signatureparameters won’t be there. An example request:


1    import requests  
2    r = requests.get("https://api.mailgun.net/v2/mydomain.com/events",  
3    auth=("api", "key-kjdh236r897rkwejhd98-sdjk3"))
4    
5    print r.json()['items'][0]['storage']['url']
6    
7    'https://api.mailgun.net/v2/domains/mydomain.com/messages/WyJhOTM4NDk1ODA3Iiw'

In addition to other data about the event, a URL is returned where you can GET the message. By default, the retrieved message will be a JSON blob but if you set the accept header to message/rfc2822, you can pull down the raw mime, attachments and all. You can also DELETE the message through the API, which we suggest you do once you retrieve it (it’s always nice to dispose of your trash :).

Sample application

To test it out we wrote this simple application to let us view our team’s daily status emails via the command line. All these emails are sent with a Mailgun Mailing List so it’s easy to identify which messages to store, we just use the mailing list alias. The code is below:


1    from requests import get
2    
3    from local import API_KEY
4    
5    MY_DOMAIN = "mailgun.net"
6    MY_STATUS_LIST = "status-updates@mailgun.net"
7    EVENTS_API_URL = "https://api.mailgun.net/v2/{}/events".format(MY_DOMAIN)
8    
9    def main():
10response = get(EVENTS_API_URL,
11               auth=('api', API_KEY),
12               params={
13                   "event": "stored"
14               })
15    
16events = response.json()
17    
18message_urls = [event['storage']['url'] for event in events['items']
19                if MY_STATUS_LIST in event['message']['recipients']]
20    
21for url in message_urls:
22    message = get(url,
23                  auth=('api', API_KEY)).json()
24    
25    print "From: ", message['from']
26    print '--------------------------- {} --------------------------------'.format(message['subject'])
27    print message['body-plain']
28    
29    if __name__ == "__main__":
30main()