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/

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.

Domains

Domain API allows information retrieval and management of existing domains hosted in your organization. Supported fields are listed in table below.

After reading all the API endpoints we support, you will notice that we do not expose the one for domain deletion, as that action is irreversible. As a precautionary measure, this option is available in the admin UI only.

Domains/INDEX

To get all domains for your organization, pass a GET request as in example below.

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

JSON response will return list of domains which you are allowed to get based on your organization permissions admin or domain_admin.

Domains/SHOW

Individual domains are accessible by their name for individual operations. For example, to show informations about domain mydomain.org we could call the API as in example below.

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

Domains/CREATE

To create a new domain which does not yet exist under your organization, issue a POST request as in example below.

Here is very important to pass hosted_dns parameter, as this parameter determines the type of DNS hosting you will be using.

We strongly recommend not use hosted_dns: true, as we plan to stop offering our DNS as solution soon

Avoiding this parameter in request will by default determine that your domain will be using external DNS for records setup.

According to email standards, some addresses (admin, postmaster, abuse) must exist on your domain. We recommend adding these right away by adding parameter create_default_addresses: true to POST request. If the parameter is omitted default addresses will not be created.

$ curl -u MIGADU_USER:USER_TOKEN \
  -X POST https://api.migadu.com/v1/domains \
  -d '{"name":"mydomain.org","create_default_addresses":"true","hosted_dns":"false"}'
  -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 domain.

{
  "name": "mydomain.org",
  "state": "inactive",
  "description": "",
  "tags": [],
  "activated_at": null,
  "deactivated_at": null,
  "recipient_denylist": "",
  "sender_allowlist": [],
  "sender_denylist": [],
  "spam_aggressiveness": 0,
  "can_access": false,
  "mx_proxy_enabled": false,
  "can_receive": false,
  "can_send": false,
  "catchall_destinations": [],
  "deactivated_at": null,
  "subject_rewriting_enabled": false,
  "junk_subject_keyword_spam": true,
  "hosted_dns": false
  "mailbox_default_incoming_limit": 500
  "mailbox_default_outgoing_limit": 100
  "mailbox_default_storage_limit": 0
  "mailbox_default_sending_enabled": true
  "mailbox_default_receiving_enabled": true
  "mailbox_default_imap_enabled": true
  "mailbox_default_pop3_enabled": true
  "mailbox_default_managesieve_enabled": true
}

Domains/UPDATE

To update domain fields you can issue PATCH request as in example below.

$ curl -u MIGADU_USER:USER_TOKEN \
  -d '{"tags":["work","business"],"description":"newly created domain"}' \
  -X PATCH https://api.migadu.com/v1/domains/mydomain.org \
  -H "Content-Type:application/json"

Domains/RECORDS

To retrieve DNS records which you need to configure your domain issue a GET request as in example below.

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

If the request was successful API will return status code 200 and JSON representation of records for your domain.

{
  "domain_name": "mydomain.org",
    "dkim": [
      {
        "name": "key1._domainkey",
        "type": "cname",
        "value": "key1.mydomain.org._domainkey.migadu.com."
      },
      {
        "name": "key2._domainkey",
        "type": "cname",
        "value": "key2.mydomain.org._domainkey.migadu.com."
      },
      {
        "name": "key3._domainkey",
        "type": "cname",
        "value": "key3.mydomain.org._domainkey.migadu.com."
      }
    ],
    "dmarc": {
      "name": "_dmarc",
      "type": "txt",
      "value": "v=DMARC1; p=quarantine;"
    },
    "dns_verification": {
      "name": "@",
      "type": "txt",
      "value": "RANDOM_VALUE"
    },
    "mx_records": [
      {
        "name": "@",
        "priority": 10,
        "type": "mx",
        "value": "aspmx1.migadu.com"
      },
      {
        "name": "@",
        "priority": 20,
        "type": "mx",
        "value": "aspmx2.migadu.com"
      }
    ],
    "spf": {
      "name": "@",
      "type": "txt",
      "value": "v=spf1 include:spf.migadu.com -all"
    }

}

Domains/DIAGNOSTICS

To run diagnostics checks after DNS was populated with the given records, issue a GET request as in example below.

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

If the request was succesfull JSON response will be returned with the status of your diagnostics checks.

Domains/ACTIVATE

When all records are set per instructions and diagnostics is passing, you can issue GET request to activate your domain like in example below.

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

If all records are set correctly and domain activated JSON response of domain itself will be returned with status code 200. Otherwise you will be returned status code 422 with JSON response messages.

{
  "error": "dns_check_failed",
  "message: "DNS checks failed, please check your DNS and try activating domain."
}

Domains/USAGE

To get messages and storage usage for domain, you can issue GET request to single endpoint.

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

Status code 200 will be returned with JSON presentation of the usage on the current date. Storage usage is returned in Gigabytes (GB).

{
  "domain_name": "mydomain.org",
  "incoming": 75,
  "outgoing": 20,
  "storage": 0.50
}

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",
   "delegations":[],
   "domain_name":"mydomain.org",
   "identities":[],
   "local_part":"demo",
   "expireable":false,
   "expires_on":null,
   "remove_upon_expiry":false,
   "may_access_imap":true,
   "may_access_managesieve":false,
   "may_access_pop3":true,
   "may_receive":true,
   "may_send":true,
   "is_internal":true,
   "wildcard_sender": false,
   "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. Such created identity will use as sender persona only.

$ curl -u MIGADU_USER:USER_TOKEN \
  -d '{"name":"Identity Name", "local_part":"example"}' \
  -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",
   "password_use":"none"
   "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.

To create new identity which uses the same password as mailbox, use parameter “password_use”:“mailbox” in the request. This will create identity which can be used as sender persona and user will be able to login with parent mailbox password.

$ curl -u MIGADU_USER:USER_TOKEN \
  -d '{"name":"Identity Name", "local_part":"example","password_use":"mailbox"}' \
  -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",
   "password_use":"mailbox"
   "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.

Creating identity with own password requires using parameter “password_use”:“custom” with setting also password parameter in request. This type of identities are mostly used as application specific mailboxes. To create this type of identities call the identities API as in example below:

$ curl -u MIGADU_USER:USER_TOKEN \
  -d '{"name":"Identity Name", "local_part":"example","password_use":"custom","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",
   "password_use":"custom"
   "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",
   "expireable":false,
   "expires_on":null,
   "remove_upon_expiry":false,
   "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