Mailbox API

https://api.sandbox.gandi.net/v5/mailbox

Gandi Email Mailbox Management API (latest version)

Listing domains and get information about them

https://api.sandbox.gandi.net/v5/mailbox/domains

get Lists all your domains

This route returns a list of all the domain attached to your account.

Request

Query String
  • Optional
    • 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 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-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:

      • fqdnstring
    Example:
    [
      {
        "fqdn": "domain.com"
      }
    ]

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

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:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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
    • Authorizationstring
      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

Domain detail

https://api.sandbox.gandi.net/v5/mailbox/domains/{domain}

get Get domain detail

This method allows you to access domain details and give you some information to validate your domain with gandi. The “configuration” key lets you know which elements to put in your zone. The TXT element is quite important, as it allows our system to check the owner of the domain.

Request

URI Parameters
    • domainstring
      The domain
Headers
  • Required
    • Authorizationstring
      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:

    • antispamboolean
    • configurationarray

      Of items of type:

      • object

        With the following properties:

        • keystring
        • valuesarray[ string ]
    • date_last_validationdatetime
    • dkimboolean
    • internalboolean
    • is_livednsboolean
    • mxboolean
    • spfboolean
    • txtboolean

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

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:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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
    • Authorizationstring
      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

/v5/mailbox/domains/{domain}/validate

https://api.sandbox.gandi.net/v5/mailbox/domains/{domain}/validate

post Validate configuration

Warning: This step is mandatory to have a working mailbox (send and receive mails) After added records TXT and MX in the zone of your domain name, you can validate this records using this route and then be able to use your mailbox.

Request

URI Parameters
    • domainstring
      The domain

Responses

200

Body
  • application/json
    object

    With the following properties:

    • dkimboolean
      State of dkim records after validation
    • internalboolean
      State internal state of domain
    • mxboolean
      State of mx records after validation
    • spfboolean
      State of spf records after validation
    • txtboolean
      State of txt (ownership) after validation

Manage your forwarding addresses

https://api.sandbox.gandi.net/v5/mailbox/forwards

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.

post Create a forwarding address

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

Request

Headers
  • Required
    • Authorizationstring
      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
    • destinationsarray[ string ]
      A list of email addresses.
    • sourcestring
      The source email address.
    Example:
    {
      "source": "alice@gandi.net",
      "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

404

  • The domain of the source email has not been validated.
  • The source email is not linked to a domain.
  • There is no mailbox with the source email's domain.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

409

  • The mail forwarding has already been created.
  • The soure email is the address of a Gandi mailbox.
  • The user try to create a mail forwarding loop.
  • The one thousand limit of mail forwardings per domain has been reached.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

422

  • The user wants to create an alias.
  • The user wants to create a mail forwarding to the source email.
  • The data sent is not in accordance with the parameters requirement.

423

  • The limit number of forwards per domain and per week has been reached.
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

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:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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
    • Authorizationstring
      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

get List forwarding addresses

This route returns a paginated list of forwarded email addresses forward route.

Request

Query String
  • Optional
    • 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.
    • searchstring
      Filter the list by source or destination.
      Example: lice@mydomain
      Example: alice
      Example: domain.com
    • sharing_idstring
      Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
    • sort_bystring

      One of: "source", "-source"

      Default: "source"

      Result sorting field.
Headers
  • Required
    • Authorizationstring
      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
    • X-Total-Countinteger
      Total number of items after filtering.
Body
  • application/json
    array

    Of items of type:

    • object

      With the following properties:

      • destinationsstring
        email addresses to forward emails to.
      • sourcestring
        The source email address.

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

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:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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
    • Authorizationstring
      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.sandbox.gandi.net/v5/mailbox/forwards/{source}

put Update a forwarding address

This route replaces a forwarding address' destinations forward route.

Request

URI Parameters
    • sourcestring
Headers
  • Required
    • Authorizationstring
      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
    • destinationsarray[ string ]
      A list of email addresses.
    Example:
    {
      "destinations": [
        "alice@example.org",
        "hello.world@gandi.net"
      ]
    }

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

404

  • The domain of the source email has not been validated.
  • The source email is not linked to a domain.
  • There is no mailbox with the source email's domain.
  • No mail forward from the source email has been created.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

409

  • The user try to create a mail forwarding loop.
  • The one thousand limit of mail forwardings per domain has been reached.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

422

  • The user wants to create an alias.
  • The user wants to create a mail forwarding to the source email.
  • The data sent is not in accordance with the parameters requirement.

423

  • The limit number of forwards per domain and per week has been reached.
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

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:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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
    • Authorizationstring
      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 forward route.

Request

URI Parameters
    • sourcestring
Headers
  • Required
    • Authorizationstring
      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

The resource has been deleted.
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

404

  • The domain of the source email has not been validated.
  • The source email is not linked to a domain.
  • There is no mailbox with the source email's domain.
Body
  • application/json
    object

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

422

  • The data sent is not in accordance with the parameters requirement.

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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
    • Authorizationstring
      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.sandbox.gandi.net/v5/mailbox/mailboxes

get List mailboxes

This route returns a paginated list of mailboxes mailbox route.

Request

Query String
  • Optional
    • addressstring
      Filter by exact login
      Example: alice
    • domain_partstring
      Filter by exact fqdn
      Example: mydomain.com
    • local_partstring
      Filter by exact login
      Example: alice
    • 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.
    • searchstring
      Search by login, complete email or domain name.
      Example: lice@mydomain
      Example: alice
      Example: domain.com
    • sharing_idstring
      Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
    • sort_bystring

      One of: "id", "-id", "local_part", "-local_part", "config_name", "-config_name", "expire_at", "-expire_at", "quota", "-quota", "autorenew", "-autorenew"

      Default: "id"

      Result sorting field.
Headers
  • Required
    • Authorizationstring
      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
    • X-Total-Countinteger
      Total number of items after filtering.
Body
  • application/json
    array

    Of items of type:

    • object

      With the following properties:

      • addressstring
        Complete address of mailbox
      • antispamboolean
        Antispam is enabled
      • configobject
        Mailbox configuration

        With the following properties:

        • labelstring
          Label of configuration
        • namestring
          Technical name of configuration
        • quota_kbinteger
          Quota in Kb
        • uuidstring
          Configuration ID
      • created_atdatetime
        Creation date
      • data_accessboolean
        Information about access
      • domain_partstring
        Domain name
      • expires_atdatetime
        Expiry date
      • internal_domainboolean
        Information about internal domain
      • last_paid_durationinteger
        Duration of last subscription
      • local_partstring
        Mailbox login
      • quotainteger
        Quota allowed
      • quota_usedinteger
        Quota used
      • updated_atdatetime
        Updated date
      • uuidstring
        Mailbox ID
      Optional
      • autorenewobject
        Object with info about autorenew, can be null

        With the following properties:

        • durationinteger

          One of: 1, 12

          Duration for renew
        • duration_typestring

          One of: "m", "y"

          Month or Year for renewal duration
        • sharing_idstring
          Organization will be billed
      • issuesarray[ string ]
        Array with potentials issues
      • responderobject
        Information about responder's state

        With the following properties:

        • end_datedatetime
          Responder end date
        • messagestring
          Responder message
        • start_datedatetime
          Responder start date

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

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:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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
    • Authorizationstring
      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 new mailbox

You can create a mailbox with config config_name could be standard (10GB) or premium (50 GB).

Request

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 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
    • config_namestring
      Specify the config of the product (standard/premium).
    • emailstring
    • passwordstring

      Minimum length: 8

      Maximum length: 200

      Password of the mailbox.
    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.

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

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:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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
    • Authorizationstring
      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 detail

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

get Get mailbox detail

This method allows you to access mailbox details

Request

URI Parameters
    • emailstring
      The email address
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 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:

    • addressstring
      Complete address of mailbox
    • antispamboolean
      Antispam is enabled
    • configobject
      Mailbox configuration

      With the following properties:

      • labelstring
        Label of configuration
      • namestring
        Technical name of configuration
      • quota_kbinteger
        Quota in Kb
      • uuidstring
        Configuration ID
    • created_atdatetime
      Creation date
    • data_accessboolean
      Information about access
    • domain_partstring
      Domain name
    • expires_atdatetime
      Expiry date
    • internal_domainboolean
      Information about internal domain
    • last_paid_durationinteger
      Duration of last subscription
    • local_partstring
      Mailbox login
    • quotainteger
      Quota allowed
    • quota_usedinteger
      Quota used
    • updated_atdatetime
      Updated date
    • uuidstring
      Mailbox ID
    Optional
    • aliasesarray[ string ]
      secondary emails of a mailbox
    • autorenewobject
      Object with info about autorenew, can be null

      With the following properties:

      • durationinteger

        One of: 1, 12

        Duration for renew
      • duration_typestring

        One of: "m", "y"

        Month or Year for renewal duration
      • sharing_idstring
        Organization will be billed
    • issuesarray
      Array with potentials issues
    • responderobject
      Information about responder's state

      With the following properties:

      • end_datedatetime
        Responder end date
      • messagestring
        Responder message
      • start_datedatetime
        Responder start date

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

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:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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
    • Authorizationstring
      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 mailbox

Thanks to this method you are able to update your mailbox:

  • You can change the offer of your mailbox updating your config config_name could be standard (10GB) or premium (50 GB).
  • Update your password.
  • Activate or deactivate autorenew.
  • Add/remove aliases.
  • Enable or disable autoresponder.
  • Enable or disable antispam.

Request

URI Parameters
    • emailstring
      The email address
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 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
    • 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
    • autorenewobject

      With the following properties:

      Required
      • activatedboolean
        Specify true to enable autorenew, false to disable it.
      • durationinteger

        One of: 1, 12

        Duration for autorenew in month(s).
    • config_namestring

      One of: "standard", "premium"

      Specify the config of the product (standard/premium).
    • 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:

      Required
      • activatedboolean

        Default: false

        true if the responder is activated
      Optional
      • messagestring
        responder message

Responses

204

Mailbox was updated.

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

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:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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
    • Authorizationstring
      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 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.

Request

URI Parameters
    • emailstring
      The email address
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 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

204

Mailbox is deleted

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

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:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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
    • Authorizationstring
      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 mailbox

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

post Renew a mailbox

This method allows you to to renew a mailbox for 1 or 12 months.

Request

URI Parameters
    • emailstring
      The email address
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 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-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
    • durationinteger
      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
    • 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

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:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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
    • Authorizationstring
      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

Buy mailbox

https://api.sandbox.gandi.net/v5/mailbox/products

post Buy new mailbox

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

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 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
    • config_namestring

      One of: "standard", "premium"

      Specify the name of the product (standard/premium).
    • duration_monthinteger

      One of: 1, 12

      The duration of the subscription 1 or 12 month(s).
    • quantityinteger
      The quantity of slots to purchase.
    Optional
    • autorenewboolean

      Default: false

      true to enable the autorenewal.

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

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:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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
    • Authorizationstring
      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

Get mailboxes quotas.

https://api.sandbox.gandi.net/v5/mailbox/quotas

get Get mailboxes available and mailboxes already used.

This route exposes mailboxes per quota. Annually and monthly stand for the renewal period of subscription. The total represents mailboxes available to create mailbox and mailbox already used.

Request

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 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
    array

    Of items of type:

    • object

      With the following properties:

      • annuallyobject
        Quota for mailboxes paid in annually subscription.

        With the following properties:

        • availableinteger
          The count of mailboxes available to create mailbox.
        • totalinteger
          The total represents mailboxes available to create mailbox and mailbox already used.
        • usedinteger
          The count of mailboxes already used.
      • config_namestring
        Configuration name of the mailbox.
      • labelstring
        Label of the offer.
      • monthlyobject
        Quota for mailboxes paid in monthly subscription.

        With the following properties:

        • availableinteger
          The count of mailboxes available to create mailbox.
        • totalinteger
          The total represents mailboxes available to create mailbox and mailbox already used.
        • usedinteger
          The count of mailboxes already used.
      • quotastring
        Quota of the mailbox expressed in giga byte (GB).
    Example:
    [
      {
        "annually": {
          "available": 0,
          "total": 1,
          "used": 1
        },
        "config_name": "standard",
        "label": "Standard 10Gb",
        "monthly": {
          "available": 1,
          "total": 1,
          "used": 0
        },
        "quota": "10Gb"
      },
      {
        "annually": {
          "available": 1,
          "total": 3,
          "used": 2
        },
        "config_name": "premium",
        "label": "Premium 50Gb",
        "monthly": {
          "available": 0,
          "total": 0,
          "used": 0
        },
        "quota": "50Gb"
      }
    ]

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

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:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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
    • Authorizationstring
      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

Listing slots

https://api.sandbox.gandi.net/v5/mailbox/slots

get Lists all your slots

This route returns a list of all the slots attached to your account.

Request

Query String
  • Optional
    • config_namestring
      Filter the list by configuration name
    • expires_at_gtedatetime
      Slot expiration date.
    • expires_at_ltedatetime
      Slot expiration date.
    • last_paid_durationinteger

      One of: 1, 12

      Filters the list by last paid duration
    • 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.
    • refundablestring

      One of: "true", "false"

      Filter the list by slots that are refundable
    • sharing_idstring
      Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
    • sort_bystring

      One of: "refund_expires_at", "-refund_expires_at"

      Default: "refund_expires_at"

      Used to specify how you want the results sorted.
Headers
  • Required
    • Authorizationstring
      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-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:

      • configobject
        Information on the configuration applied to this slot

        With the following properties:

        • labelstring
          Commercial label of configuration
        • namestring
          Internal name of configuration
        • uuidstring
          Config id
      • refund_infoobject
        Information about the refundable process, may be false if there no refundable possibility

        With the following properties:

        • currencystring
          Refund currency
        • pricenumber
          Refund amout
        • refund_expires_atdatetime
          This is the date on which refund is possible
      • refundableboolean
        If this slot can be refundable
      • uuidstring
        Slot id
      Optional
      • autorenewobject
        Status of autorenew on the slot, may be false if there is no active autorenew

        With the following properties:

        • duration_monthinteger

          One of: 1, 12

          Duration in months to be used for autorenewal
        • sharing_idstring
          Sharing who paid for this autorenewal process
      • expires_atdatetime
        When the slot expires
      • last_paid_durationinteger

        One of: 1, 12

        Duration of last paid renewal
    Example:
    [
      {
        "uuid": "5156f881-cf33-11ee-aa2a-c889f3cdfda1",
        "autorenew": {
          "duration_month": 12,
          "sharing_id": "5156f881-cf33-11ee-aa2a-c000f3cdfda8"
        },
        "config": {
          "label": "Premium 50 Go",
          "name": "premium-50go",
          "uuid": "5156f876-cf33-11ee-aa4a-c889f3cdfda7"
        },
        "expires_at": "2024-03-20T14:29:41Z",
        "last_paid_duration": 1,
        "refund_info": {
          "currency": "EUR",
          "price": 61.8,
          "refund_expires_at": "2025-03-04T14:29:41Z"
        },
        "refundable": true
      }
    ]

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

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:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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
    • Authorizationstring
      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 detail

https://api.sandbox.gandi.net/v5/mailbox/slots/{slot_id}

get Get slot detail

This method allows you to access to slot details

Request

URI Parameters
    • slot_idstring
      Identifier of the slot, an uuid.
Headers
  • Required
    • Authorizationstring
      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:

    • configobject
      Information on the configuration applied to this slot

      With the following properties:

      • labelstring
        Commercial label of configuration
      • namestring
        Internal name of configuration
      • uuidstring
        Config id
    • refund_infoobject
      Information about the refundable process, may be false if there no refundable possibility

      With the following properties:

      • currencystring
        Refund currency
      • pricenumber
        Refund amout
      • refund_expires_atdatetime
        This is the date on which refund is possible
    • refundableboolean
      If this slot can be refundable
    • uuidstring
      Slot id
    Optional
    • autorenewobject
      Status of autorenew on the slot, may be false if there is no active autorenew

      With the following properties:

      • duration_monthinteger

        One of: 1, 12

        Duration in months to be used for autorenewal
      • sharing_idstring
        Sharing who paid for this autorenewal process
    • expires_atdatetime
      When the slot expires
    • last_paid_durationinteger

      One of: 1, 12

      Duration of last paid renewal

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

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:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

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
    • Authorizationstring
      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