Sign In

Introduction

Migadu provides a simple API intended to integrate with other systems. The API is still in early beta and not all functionalities are exposed. If you need a specific function, please open a support ticket and tell us about it.

API Keys

To access the API, you will need an API key. The keys are tied to your Migadu user account, meaning each user within the organization can have one or several own API keys.

Get a new API key by visiting My Account > API Keys. The function to create a new API key is in the submenu on the left. You can create multiple keys and give them specific names.

API Requests

All API calls should be pointed to the dedicated API endpoint:

https://api.migadu.com/v1/

The API uses HTTP Basic authentication over https. Username is the email address of the Migadu account and the password is the API key. Here is a simple curl example

$ curl -u MIGADU_USER:USER_TOKEN \
    https://api.migadu.com/v1/domains/mydomain.org/mailboxes \
    -H "Content-Type:application/json"

If the request succeeds, HTTP 200 status code will be returned along with relevant object. If it did not succeed, HTTP 400 status code will be returned.

All responses are always of application/json content type.

Data submitted in requests must also be of the same content type, so please include the Content-Type header "Content-Type:application/json".

Mailboxes

Mailboxes API allows information retrieval and management of mailboxes on an existing domain hosted in your organization.

Field Type Note
local_part String Read Only
domain String Read Only
address String Read Only
name String
may_send Boolean
may_receive Boolean
may_access_imap Boolean
may_access_pop3 Boolean
may_access_managesieve Boolean
password_method String Predefined Values
password String
password_recovery_email String
spam_action String Predefined Values
spam_aggressiveness String Predefined Values
sender_denylist String
sender_allowlist String
recipient_denylist String
autorespond_active Boolean
autorespond_subject String
autorespond_body String
autorespond_expires_on Date
footer_active String
footer_plain_body String
footer_html_body String

Mailboxes/INDEX

To get all mailboxes of a domain pass a GET request as in the example below, where mydomain.org is a domain on your account.

$ curl -u MIGADU_USER:USER_TOKEN \
  https://api.migadu.com/v1/domains/mydomain.org/mailboxes

Mailboxes/SHOW

Individual rewrites are accessible by their local part for individual operations. For example, to show mailbox information of demo@mydomain.org, we could call the API as in the example below.

$ curl -u MIGADU_USER:USER_TOKEN \
  https://api.migadu.com/v1/domains/mydomain.org/mailboxes/demo

Mailboxes/CREATE

To create a new mailbox demo@mydomain.org with admin panel name Mailbox Name and invite the future user of it at invitee@somewhere.tld to set own password, you can call the mailboxes API as in the example below.

$ curl -u MIGADU_USER:USER_TOKEN \
  -d '{"name":"Mailbox Name", "local_part":"demo", "password_method":"invitation", "password_recovery_email":"invitee@somewhere.tld"}' \
  -X POST https://api.migadu.com/v1/domains/mydomain.org/mailboxes

The field password_method is not required and it has a default value "password". Its only use is when you need to invite the mailbox owner to set own password. In that case password_method should be set to "invitation" and field password_recovery_email must be provided.

Alternatively, you could set the password immediately for the user as in the example below.

$ curl -u MIGADU_USER:USER_TOKEN \
  -d '{"name":"Mailbox Name","local_part":"demo", "password":"Sup3r_s3cr3T"}' \
  -X POST https://api.migadu.com/v1/domains/mydomain.org/mailboxes

If the request was successful, the API will return HTTP 200 status code and the JSON representation of the newly created mailbox.

{
   "address":"demo@mydomain.org",
   "autorespond_active":null,
   "autorespond_body":"Hi there,\n\nThank you for your message. I will be out of the office from [mm/dd] to [mm/dd] and will have limited access to email. If this is urgent, please contact [NAME] at [EMAIL] or [PHONE]. I will do my best to respond promptly to your email when I return on [mm/dd].\n\nBest,\n\n[MY NAME]\n",
   "autorespond_expires_on":null,
   "autorespond_subject":"Autoreply: {{subject}}",
   "delegations":[],
   "domain_name":"mydomain.org",
   "footer_active":false,
   "footer_html_body":null,
   "footer_plain_body":null,
   "identities":[],
   "local_part":"demo1",
   "may_access_imap":true,
   "may_access_managesieve":false,
   "may_access_pop3":true,
   "may_receive":true,
   "may_send":true,
   "name":"Mailbox Name",
   "password_recovery_email":"invitee@somewhere.tld",
   "recipient_denylist":[],
   "sender_allowlist":[],
   "sender_denylist":[],
   "spam_action":"folder",
   "spam_aggressiveness":"default"
}

If the request did not succeed, HTTP 400 status code will be returned.

Mailboxes/UPDATE

$ curl -u MIGADU_USER:USER_TOKEN \
  -d '{"name":"Mailbox Updated Name"}' \
  -X PUT https://api.migadu.com/v1/domains/mydomain.org/mailboxes/demo

Mailboxes/DELETE

$ curl -u MIGADU_USER:USER_TOKEN \
  -X DELETE https://api.migadu.com/v1/domains/mydomain.org/mailboxes/local_part

Aliases

Aliases API allows information retrieval and management of aliases on an existing domain hosted in your organization.

Field Type Note
local_part String Read Only
domain String Read Only
address String Read Only
destinations Array or CSV String

Aliases/INDEX

To get all aliases of a domain pass a GET request as in the example below, where mydomain.org is a domain on your account.

$ curl -u MIGADU_USER:USER_TOKEN \
  https://api.migadu.com/v1/domains/mydomain.org/aliases

Aliases/SHOW

Individual aliases are accessible by their local part for individual operations. For example, to show alias information of demo@mydomain.org, we could call the API as in the example below.

$ curl -u MIGADU_USER:USER_TOKEN \
  https://api.migadu.com/v1/domains/mydomain.org/aliases/demo

Aliases/CREATE

To create a new alias demo@mydomain.org with destinations one@mydomain.org and two@mydomain.org you can call the aliases API as in the example below. Note that aliases can redirect only on the same domain.

$ curl -u MIGADU_USER:USER_TOKEN \
  -d '{"local_part":"demo", "destinations": "one@domain.tld,two@domain.tld"}' \
  -X POST https://api.migadu.com/v1/domains/mydomain.org/aliases

If the request was successful, the API will return HTTP 200 status code and the JSON representation of the newly created mailbox.

{
   "address":"demo@mydomain.org",
   "domain_name":"mydomain.org",
   "local_part":"demo",
   "destinations":["one@mydomain.org","two@mydomain.org"]
}

If the request did not succeed, HTTP 400 status code will be returned.

Aliases/UPDATE

$ curl -u MIGADU_USER:USER_TOKEN \
  -d '{"destinations": "three@domain.tld"}' \
  -X PUT https://api.migadu.com/v1/domains/mydomain.org/aliases/demo

Aliases/DELETE

$ curl -u MIGADU_USER:USER_TOKEN \
  -X DELETE https://api.migadu.com/v1/domains/mydomain.org/aliases/demo

Rewrites

Rewrites are aliases that listen on predefined patterns. If the message recipient matches the pattern, the message if passed onto defined destinations. The destinations have to be on the same domain.

Rewrites API allows management of rewrites.

Field Type Note
domain String Read Only
name String Slug
local_part_rule String
order_num Integer
destinations Array or CSV String

Rewrites/INDEX

To get all rewrites of a domain pass a GET request as in the example below, where mydomain.org is a domain on your account.

$ curl -u MIGADU_USER:USER_TOKEN \
  https://api.migadu.com/v1/domains/mydomain.org/rewrites

Rewrites/SHOW

Individual rewrites are accessible by their name (slug) for individual operations.

$ curl -u MIGADU_USER:USER_TOKEN \
  https://api.migadu.com/v1/domains/mydomain.org/rewrites/demo

Rewrites/CREATE

To create a new rewrite named demo with pattern demo-* and destinations one@mydomain.org, two@mydomain.org you can call the rewrites API as in the example below. Note that rewrites must be on the same domain as destinations. Destination addresses on external domains will be rewritten.

$ curl -u MIGADU_USER:USER_TOKEN \
  -d '{"name":"demo", "local_part_rule":"demo-*", "destinations": "one@domain.tld,two@domain.tld"}' \
  -X POST https://api.migadu.com/v1/domains/mydomain.org/rewrites

If the request was successful, the API will return HTTP 200 status code and the JSON representation of the newly created mailbox.

{
   "name":"demo",
   "domain_name":"mydomain.org",
   "local_part_rule":"demo-*",
   "destinations":["one@mydomain.org","two@mydomain.org"]
}

If the request did not succeed, HTTP 400 status code will be returned.

Rewrites/UPDATE

$ curl -u MIGADU_USER:USER_TOKEN \
  -d '{"name":"demo1", "local_part_rule":"demo-*", "destinations": "one@domain.tld,two@domain.tld"}' \
  -X PUT https://api.migadu.com/v1/domains/mydomain.org/rewrites/demo

Rewrites/DELETE

$ curl -u MIGADU_USER:USER_TOKEN \
  -X DELETE https://api.migadu.com/v1/domains/mydomain.org/rewrites/demo