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

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" in requests that pass JSON parameters.

Mailboxes

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

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 mailboxes 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 \
  -H "Content-Type:application/json"

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 \
  -H "Content-Type:application/json"

If you want to create a new mailbox which will do the forwarding to external address external@external.com, add an optional field forwarding_to with external email address value. Its only use is when you want to create forwardings immediately with mailbox creation as in example below.

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

If you want setup internal, private mailbox and restrict it to receive messages only via Migadu outgoing servers, please set option is_internal to "true" like in the example below. Note that no external messages would be accepted.

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

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",
   "identities":[],
   "local_part":"demo",
   "footer_active":false,
   "footer_html_body":null,
   "footer_plain_body":null,
   "may_access_imap":true,
   "may_access_managesieve":false,
   "may_access_pop3":true,
   "may_receive":true,
   "may_send":true,
   "is_internal":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 \
  -H "Content-Type:application/json"

Mailboxes/DELETE

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

Identities

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

Identities/INDEX

To get all identities of a mailbox pass a GET request as in the example below, where demo@mydomain.org is the mailbox.

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

Identities/SHOW

Individual identities are accessible by their local part for individual operations. For example, to show information of identity example@mydomain.org of mailbox 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/identities/example

Identities/CREATE

To create a new identity example@mydomain.org on the mailbox demo@mydomain.org we can call the identities API as in the example below.

$ curl -u MIGADU_USER:USER_TOKEN \
  -d '{"name":"Identity Name", "local_part":"example", "password":"Sup3r_s3cr3T"}' \
  -X POST https://api.migadu.com/v1/domains/mydomain.org/mailboxes/demo/identities \
  -H "Content-Type:application/json"

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

{
   "local_part":"example",
   "address":"example@mydomain.org",
   "domain_name":"mydomain.org",
   "footer_active":false,
   "footer_html_body":null,
   "footer_plain_body":null,
   "may_access_imap":true,
   "may_access_managesieve":false,
   "may_access_pop3":true,
   "may_receive":true,
   "may_send":true,
   "name":"Identity Name"
}

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

Identities/UPDATE

$ curl -u MIGADU_USER:USER_TOKEN \
  -d '{"name":"Identity Updated Name"}' \
  -X PUT https://api.migadu.com/v1/domains/mydomain.org/mailboxes/demo/identities/example \
  -H "Content-Type:application/json"

Identities/DELETE

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

Forwardings

Forwardings API allows retrieval and management of forwardings on mailboxes on existing domain hosted in your organization.

Forwardings/INDEX

To get all forwardings on existing mailbox demo@mydomain.org we can call the API as in example below:

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

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

Forwardings/SHOW

Individual forwardings are accessible by their full address as individual operations. For example, to show information of forwarding external@external.com of mailbox 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/forwardings/external@external.com

Forwardings/CREATE

To create a new forwarding on existing mailbox demo@mydomain.org we can call the API as in example below:

$ curl -u MIGADU_USER:USER_TOKEN \
  -d '{"address":"user@external.com"}' \
  -X POST https://api.migadu.com/v1/domains/mydomain.org/mailboxes/demo/forwardings \
  -H "Content-Type:application/json"

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

{
  "address": "user@external.com",
  "blocked_at": null,
  "confirmation_sent_at": "2024-12-09T16:34:47Z" ,
  "confirmed_at": null,
  "expires_on": null,
  "is_active": true,
  "remove_upon_expiry": null
}

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

Forwardings/UPDATE

$ curl -u MIGADU_USER:USER_TOKEN \
  -d '{"is_active":true, "expires_on":"2024-12-31", "remove_upon_expiry": true}' \
  -X PUT https://api.migadu.com/v1/domains/mydomain.org/mailboxes/demo/identities/example \
  -H "Content-Type:application/json"

Note that expires_on field is accepting only future dates, if past date is provided it will return HTTP 400 status code as bad request.

Forwardings/DELETE

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

Aliases

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

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 \
  -H "Content-Type:application/json"

If you want setup internal, private alias and restrict it to receive messages only via Migadu outgoing servers, please set option is_internal to "true" like in the example below. Note that no external messages would be accepted.

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

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",
   "is_internal":"true",
   "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 \
  -H "Content-Type:application/json"

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.

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 \
  -H "Content-Type:application/json"

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 \
  -H "Content-Type:application/json"

Rewrites/DELETE

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