Email API (current version)

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
    • domain ⁠string
      Domain name.
Query String
  • Optional
    • destination ⁠string
      Filters the list by a destination pattern.
      Example: *@toto.net
      Example: john.doe@toto*
    • page ⁠integer

      Default: 1

      Minimum: 1

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

      Minimum: 1

      How many items to display per page.
    • sort_by ⁠string

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

      Default: "source"

      Result sorting field.
    • source ⁠string
      Filters the list by a source pattern.
      Example: *lice
      Example: alice
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key
    Optional
    • Accept ⁠string
      When passed text/csv value, this route will return a CSV-formatted response.

Responses

200

Headers
    • Filtered-Count ⁠integer
      Number of items returned by the API call.
    • Total-Count ⁠integer
      Total number of items.
    Optional
    • Link ⁠string
      Links to next and last page.
Body
  • application/json
    ⁠array

    Of items of type:

    • object

      With the following properties:

      • destinations ⁠array[ string ]
        A list of email addresses.
      • href ⁠string
        URL to forwarding address
      • source ⁠string
        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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      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
    • domain ⁠string
      Domain name.
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key
Body
  • application/json
    ⁠object

    With the following properties:

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

Responses

201

The resource has been created.
Headers
  • Optional
    • Location ⁠string
Body
  • application/json
    ⁠object

    With the following properties:

    • message ⁠string
      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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      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
    • domain ⁠string
      Domain name.
    • source ⁠string
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key
Body
  • application/json
    ⁠object

    With the following properties:

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

Responses

202

The request has been accepted.
Headers
  • Optional
    • Location ⁠string
Body
  • application/json
    ⁠object

    With the following properties:

    • message ⁠string
      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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key

delete Delete a forwarding address

This route deletes a forwarding address.

Request

URI Parameters
    • domain ⁠string
      Domain name.
    • source ⁠string
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key

Responses

202

The request has been accepted.
Headers
  • Optional
    • Location ⁠string
Body
  • application/json
    ⁠object

    With the following properties:

    • message ⁠string
      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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      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}.

The "to_convert" field lets you know whether or not you need to convert your mailbox with the renew route.

Request

URI Parameters
    • domain ⁠string
      Domain name.
Query String
  • Optional
    • <created_at ⁠datetime
      Slot creation date.
    • ~login ⁠string
      Filters the list by a login pattern.
      Example: *lice
      Example: alic*
    • antispam ⁠boolean
      Antispam is enabled or disabled
    • login ⁠string
      Filters the list by exact login.
    • mailbox_type ⁠string

      One of: "standard", "premium", "standard_2023", "premium_2023"

    • page ⁠integer

      Default: 1

      Minimum: 1

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

      Minimum: 1

      How many items to display per page.
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key
    Optional
    • Accept ⁠string
      When passed text/csv value, this route will return a CSV-formatted response.

Responses

200

A paginated list of the domain's mailboxes.
Headers
    • Filtered-Count ⁠integer
      Number of items returned by the API call.
    • Total-Count ⁠integer
      Total number of items.
    Optional
    • Link ⁠string
      Links to next and last page.
Body
  • application/json
    ⁠array

    Of items of type:

    • object

      With the following properties:

      • address ⁠string
        Full email address
      • alias_count ⁠integer

        Default: 0

      • antispam ⁠boolean
        Antispam is enabled
      • autorenew ⁠object
        State of autorenew

        With the following properties:

        • duration ⁠integer
          Duration for autorenew
        • duration_type ⁠string
          Type of duration ('m' for month)
        • enabled ⁠boolean
          Specify if autorenew is enabled on this mailbox
        Optional
        • sharing_id ⁠string
          Billed organization
      • domain ⁠string
        Domain name
      • expires_at ⁠datetime
        Expiry date
      • href ⁠string
        Link to mailbox details
      • id ⁠string
        Mailbox ID
      • login ⁠string
        Mailbox login
      • mailbox_type ⁠string

        One of: "standard", "premium", "standard_2023", "premium_2023"

      • quota_used ⁠integer

        Default: 0

      • to_convert ⁠boolean
        Need to be converted
    Example:
    [
  {
    "domain": "example.net",
    "login": "alice",
    "address": "alice@example.net",
    "id": "066743e5-96e4-4a1d-9195-8b8a700a8a79",
    "mailbox_type": "standard_2023",
    "quota_used": 1200,
    "alias_count": 2,
    "antispam": true,
    "href": "https://api.test/api/v5/email/example.net/066743e5-96e4-4a1d-9195-8b8a700a8a79",
    "expires_at": "2021-05-04T10:04:18Z",
    "to_convert": false,
    "autorenew": {
      "enabled": true,
      "duration": 1,
      "duration_type": "m"
    }
  }
]
  • 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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      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).

Note If you continue to use premium_new and standard_new, the api will respond with premium_2023 and standard_2023.

Request

URI Parameters
    • domain ⁠string
      Domain name.
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key
    Optional
    • Dry-Run ⁠integer
      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
    • login ⁠string

      Minimum length: 1

    • mailbox_type ⁠string

      One of: "standard", "premium", "standard_2023", "premium_2023", "standard_new (deprecated, replaced by standard_2023)", "premium_new (deprecated, replaced by premium_2023)"

    • password ⁠string

      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
    • aliases ⁠array

      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.
    • antispam ⁠boolean

      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
    • Warning ⁠string
      Warning message
Body
  • application/json
    ⁠object

    With the following properties:

    • status ⁠string

      One of: "success", "error"

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

      Of items of type:

      • object

        With the following properties:

        • description ⁠string
          Error message.
        • location ⁠string

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

          The field's location in the HTTP response.
        • name ⁠string
          The xpath of the field.

202

The request has been accepted.
Headers
  • Optional
    • Location ⁠string
Body
  • application/json
    ⁠object

    With the following properties:

    • message ⁠string
      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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key

Mailbox renew

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

post Renew a mailbox

This method allows you to to renew a mailbox for 1 or 12 months.
This route can also be used to convert your mailboxes from free to charged, if you don't convert them, they will be deleted on the expiration date.
Warning! This is not a free operation. Please ensure your prepaid account has enough credit.

To find out which mailboxes to convert, you can use the "to_convert" field in the list of your mailboxes.

Request

URI Parameters
    • domain ⁠string
      Domain name.
    • email ⁠string
      Email
Query String
  • Optional
    • sharing_id ⁠string
      Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key
    Optional
    • Dry-Run ⁠integer
      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
    • duration ⁠integer
      The duration (in month) of the renewal.
    Example - Renewal for 1 month:
    {
  "duration": 1
}
    Example - Renewal for 12 months:
    {
  "duration": 12
}

Responses

200

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

    With the following properties:

    • status ⁠string

      One of: "success", "error"

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

      Of items of type:

      • object

        With the following properties:

        • description ⁠string
          Error message.
        • location ⁠string

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

          The field's location in the HTTP response.
        • name ⁠string
          The xpath of the field.

202

The request has been accepted.
Headers
  • Optional
    • Location ⁠string
Body
  • application/json
    ⁠object

    With the following properties:

    • message ⁠string
      Confirmation message.

402

The organisation (sharing_id) have no money. The amount of money in the prepaid account is 0 and there is no other way to pay.
Body
  • application/json
    ⁠object

    With the following properties:

    • message ⁠string
    • status_code ⁠integer

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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      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
    • domain ⁠string
      Domain name.
    • mailbox_id ⁠string
      Mailbox ID, of type UUID
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key

Responses

200

Body
  • application/json
    ⁠object

    With the following properties:

    • address ⁠string
      Full email address
    • aliases ⁠array

      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.
    • antispam ⁠boolean
      Antispam is enabled
    • autorenew ⁠object
      State of autorenew

      With the following properties:

      • duration ⁠integer
        Duration for autorenew
      • duration_type ⁠string
        Type of duration ('m' for month)
      • enabled ⁠boolean
        Specify if autorenew is enabled on this mailbox
      Optional
      • sharing_id ⁠string
        Billed organization
    • domain ⁠string
      Domain name
    • expires_at ⁠datetime
      Expiry date
    • href ⁠string
      Link to mailbox details
    • id ⁠string
      Mailbox ID
    • login ⁠string
      Mailbox login
    • mailbox_type ⁠string

      One of: "standard", "premium", "standard_2023", "premium_2023"

    • quota_used ⁠integer

      Default: 0

    Optional
    • alias_count ⁠integer

      Default: 0

    • fallback_email ⁠string
      Fallback email addresse
    • responder ⁠object

      With the following properties:

      Optional
      • enabled ⁠boolean

        Default: false

        true if the responder is activated
      • ends_at ⁠datetime
        responder end date
      • message ⁠string
        responder message
      • starts_at ⁠datetime
        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",
  "expires_at": "2021-05-04T10:04:18Z",
  "autorenew": {
    "enabled": true,
    "duration": 1,
    "duration_type": "m"
  }
}

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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      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, activate/deactivate out-of-office replies or change offer on a given mailbox.

In the event of a change of offer, the remaining time is calculated on the basis of the new offer.

Request

URI Parameters
    • domain ⁠string
      Domain name.
    • mailbox_id ⁠string
      Mailbox ID, of type UUID
Query String
  • Optional
    • sharing_id ⁠string
      Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key
Body
  • application/json
    ⁠object

    With the following properties:

    Optional
    • aliases ⁠array

      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.
    • antispam ⁠boolean
      Enable or disable antispam
    • autorenew ⁠object

      With the following properties:

      Required
      • activated ⁠boolean
        Activate Autorenew
      • duration ⁠integer

        One of: 1, 12

        Activate autorenewfor each month or 12 months
    • login ⁠string
    • mailbox_type ⁠string

      One of: "standard_2023", "premium_2023"

      New mailbox type
    • password ⁠string

      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

    • responder ⁠object

      With the following properties:

      Optional
      • enabled ⁠boolean

        Default: false

        true if the responder is activated
      • ends_at ⁠datetime
        responder end date
      • message ⁠string
        responder message
      • starts_at ⁠datetime
        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*"
  ]
}
    Example - Changing a mailbox offer:
    {
  "mailbox_type": "premium_2023"
}
    Example - Activate autorenew:
    {
  "autorenew": {
    "activated": true,
    "duration": 1
  }
}

Responses

202

The request has been accepted.
Headers
  • Optional
    • Location ⁠string
Body
  • application/json
    ⁠object

    With the following properties:

    • message ⁠string
      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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      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
    • domain ⁠string
      Domain name.
    • mailbox_id ⁠string
      Mailbox ID, of type UUID
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key

Responses

202

The request has been accepted.
Headers
  • Optional
    • Location ⁠string
Body
  • application/json
    ⁠object

    With the following properties:

    • message ⁠string
      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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      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
    • domain ⁠string
      Domain name.
    • mailbox_id ⁠string
      Mailbox ID, of type UUID
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key

Responses

202

The request has been accepted.
Headers
  • Optional
    • Location ⁠string
Body
  • application/json
    ⁠object

    With the following properties:

    • message ⁠string
      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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key

Renew all mailboxes for a given domain

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

post Renew all mailboxes

This method allows you to to renew all mailboxes for a given domain.
This route can also be used to convert your mailboxes from free to charged, if you don't convert them, they will be deleted on the expiration date.
Warning! This is not a free operation. Please ensure your prepaid account has enough credit.

Request

URI Parameters
    • domain ⁠string
      Domain name.
Query String
  • Optional
    • sharing_id ⁠string
      Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key
    Optional
    • Dry-Run ⁠integer
      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
    ⁠any
    Example:
    {
  "sharing_id": "ac7205ab-5888-4e8a-af59-397db787d75f"
}

Responses

200

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

    With the following properties:

    • status ⁠string

      One of: "success", "error"

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

      Of items of type:

      • object

        With the following properties:

        • description ⁠string
          Error message.
        • location ⁠string

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

          The field's location in the HTTP response.
        • name ⁠string
          The xpath of the field.

202

The request has been accepted.
Headers
  • Optional
    • Location ⁠string
Body
  • application/json
    ⁠object

    With the following properties:

    • message ⁠string
      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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      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_2023 (10GB), premium (50GB) and premium_2023 (50GB) purchased mailboxes. Also returns the count of mailboxes included with the domain and free.

Request

URI Parameters
    • domain ⁠string
Query String
  • Optional
    • sharing_id ⁠string
      Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key

Responses

200

Body
  • application/json
    ⁠object

    With the following properties:

    • available ⁠boolean
      Return True if mailbox can be migrated
    • currency ⁠string
      Currency used.
    • forward_count ⁠integer
      Total number of forwards.
    • free_mailboxes ⁠integer
      Total number of free mailboxes.
    • included_mailboxes ⁠integer
      Total number of included mailboxes (offered with the domain).
    • info ⁠array
      Details of the mailbox migration.

      Of items of type:

      • object

        With the following properties:

        • login ⁠string
          Email login.
        • offer_v2 ⁠string
          Mailbox type, it could be standard (3Gb), standard_2023 (10 Gb), premium (50Gb) or premium_2023 (50Gb).
        • price_v2 ⁠number
          Yearly mailbox price.
        • price_v2_m ⁠number
          Monthly mailbox price.
        • quota ⁠number
          Quota of the mailbox before migration.
        • quota_v2 ⁠number
          Quota of the mailbox after migration.
        • usage ⁠number
          Quota used.
    • packmail ⁠boolean
      Return True if the offer is still packmail.
    • price_v1 ⁠number
      Total price before mailbox migration.
    • price_v2 ⁠number
      Total price after mailbox migration.
    • quota_v1 ⁠number
      Quota before mailbox migration.
    • token ⁠string
      The token needed to migrate.
    • usage_v1 ⁠number
      Quota used.
    Example:
    {
  "available": true,
  "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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      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
    • domain ⁠string
Query String
  • Optional
    • sharing_id ⁠string
      Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key
Body
  • application/json
    ⁠object

    With the following properties:

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

Responses

202

The request has been accepted.
Headers
  • Optional
    • Location ⁠string
Body
  • application/json
    ⁠object

    With the following properties:

    • message ⁠string
      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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      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
    • domain ⁠string
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key

Responses

200

Body
  • application/json
    ⁠object

    With the following properties:

    • antispam ⁠string

      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.
    • dkim ⁠string

      One of: "active", "inactive"

      DKIM status on the domain.
    • status ⁠string

      One of: "active", "inactive"

      Offer status
    • version ⁠integer

      One of: 1, 2, 3

      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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key

patch Update global email options

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

Request

URI Parameters
    • domain ⁠string
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key
Body
  • application/json
    ⁠object

    With the following properties:

    Required
    • antispam ⁠string

      One of: "active", "inactive"

      Enable or disable the antispam at the domain's level.
    • dkim ⁠string

      One of: "active", "inactive"

      Enable or disable DKIM on this domain.
    Example - Enable DKIM and antispam:
    {
  "antispam": "active",
  "dkim": "active"
}

Responses

202

The request has been accepted.
Headers
  • Optional
    • Location ⁠string
Body
  • application/json
    ⁠object

    With the following properties:

    • message ⁠string
      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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      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
    • domain ⁠string
Query String
  • Optional
    • display_not_expired_and_inactive ⁠boolean

      Default: false

      Only select inactive slots which have not expired.
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key

Responses

200

Headers
    • Total-Count ⁠integer
      Total number of items.
Body
  • application/json
    ⁠array

    Of items of type:

    • object

      With the following properties:

      • capacity ⁠integer
        Slot capacity (in MB).
      • created_at ⁠datetime
        Slot creation date.
      • href ⁠string
        Link to slot details
      • id ⁠integer
        Slot ID.
      • mailbox_type ⁠string
        Type of mailbox this slot can handle.
      • refundable ⁠boolean
        true if this slot is refundable
      • status ⁠string
        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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      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 slots that you purchased but require more mailboxes on that domain, you must purchase additional slots using this route before being able to create new mailboxes.

Request

URI Parameters
    • domain ⁠string
Query String
  • Optional
    • sharing_id ⁠string
      Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key
Body
  • application/json
    ⁠object

    With the following properties:

    Required
    • duration ⁠integer
      The duration (in month) of the renewal.
    • mailbox_type ⁠string

      One of: "standard", "premium", "standard_2023", "premium_2023"

      Type of mailbox this slot can handle.
    Optional
    • autorenew ⁠boolean
      Activate autorenew on slot. (False by default)
    Example:
    {
  "mailbox_type": "standard_2023",
  "duration": 12
}
    Example:
    {
  "mailbox_type": "standard_2023",
  "duration": 12,
  "autorenew": true
}

Responses

200

Headers
    • Total-Count ⁠integer
      Total number of items.

202

The request has been accepted.
Headers
  • Optional
    • Location ⁠string
Body
  • application/json
    ⁠object

    With the following properties:

    • message ⁠string
      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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      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
    • domain ⁠string
    • slot_id ⁠integer
      Slot ID.
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key

Responses

200

Body
  • application/json
    ⁠object

    With the following properties:

    • capacity ⁠integer
      Slot capacity (in MB).
    • created_at ⁠datetime
      Slot creation date.
    • href ⁠string
      Link to slot details
    • id ⁠integer
      Slot ID.
    • mailbox_type ⁠string
      Type of mailbox this slot can handle.
    • refundable ⁠boolean
      true if this slot is refundable
    • status ⁠string
      Slot status.
    Optional
    • refund_amount ⁠number
      Refunded amount if you delete this slot now.
    • refund_currency ⁠string
      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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      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
    • domain ⁠string
    • slot_id ⁠integer
      Slot ID.
Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key

Responses

202

The request has been accepted.
Headers
  • Optional
    • Location ⁠string
Body
  • application/json
    ⁠object

    With the following properties:

    • message ⁠string
      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:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

401

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

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

403

In case the bearer token has expired, does not have enought permission or does not exists.
Body
  • application/json
    ⁠object

    With the following properties:

    • cause ⁠string
    • code ⁠integer
    • message ⁠string
    • object ⁠string

Secured by

Http Authorization Scheme

This authentication scheme allows you to pass your Personal Access Token and be granted access to permissions and resources scoped by this token.

Tokens are created in the Organization Tab of the Gandi Admin application, choose the organization the token will have access too. Then go to the sharing tab, and click on "Create a token" button.

The authentication scheme Apikey allows also you to pass your Gandi API Key, but has been deprecated.

Headers
  • Required
    • Authorization ⁠string
      The Authorization header must start with Bearer for access token, or Apikey depending of the authentication scheme. Apikey is deprecated and be replaced by personal access token.
      Example: Bearer pat_abc-123
      Example: Apikey your-api-key

Last modification: Sep. 1st 2026