Mailboxes

Mailboxes

Mailgun Mailbox API allows you to programmatically create as many mailboxes as you wish. The incoming messages can be stored in mailboxes. There is no HTTP API to fetch the contents of the mailboxes: you need to use POP3 or IMAP protocols for that.

Warning

Currently Mailgun stores mailbox passwords in plain text. This is not acceptable for some applications. We are considering changing this in the future.

GET /<domain>/mailboxes

Fetches the list of mailboxes for a given domain.

Parameter Description
limit Maximum number of records to return. (100 by default)
skip Number of records to skip. (0 by default) 
POST /<domain>/mailboxes

Creates a new mailbox for a supplied domain

Parameter Description
mailbox The name of the mailbox, for example bob.lee
password Mailbox password. 
PUT /<domain>/mailboxes/<mailbox>

Updates the specified mailbox. Currently only the password can be changed.

Parameter Description
password Mailbox password. 
DELETE /<domain>/mailboxes/<mailbox>

Deletes the given mailbox.

Examples

Listing all mailboxes:

def get_mailboxes
  RestClient.get "https://api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0"\
  "@api.mailgun.net/v2/samples.mailgun.org/mailboxes"
end

Response:

{
  "total_count": 5,
  "items": [
    {
      "size_bytes": null,
      "created_at": "Sat, 29 Oct 2011 08:33:05 GMT",
      "mailbox": "gino.heyman@samples.mailgun.org"
    },
    {
      "size_bytes": 0,
      "created_at": "Tue, 27 Sep 2011 20:24:22 GMT",
      "mailbox": "postmaster@samples.mailgun.org"
    },
    {
      "size_bytes": 0,
      "created_at": "Wed, 07 Dec 2011 09:27:54 GMT",
      "mailbox": "rahulk@samples.mailgun.org"
    },
    {
      "size_bytes": null,
      "created_at": "Mon, 23 Jan 2012 11:10:29 GMT",
      "mailbox": "sergeyo@samples.mailgun.org"
    },
    {
      "size_bytes": 0,
      "created_at": "Thu, 06 Oct 2011 10:22:36 GMT",
      "mailbox": "user@samples.mailgun.org"
    }
  ]
}

Creating a new mailbox:

def create_mailbox
  RestClient.post "https://api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0"\
  "@api.mailgun.net/v2/samples.mailgun.org/mailboxes",
  :mailbox => "sergeyo@samples.mailgun.org",
  :password => "secret"
end

Response:

{
  "message": "Created 1 mailboxes"
}

Updating the password for a given mailbox:

def update_password
  RestClient.put "https://api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0"\
  "@api.mailgun.net/v2/samples.mailgun.org/mailboxes/sergeyo",
  :password => "supersecret"
end

Response:

{
  "message": "Password changed"
}

Deleting a given mailbox:

def delete_mailbox
  RestClient.delete "https://api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0"\
  "@api.mailgun.net/v2/samples.mailgun.org/mailboxes/sergeyo"
end

Response:

{
  "message": "Mailbox has been deleted",
  "spec": "sergeyo@samples.mailgun.org"
}

Listing all mailboxes:

public static ClientResponse GetMailboxes() {
       Client client = Client.create();
       client.addFilter(new HTTPBasicAuthFilter("api",
                       "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"));
       WebResource webResource =
               client.resource("https://api.mailgun.net/v2/samples.mailgun.org" +
                               "/mailboxes");
       return webResource.get(ClientResponse.class);
}

Response:

{
  "total_count": 4,
  "items": [
    {
      "size_bytes": null,
      "created_at": "Sat, 29 Oct 2011 08:33:05 GMT",
      "mailbox": "gino.heyman@samples.mailgun.org"
    },
    {
      "size_bytes": 0,
      "created_at": "Tue, 27 Sep 2011 20:24:22 GMT",
      "mailbox": "postmaster@samples.mailgun.org"
    },
    {
      "size_bytes": null,
      "created_at": "Fri, 11 Nov 2011 17:53:04 GMT",
      "mailbox": "sergeyo@samples.mailgun.org"
    },
    {
      "size_bytes": 0,
      "created_at": "Thu, 06 Oct 2011 10:22:36 GMT",
      "mailbox": "user@samples.mailgun.org"
    }
  ]
}

Creating a new mailbox:

public static ClientResponse CreateMailbox() {
       Client client = Client.create();
       client.addFilter(new HTTPBasicAuthFilter("api",
                       "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"));
       WebResource webResource =
               client.resource("https://api.mailgun.net/v2/samples.mailgun.org" +
                               "/mailboxes");
       MultivaluedMapImpl formData = new MultivaluedMapImpl();
       formData.add("mailbox", "sergeyo@samples.mailgun.org");
       formData.add("password", "secret");
       return webResource.type(MediaType.APPLICATION_FORM_URLENCODED).
               post(ClientResponse.class, formData);
}

Response:

{
  "message": "Created 1 mailboxes"
}

Updating the password for a given mailbox:

public static ClientResponse UpdatePassword() {
       Client client = Client.create();
       client.addFilter(new HTTPBasicAuthFilter("api",
                       "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"));
       WebResource webResource =
               client.resource("https://api.mailgun.net/v2/samples.mailgun.org" +
                               "/mailboxes/sergeyo");
       MultivaluedMapImpl formData = new MultivaluedMapImpl();
       formData.add("password", "supersecret");
       return webResource.type(MediaType.APPLICATION_FORM_URLENCODED).
               put(ClientResponse.class, formData);
}

Response:

{
  "message": "Password changed"
}

Deleting a given mailbox:

public static ClientResponse DeleteMailbox() {
       Client client = Client.create();
       client.addFilter(new HTTPBasicAuthFilter("api",
                       "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"));
       WebResource webResource =
               client.resource("https://api.mailgun.net/v2/samples.mailgun.org" +
                               "/mailboxes/sergeyo");
       return webResource.delete(ClientResponse.class);
}

Response:

{
  "message": "Mailbox has been deleted",
  "spec": "sergeyo@samples.mailgun.org"
}

Listing all mailboxes:

function get_mailboxes() {
  $request =
    new HttpRequest('https://api.mailgun.net/v2/samples.mailgun.org/mailboxes',
                    HttpRequest::METH_GET);
  $auth = base64_encode('api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  $request->setHeaders(array('Authorization' => 'Basic '.$auth));
  $request->send();
  return $request;
}

Response:

{
  "total_count": 4,
  "items": [
    {
      "size_bytes": null,
      "created_at": "Sat, 29 Oct 2011 08:33:05 GMT",
      "mailbox": "gino.heyman@samples.mailgun.org"
    },
    {
      "size_bytes": 0,
      "created_at": "Tue, 27 Sep 2011 20:24:22 GMT",
      "mailbox": "postmaster@samples.mailgun.org"
    },
    {
      "size_bytes": null,
      "created_at": "Mon, 14 Nov 2011 18:05:48 GMT",
      "mailbox": "sergeyo@samples.mailgun.org"
    },
    {
      "size_bytes": 0,
      "created_at": "Thu, 06 Oct 2011 10:22:36 GMT",
      "mailbox": "user@samples.mailgun.org"
    }
  ]
}

Creating a new mailbox:

function create_mailbox() {
  $request =
    new HttpRequest('https://api.mailgun.net/v2/samples.mailgun.org/mailboxes',
                    HttpRequest::METH_POST);
  $auth = base64_encode('api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  $request->setHeaders(array('Authorization' => 'Basic '.$auth));
  $request->setPostFields(array('mailbox' => 'sergeyo@samples.mailgun.org',
                                'password' => 'secret'));
  $request->send();
  return $request;
}

Response:

{
  "message": "Created 1 mailboxes"
}

Updating the password for a given mailbox:

function update_password() {
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL,
              'https://api.mailgun.net/v2/samples.mailgun.org/mailboxes/'.
              'sergeyo');
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD,
              'api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS,
              http_build_query(array('password' => 'supersecret')));
  $r = curl_exec($ch);
  curl_close($ch);
  return $r;
}

Response:

{
  "message": "Password changed"
}

Deleting a given mailbox:

function delete_mailbox() {
  $request =
    new HttpRequest('https://api.mailgun.net/v2/samples.mailgun.org/mailboxes'.
                    '/sergeyo',
                    HttpRequest::METH_DELETE);
  $auth = base64_encode('api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0');
  $request->setHeaders(array('Authorization' => 'Basic '.$auth));
  $request->send();
  return $request;
}

Response:

{
  "message": "Mailbox has been deleted",
  "spec": "sergeyo@samples.mailgun.org"
}

Listing all mailboxes:

def get_mailboxes():
    r = requests.\
        get(("https://api.mailgun.net/v2/samples.mailgun.org/"
             "mailboxes"),
            auth=("api", "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"))
    return r

Response:

{
  "total_count": 5,
  "items": [
    {
      "size_bytes": null,
      "created_at": "Sat, 29 Oct 2011 08:33:05 GMT",
      "mailbox": "gino.heyman@samples.mailgun.org"
    },
    {
      "size_bytes": 0,
      "created_at": "Tue, 27 Sep 2011 20:24:22 GMT",
      "mailbox": "postmaster@samples.mailgun.org"
    },
    {
      "size_bytes": 0,
      "created_at": "Wed, 07 Dec 2011 09:27:54 GMT",
      "mailbox": "rahulk@samples.mailgun.org"
    },
    {
      "size_bytes": null,
      "created_at": "Mon, 06 Feb 2012 19:50:21 GMT",
      "mailbox": "sergeyo@samples.mailgun.org"
    },
    {
      "size_bytes": 0,
      "created_at": "Thu, 06 Oct 2011 10:22:36 GMT",
      "mailbox": "user@samples.mailgun.org"
    }
  ]
}

Creating a new mailbox:

def create_mailbox():
    r = requests.\
        post(("https://api.mailgun.net/v2/samples.mailgun.org/"
              "mailboxes"),
             auth=("api", "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"),
             data={"mailbox": "sergeyo@samples.mailgun.org",
                   "password": "secret"}
             )
    return r

Response:

{
  "message": "Created 1 mailboxes"
}

Updating the password for a given mailbox:

def update_password():
    r = requests.\
        put(("https://api.mailgun.net/v2/samples.mailgun.org/"
             "mailboxes/sergeyo"),
            auth=("api", "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"),
            data={"password": "supersecret"}
            )
    return r

Response:

{
  "message": "Password changed"
}

Deleting a given mailbox:

def delete_mailbox():
    r = requests.\
        delete(("https://api.mailgun.net/v2/samples.mailgun.org/"
               "mailboxes/sergeyo"),
               auth=("api", "key-3ax6xnjp29jd6fds4gc373sgvjxteol0"))
    return r

Response:

{
  "message": "Mailbox has been deleted",
  "spec": "sergeyo@samples.mailgun.org"
}

Listing all mailboxes:

public static RestResponse GetMailboxes() {

       RestClient client = new RestClient();
       client.BaseUrl = "https://api.mailgun.net/v2";
       client.Authenticator =
               new HttpBasicAuthenticator("api",
                                          "key-3ax6xnjp29jd6fds4gc373sgvjxteol0");
       RestRequest request = new RestRequest();
       request.AddParameter("domain",
                            "samples.mailgun.org",
                            ParameterType.UrlSegment);
       request.Resource = "{domain}/mailboxes";
       return client.Execute(request);
}

Response:

{
  "total_count": 4,
  "items": [
    {
      "size_bytes": null,
      "created_at": "Sat, 29 Oct 2011 08:33:05 GMT",
      "mailbox": "gino.heyman@samples.mailgun.org"
    },
    {
      "size_bytes": 0,
      "created_at": "Tue, 27 Sep 2011 20:24:22 GMT",
      "mailbox": "postmaster@samples.mailgun.org"
    },
    {
      "size_bytes": null,
      "created_at": "Tue, 15 Nov 2011 09:25:31 GMT",
      "mailbox": "sergeyo@samples.mailgun.org"
    },
    {
      "size_bytes": 0,
      "created_at": "Thu, 06 Oct 2011 10:22:36 GMT",
      "mailbox": "user@samples.mailgun.org"
    }
  ]
}

Creating a new mailbox:

public static RestResponse CreateMailbox() {
       RestClient client = new RestClient();
       client.BaseUrl = "https://api.mailgun.net/v2";
       client.Authenticator =
               new HttpBasicAuthenticator("api",
                                          "key-3ax6xnjp29jd6fds4gc373sgvjxteol0");
       RestRequest request = new RestRequest();
       request.AddParameter("domain",
                            "samples.mailgun.org",
                            ParameterType.UrlSegment);
       request.Resource = "{domain}/mailboxes";
       request.AddParameter("mailbox", "sergeyo@samples.mailgun.org");
       request.AddParameter("password", "secret");
       request.Method = Method.POST;
       return client.Execute(request);
}

Response:

{
  "message": "Created 1 mailboxes"
}

Updating the password for a given mailbox:

public static RestResponse UpdatePassword() {
       RestClient client = new RestClient();
       client.BaseUrl = "https://api.mailgun.net/v2";
       client.Authenticator =
               new HttpBasicAuthenticator("api",
                                          "key-3ax6xnjp29jd6fds4gc373sgvjxteol0");
       RestRequest request = new RestRequest();
       request.AddParameter("domain",
                            "samples.mailgun.org", ParameterType.UrlSegment);
       request.Resource = "{domain}/mailboxes/{username}";
       request.AddUrlSegment("username", "sergeyo");
       request.AddParameter("password", "supersecret");
       request.Method = Method.PUT;
       return client.Execute(request);
}

Response:

{
  "message": "Password changed"
}

Deleting a given mailbox:

public static RestResponse DeleteMailbox() {
       RestClient client = new RestClient();
       client.BaseUrl = "https://api.mailgun.net/v2";
       client.Authenticator =
               new HttpBasicAuthenticator("api",
                                          "key-3ax6xnjp29jd6fds4gc373sgvjxteol0");
       RestRequest request = new RestRequest();
       request.AddParameter("domain",
                            "samples.mailgun.org", ParameterType.UrlSegment);
       request.Resource = "{domain}/mailboxes/{username}";
       request.AddUrlSegment("username", "sergeyo");
       request.Method = Method.DELETE;
       return client.Execute(request);
}

Response:

{
  "message": "Mailbox has been deleted",
  "spec": "sergeyo@samples.mailgun.org"
}

Creating a new mailbox:

curl -s -k --user api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0 \
    https://api.mailgun.net/v2/samples.mailgun.org/mailboxes \
    -F mailbox='user@samples.mailgun.org' \
    -F password='supasecret'

Response:

{
  "message": "Created 1 mailboxes"
}

Updating the password for a given mailbox:

curl -s -k --user api:key-3ax6xnjp29jd6fds4gc373sgvjxteol0 -X PUT \
    https://api.mailgun.net/v2/samples.mailgun.org/mailboxes/user \
    -F password='abc123'

Response:

{
  "message": "Password changed"
}

© Copyright 2011, Mailgun Inc.
Created using Sphinx 1.1.2.
Style for Mailgun Documentation based on ADCtheme Copyright (c) 2009, Corey Oordt.