Email API

https://api.gandi.net/v5/email

Gandi Email Mailbox Management API

Introduction

This section of our documentation will assist you in the management of Gandi email mailboxes through our API.

General information on Gandi's email services can be found in our public documentation at:
https://docs.gandi.net/en/gandimail

A mailbox is:

  • attached to what we refer to as a "slot". Consequently, it is necessary to have at least one slot available before you can create a new mailbox.
  • available as one of two different types: Standard (with 3GB of storage), or Premium (with 50GB of storage)

Manage your forwarding addresses

https://api.gandi.net/v5/email/forwards/{domain}

Forwarding addresses make it possible to redirect mail from one or more of your domain's email addresses to an external address. Learn more on the documentation.

get List forwarding addresses

This route returns a paginated list of forwarded email addresses on the given domain.

Request

URI Parameters
    • domainstring
      Domain name.
Query String
  • Optional
    • destinationstring
      Filters the list by a destination pattern.
      Example: *@toto.net
      Example: john.doe@toto*
    • pageinteger

      Default: 1

      Minimum: 1

      Which result page to retrieve. If the number is greater than the last page, an empty list is returned.
    • per_pageinteger

      Minimum: 1

      How many items to display per page.
    • sort_bystring

      One of: "source", "-source", "destination", "-destination"

      Default: "source"

      Result sorting field.
    • sourcestring
      Filters the list by a source pattern.
      Example: *lice
      Example: alice
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
    Optional
    • Acceptstring
      When passed text/csv value, this route will return a CSV-formatted response.

Responses

200

Headers
    • Total-Countinteger
      Total number of items.
    Optional
    • Linkstring
      Links to next and last page.
Body
  • application/json
    array

    Of items of type:

    • object

      With the following properties:

      • destinationsarray[ string ]
        A list of email addresses.
      • hrefstring
        URL to forwarding address
      • sourcestring
        The source email address.
  • text/csv
    any
    CSV-formatted response.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

post Create a forwarding address

This route creates a new forwarding address to one or several destinations.

Request

URI Parameters
    • domainstring
      Domain name.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
Body
  • application/json
    object

    With the following properties:

    Required
    • destinationsarray[ string ]
      A list of email addresses.
    • sourcestring
      The source email address.
    Example:
    {
      "source": "alice",
      "destinations": [
        "alice.doe@example.org",
        "ruth@example.org"
      ]
    }

Responses

201

The resource has been created.
Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Forwarding address details

https://api.gandi.net/v5/email/forwards/{domain}/{source}

put Update a forwarding address

This route replaces a forwarding address' destinations.

Request

URI Parameters
    • domainstring
      Domain name.
    • sourcestring
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
Body
  • application/json
    object

    With the following properties:

    Required
    • destinationsarray[ string ]
      A list of email addresses.
    Example:
    {
      "destinations": [
        "alice@example.org"
      ]
    }

Responses

202

The request has been accepted.
Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

delete Delete a forwarding address

This route deletes a forwarding address.

Request

URI Parameters
    • domainstring
      Domain name.
    • sourcestring
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

202

The request has been accepted.
Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Manage your mailboxes

https://api.gandi.net/v5/email/mailboxes/{domain}

A mailbox belongs to a domain and is managed accordingly. Every API route takes a domain name as the first argument. Therefore, the user that is performing the operation must have sufficient permissions to modify the domain.

get List mailboxes

This route returns a list of all the mailboxes attached to a specific {domain}.

Request

URI Parameters
    • domainstring
      Domain name.
Query String
  • Optional
    • <created_atdatetime
      Slot creation date.
    • ~loginstring
      Filters the list by a login pattern.
      Example: *lice
      Example: alic*
    • antispamboolean
      Antispam is enabled or disabled
    • loginstring
      Filters the list by exact login.
    • mailbox_typestring

      One of: "standard", "premium", "standard_new", "premium_new"

    • pageinteger

      Default: 1

      Minimum: 1

      Which result page to retrieve. If the number is greater than the last page, an empty list is returned.
    • per_pageinteger

      Minimum: 1

      How many items to display per page.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
    Optional
    • Acceptstring
      When passed text/csv value, this route will return a CSV-formatted response.

Responses

200

A paginated list of the domain's mailboxes.
Headers
    • Total-Countinteger
      Total number of items.
    Optional
    • Linkstring
      Links to next and last page.
Body
  • application/json
    array

    Of items of type:

    • object

      With the following properties:

      • addressstring
        Full email address
      • alias_countinteger

        Default: 0

      • antispamboolean
        Antispam is enabled
      • domainstring
        Domain name
      • hrefstring
        Link to mailbox details
      • idstring
        Mailbox ID
      • loginstring
        Mailbox login
      • mailbox_typestring

        One of: "standard", "premium", "standard_new", "premium_new"

      • quota_usedinteger

        Default: 0

    Example:
    [
      {
        "domain": "example.net",
        "login": "alice",
        "address": "alice@example.net",
        "id": "066743e5-96e4-4a1d-9195-8b8a700a8a79",
        "mailbox_type": "standard",
        "quota_used": 1200,
        "alias_count": 2,
        "antispam": true,
        "href": "https://api.test/api/v5/email/example.net/066743e5-96e4-4a1d-9195-8b8a700a8a79"
      }
    ]
  • text/csv
    any
    CSV-formatted response.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

post Create a new mailbox

This route creates a new mailbox for the given domain. You will have to choose a mailbox_type.

Note that before you can create a mailbox, you must have a slot available (see Slot management).

Request

URI Parameters
    • domainstring
      Domain name.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
    Optional
    • Dry-Runinteger
      If this header's value is 1 the request's parameters will only be checked; the operation will not actually be performed.
Body
  • application/json
    object

    With the following properties:

    Required
    • loginstring

      Minimum length: 1

    • mailbox_typestring

      One of: "standard", "premium", "standard_new", "premium_new"

    • passwordstring

      Minimum length: 8

      Maximum length: 200

      Mailbox password.

      Must contain between 8 and 200 characters, containing at least 1 upper-case letter, 3 numbers, and a special character.

      You can also send a hashed password in SHA512-CRYPT ie: $6$xxxx$yyyy

    Optional
    • aliasesarray

      Of items of type:

      • string
        A local-part (what comes before the "@") of an email address. It can contain a wildcard "*" before or after at least two characters to redirect everything thats matches the local-part pattern.
    • antispamboolean

      Default: true

      Enable antispam
    Example:
    {
      "login": "alice",
      "mailbox_type": "standard",
      "password": "a*6@Xk86cPR2kcZ@qPAi",
      "aliases": [
        "bob",
        "bob*"
      ]
    }

Responses

200

Dry-Run response. You will get this response when you send your request. with a Dry-Run: 1 header.
Headers
  • Optional
    • Warningstring
      Warning message
Body
  • application/json
    object

    With the following properties:

    • statusstring

      One of: "success", "error"

      Response status.
    Optional
    • errorsarray
      A list of all the errors encountered during validation.

      Of items of type:

      • object

        With the following properties:

        • descriptionstring
          Error message.
        • locationstring

          One of: "header", "path", "querystring", "body"

          The field's location in the HTTP response.
        • namestring
          The xpath of the field.

202

The request has been accepted.
Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Mailbox details

https://api.gandi.net/v5/email/mailboxes/{domain}/{mailbox_id}

get Retrieve a mailbox

This route returns all the parameters linked to a specific mailbox.

Request

URI Parameters
    • domainstring
      Domain name.
    • mailbox_idstring
      Mailbox ID, of type UUID
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

200

Body
  • application/json
    object

    With the following properties:

    • addressstring
      Full email address
    • aliasesarray

      Default: []

      Mailbox alias list

      Of items of type:

      • string
        A local-part (what comes before the "@") of an email address. It can contain a wildcard "*" before or after at least two characters to redirect everything thats matches the local-part pattern.
    • antispamboolean
      Antispam is enabled
    • domainstring
      Domain name
    • hrefstring
      Link to mailbox details
    • idstring
      Mailbox ID
    • loginstring
      Mailbox login
    • mailbox_typestring

      One of: "standard", "premium", "standard_new", "premium_new"

    • quota_usedinteger

      Default: 0

    Optional
    • alias_countinteger

      Default: 0

    • fallback_emailstring
      Fallback email addresse
    • responderobject

      With the following properties:

      Optional
      • enabledboolean

        Default: false

        true if the responder is activated
      • ends_atdatetime
        responder end date
      • messagestring
        responder message
      • starts_atdatetime
        responder start date
    Example:
    {
      "domain": "mailbox-api-test-1.fr",
      "responder": {
        "message": "",
        "enabled": false
      },
      "mailbox_type": "standard",
      "login": "alice",
      "quota_used": 0,
      "antispam": true,
      "aliases": [
        "bob",
        "bob*"
      ],
      "address": "alice@example.net",
      "href": "https://api.test/api/v5/email/example.net/066743e5-96e4-4a1d-9195-8b8a700a8a79",
      "id": "066743e5-96e4-4a1d-9195-8b8a700a8a79"
    }

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

patch Update a mailbox

This route allows you to update a mailbox. This is how you can add aliases, change passwords, or activate/deactivate out-of-office replies on a given mailbox.

Request

URI Parameters
    • domainstring
      Domain name.
    • mailbox_idstring
      Mailbox ID, of type UUID
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
Body
  • application/json
    object

    With the following properties:

    Optional
    • aliasesarray

      Of items of type:

      • string
        A local-part (what comes before the "@") of an email address. It can contain a wildcard "*" before or after at least two characters to redirect everything thats matches the local-part pattern.
    • antispamboolean
      Enable or disable antispam
    • loginstring
    • passwordstring

      Minimum length: 8

      Maximum length: 200

      Mailbox password.

      Must contain between 8 and 200 characters, containing at least 1 upper-case letter, 3 numbers, and a special character.

      You can also send a hashed password in SHA512-CRYPT ie: $6$xxxx$yyyy

    • responderobject

      With the following properties:

      Optional
      • enabledboolean

        Default: false

        true if the responder is activated
      • ends_atdatetime
        responder end date
      • messagestring
        responder message
      • starts_atdatetime
        responder start date
    Example - Update a mailbox password:
    {
      "password": "lGv6KLZhbCgcX8pMK9Vx6mqrZC8vk84L"
    }
    Example - Activate responder:
    {
      "responder": {
        "enabled": true,
        "message": "Out of office",
        "starts_at": "2019-07-10T18:00:01Z",
        "ends_at": "2019-07-26T09:00:01Z"
      }
    }
    Example - Setup aliases:
    {
      "aliases": [
        "bob",
        "bob*"
      ]
    }

Responses

202

The request has been accepted.
Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

delete Delete a mailbox

This route allows you to delete a mailbox. The mailbox and all its contents will be permanently deleted. If you delete a mailbox for which you have purchased a slot, this action frees the slot so it once again becomes available for use with a new mailbox, or for deletion (to see how to delete a slot refer Slot management).

Request

URI Parameters
    • domainstring
      Domain name.
    • mailbox_idstring
      Mailbox ID, of type UUID
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

202

The request has been accepted.
Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Mailbox content management

https://api.gandi.net/v5/email/mailboxes/{domain}/{mailbox_id}/contents

delete Purge a mailbox

This method allows you to purge a mailbox. All mails and content within a specific mailbox will be deleted.

Request

URI Parameters
    • domainstring
      Domain name.
    • mailbox_idstring
      Mailbox ID, of type UUID
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

202

The request has been accepted.
Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Mailbox type management

https://api.gandi.net/v5/email/mailboxes/{domain}/{mailbox_id}/type

patch Upgrade or downgrade a mailbox offer

This method lets you upgrade or downgrade a mailbox offer.

If you choose to upgrade, you will be charged for the remaining time of the offer, with an updated price. If you downgrade, you will get a refund.

Request

URI Parameters
    • domainstring
      Domain name.
    • mailbox_idstring
      Mailbox ID, of type UUID
Query String
  • Optional
    • sharing_idstring
      Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
    Optional
    • Dry-Runinteger
      If this header's value is 1 the request's parameters will only be checked; the operation will not actually be performed.
Body
  • application/json
    object

    With the following properties:

    Required
    • mailbox_typestring

      One of: "standard", "premium", "standard_new", "premium_new"

      New mailbox type
    Example - Upgrade:
    {
      "mailbox_type": "premium"
    }
    Example - Downgrade:
    {
      "mailbox_type": "standard"
    }

Responses

200

Dry-Run response. You will get this response when you send your request. with a Dry-Run: 1 header.
Headers
  • Optional
    • Warningstring
      Warning message
Body
  • application/json
    object

    With the following properties:

    • statusstring

      One of: "success", "error"

      Response status.
    Optional
    • errorsarray
      A list of all the errors encountered during validation.

      Of items of type:

      • object

        With the following properties:

        • descriptionstring
          Error message.
        • locationstring

          One of: "header", "path", "querystring", "body"

          The field's location in the HTTP response.
        • namestring
          The xpath of the field.

202

The request has been accepted.
Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Migrate from packmail to the new mailbox offer

https://api.gandi.net/v5/email/migration/{domain}

get Show migration details

You need to use this route to get the migration token. This route returns the count of standard (3GB), standard_new (10GB), premium (50GB) and premium_new (50GB) purchased mailboxes. Also returns the count of mailboxes included with the domain and free.

Request

URI Parameters
    • domainstring
Query String
  • Optional
    • sharing_idstring
      Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

200

Body
  • application/json
    object

    With the following properties:

    • currencystring
      Currency used.
    • forward_countinteger
      Total number of forwards.
    • free_mailboxesinteger
      Total number of free mailboxes.
    • included_mailboxesinteger
      Total number of included mailboxes (offered with the domain).
    • infoarray
      Details of the mailbox migration.

      Of items of type:

      • object

        With the following properties:

        • loginstring
          Email login.
        • offer_v2string
          Mailbox type, it could be standard (3Gb), standard_new (10 Gb), premium (50Gb) or premium_new (50Gb).
        • price_v2number
          Yearly mailbox price.
        • price_v2_mnumber
          Monthly mailbox price.
        • quotanumber
          Quota of the mailbox before migration.
        • quota_v2number
          Quota of the mailbox after migration.
        • usagenumber
          Quota used.
    • packmailboolean
      Return True if the offer is still packmail.
    • price_v1number
      Total price before mailbox migration.
    • price_v2number
      Total price after mailbox migration.
    • quota_v1number
      Quota before mailbox migration.
    • tokenstring
      The token needed to migrate.
    • usage_v1number
      Quota used.
    Example:
    {
      "packmail": true,
      "included_mailboxes": 5,
      "free_mailboxes": 2,
      "forward_count": 0,
      "info": [
        {
          "login": "mb1",
          "offer_v2": "standard",
          "price_v2": 4.2,
          "price_v2_m": 0.35,
          "quota": 0,
          "usage": 2097152,
          "quota_v2": 3145728
        }
      ],
      "currency": "EUR",
      "price_v1": 12,
      "price_v2": 4.2,
      "quota_v1": 3145728,
      "usage_v1": 1887436,
      "token": "fa647dadedaeae4e6a3551e16907f36abe029ddc"
    }

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

post Launch migration

Post on this route with the appropriate token to launch the mail migration, use GET /migration/{domain} to retrieve the token.

Request

URI Parameters
    • domainstring
Query String
  • Optional
    • sharing_idstring
      Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
Body
  • application/json
    object

    With the following properties:

    Required
    • tokenstring
      The token needed to migrate.
    Example:
    {
      "token": "fa647dadedaeae4e6a3551e16907f36abe029ddc"
    }

Responses

202

The request has been accepted.
Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Offer details

https://api.gandi.net/v5/email/offers/{domain}

get Retrieve current email offer

This route returns the current status of your mailbox offer.

Request

URI Parameters
    • domainstring
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

200

Body
  • application/json
    object

    With the following properties:

    • antispamstring

      One of: "active", "inactive", "mixed"

      Antispam status on the domain. Note that a mixed value means that some mailboxes use the antispam while others don't.
    • dkimstring

      One of: "active", "inactive"

      DKIM status on the domain.
    • statusstring

      One of: "active", "inactive"

      Offer status
    • versioninteger

      One of: 1, 2

      Offer version
    Example:
    {
      "status": "active",
      "version": 2,
      "antispam": "active",
      "dkim": "active"
    }

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

patch Update global email options

This route updates some settings on a domain's level.

Request

URI Parameters
    • domainstring
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
Body
  • application/json
    object

    With the following properties:

    Required
    • antispamstring

      One of: "active", "inactive"

      Enable or disable the antispam at the domain's level.
    • dkimstring

      One of: "active", "inactive"

      Enable or disable DKIM on this domain.

Responses

202

The request has been accepted.
Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Manage slots

https://api.gandi.net/v5/email/slots/{domain}

get List existing mailbox slots

This route returns a list of all the slots attached to a specific {domain}.

Request

URI Parameters
    • domainstring
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

200

Headers
    • Total-Countinteger
      Total number of items.
Body
  • application/json
    array

    Of items of type:

    • object

      With the following properties:

      • capacityinteger
        Slot capacity (in MB).
      • created_atdatetime
        Slot creation date.
      • hrefstring
        Link to slot details
      • idinteger
        Slot ID.
      • mailbox_typestring
        Type of mailbox this slot can handle.
      • refundableboolean
        true if this slot is refundable
      • statusstring
        Slot status.
    Example:
    [
      {
        "status": "inactive",
        "capacity": 3072,
        "mailbox_type": "standard",
        "refundable": false,
        "id": 123,
        "href": "https://api.test/v5/email/slots/mailbox-api-test-1.fr/123",
        "created_at": "2019-01-15T13:20:01Z"
      },
      {
        "status": "active",
        "capacity": 3072,
        "mailbox_type": "standard",
        "refundable": false,
        "id": 124,
        "href": "https://api.test/v5/email/slots/mailbox-api-test-1.fr/124",
        "created_at": "2019-01-15T13:20:01Z"
      }
    ]

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

post Create a new mailbox slot

This route creates a new slot. You must have slots available before you can create a mailbox. If you have used the two free standard 3GB mailbox slots that are included with the domain, but require more mailboxes on that domain, you must first purchase additional slots using this route.

Request

URI Parameters
    • domainstring
Query String
  • Optional
    • sharing_idstring
      Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key
Body
  • application/json
    object

    With the following properties:

    Required
    • mailbox_typestring

      One of: "standard", "premium", "standard_new", "premium_new"

      Type of mailbox this slot can handle.
    Example:
    {
      "mailbox_type": "standard"
    }

Responses

200

Headers
    • Total-Countinteger
      Total number of items.

202

The request has been accepted.
Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Slot details

https://api.gandi.net/v5/email/slots/{domain}/{slot_id}

get Get slot details

This route returns all the parameters linked to a specific slot. For example, if a slot is in use, or refundable and by how much.

Request

URI Parameters
    • domainstring
    • slot_idinteger
      Slot ID.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

200

Body
  • application/json
    object

    With the following properties:

    • capacityinteger
      Slot capacity (in MB).
    • created_atdatetime
      Slot creation date.
    • hrefstring
      Link to slot details
    • idinteger
      Slot ID.
    • mailbox_typestring
      Type of mailbox this slot can handle.
    • refundableboolean
      true if this slot is refundable
    • statusstring
      Slot status.
    Optional
    • refund_amountnumber
      Refunded amount if you delete this slot now.
    • refund_currencystring
      Refund currency.
    Example:
    {
      "status": "inactive",
      "capacity": 51200,
      "refund_amount": 16.16,
      "mailbox_type": "premium",
      "refundable": true,
      "refund_currency": "EUR",
      "id": 125,
      "href": "http://api.test/v5/email/slots/mailbox-api-test-1.fr/125",
      "created_at": "2019-04-08T08:48:41Z"
    }

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

delete Refund a slot

This route is used to delete an availbale, unused, refundable, slot (to delete a mailbox, see DELETE {domain}/{mailbox_id}) When you delete a slot, the prepaid account that was used to purchase the slot will be refunded for the remaining time that will not be used.

Request

URI Parameters
    • domainstring
    • slot_idinteger
      Slot ID.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

202

The request has been accepted.
Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

Bad authentication attempt because of a wrong API Key.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

This authentication scheme allows you to pass your Gandi API Key and be granted access to your resources, as your permissions allow.
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key