Mailbox API (BETA version)

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

Gandi Email Mailbox Management API (BETA version)

Introduction ¶

Only for existing mailbox migrated on the new mailbox offer AND for any domains not registered with Gandi.

This section of our documentation will assist you in the management of Gandi email mailboxes through our API. This product is the new mailbox product also knows at mailbox standalone.

You have to contact us to migrate your current mailboxes to this new product. You will not be able to manage your current mailbox product with this API.

Thanks to this API you can use mailbox for domain name registered at Gandi and also domain name registered to another registrar (external domain). This is the main new feature of this product.

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 10GB of storage), or Premium (with 50GB of storage)

Warning! The mailbox API does not support the ApiKey authentication, you need to create a new token (personal access token) through the Organization Admin application.

More informations about authentication.

Listing domains and get information about them ¶

https://api.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
- 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

Responses

200

Headers

- 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:
  - fqdn ⁠string
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:
- 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

Domain detail ¶

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

get Get domain detail ¶

Domain details and configuration for DNS records.
You will get the TXT record to add to your zonerecords dns linked to your domain.
This record will validate that you are the owner of the domain.

Request

URI Parameters

- domain ⁠string
  The domain

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 ⁠boolean
configuration ⁠array
Of items of type:
- object
  With the following properties:
  - key ⁠string
  - values ⁠array[ string ]
dkim ⁠boolean
internal ⁠boolean
is_livedns ⁠boolean
mx ⁠boolean
spf ⁠boolean
txt ⁠boolean

Optional

date_last_validation ⁠datetime

Example - Domain details and configuration for DNS records.:

{
  "dkim": false,
  "mx": false,
  "spf": false,
  "txt": false,
  "internal": false,
  "antispam": false,
  "is_livedns": false,
  "configuration": [
    {
      "key": "TXT",
      "values": [
        "mailsa 10800 IN TXT \"03c77e4fabebde501d83d55cd937671a6a3760d9aa4b2e0fe47f754dc4fa213f\""
      ]
    },
    {
      "key": "DKIM",
      "values": [
        "gm1._domainkey 1200 IN CNAME gm1.gandimail.net.",
        "gm2._domainkey 1200 IN CNAME gm2.gandimail.net.",
        "gm3._domainkey 1200 IN CNAME gm3.gandimail.net."
      ]
    }
  ]
}

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

Validate configuration ¶

https://api.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. Use this route to launch a DNS record check manually. This process is made asynchronously.

Request

URI Parameters

- domain ⁠string
  The domain

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
- records_to_validate ⁠array[ string ]
  List of elements to validate
Example - Validate DNS records.:
```
{
  "records_to_validate": [
    "dkim",
    "spf",
    "txt"
  ]
}
```

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 forwarding addresses ¶

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

Warning! You must create at least one mailbox on the domain source to create forward.
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.

Warning! You must create at least one mailbox on the domain source to create forward.

Request

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@gandi.net",
  "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

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:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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.

429

The limit number of forwards per domain and per week has been reached.

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

get List forwarding addresses ¶

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

Request

Query String

Optional
- 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.
- search ⁠string
  Filter the list by source or destination.
  Example: lice@mydomain
  Example: alice
  Example: domain.com
- sharing_id ⁠string
  Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
- sort_by ⁠string
  One of: "source", "-source"
  Default: "source"
  Result sorting field.

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

- X-Total-Count ⁠integer
  Total number of items after filtering.

Body

application/json
⁠array
Of items of type:
- object
  With the following properties:
  - destinations ⁠string
    email addresses to forward emails to.
  - source ⁠string
    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:
- 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/mailbox/forwards/{source}

put Update a forwarding address ¶

This route replaces a forwarding address' destinations forward route.

Warning! You must have at least one mailbox on the domain source to update forward.

Request

URI Parameters

- 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",
    "hello.world@gandi.net"
  ]
}
```

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

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:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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.

429

The limit number of forwards per domain and per week has been reached.

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

Request

URI Parameters

- 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

200

The resource has been deleted.

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

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:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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:
- 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/mailbox/mailboxes

get List mailboxes ¶

This method allows you to list all the mailbox.
Name of the mailbox, config_name date, expiration date, update date, domain_part, local part.
State of the mailbox options : antispam, quota allowed/used, internal_domain. mailbox route.

Request

Query String

Optional
- address ⁠string
  Filter by exact login
  Example: alice
- domain_part ⁠string
  Filter by exact fqdn
  Example: mydomain.com
- local_part ⁠string
  Filter by exact login
  Example: alice
- 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.
- search ⁠string
  Search by login, complete email or domain name.
  Example: lice@mydomain
  Example: alice
  Example: domain.com
- sharing_id ⁠string
  Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
- sort_by ⁠string
  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
- 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

- X-Total-Count ⁠integer
  Total number of items after filtering.

Body

application/json
⁠array
Of items of type:
- object
  With the following properties:
  - address ⁠string
    Complete address of mailbox
  - antispam ⁠boolean
    Antispam is enabled
  - config ⁠object
    Mailbox configuration
    With the following properties:
    label ⁠string
    Label of configuration
    name ⁠string
    Technical name of configuration
    quota_kb ⁠integer
    Quota in Kb
    uuid ⁠string
    Configuration ID
  - created_at ⁠datetime
    Creation date
  - data_access ⁠boolean
    Information about access
  - domain_part ⁠string
    Domain name
  - expires_at ⁠datetime
    Expiry date
  - internal_domain ⁠boolean
    Information about internal domain
  - last_paid_duration ⁠integer
    Duration of last subscription
  - local_part ⁠string
    Mailbox login
  - owner ⁠object
    Information about owner
    With the following properties:
    id ⁠string
    UUID's owner
    name ⁠string
    Owner's name
  - quota ⁠integer
    Quota allowed
  - quota_used ⁠integer
    Quota used
  - updated_at ⁠datetime
    Updated date
  - uuid ⁠string
    Mailbox ID
  Optional
  - autorenew ⁠object
    Object with info about autorenew, can be null
    With the following properties:
    duration ⁠integer
    One of: 1, 12
    Duration for renew
    duration_type ⁠string
    One of: "m", "y"
    Month or Year for renewal duration
    sharing_id ⁠string
    Organization will be billed
  - issues ⁠array[ string ]
    Array with potentials issues
  - responder ⁠object
    Information about responder's state
    With the following properties:
    ends_at ⁠datetime
    Responder end date
    message ⁠string
    Responder message
    starts_at ⁠datetime
    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:
- 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 new mailbox ¶

You can create a mailbox with config config_name could be standard (10GB) or premium (50 GB).
You can set the config_name , email and password.
And add alias if it is not already on the DNS zone record domain.

Add records to your domain zone.
We make a DNS check to ensure the domain is correctly owned by you.
These records are mandatory to validate your mailbox product :
```
mailsa 10800 IN TXT "{value}"
```
The MX records:
```
@               10800        IN        MX        50 fb.mail.gandi.net.
@               10800        IN        MX        10 spool.mail.gandi.net.
```
The records below are strongly suggest to have functional mailbox and to send/received mails, add SPF and DKIM records to prove your mails are legitimate and diminish the possibilty for your mails to be marked as spam:
```
@               10800        IN        TXT        "v=spf1 include:_mailcust.gandi.net ?all"
gm1._domainkey  10800        IN        CNAME      gm1.gandimail.net.
gm2._domainkey  10800        IN        CNAME      gm2.gandimail.net.
gm3._domainkey  10800        IN        CNAME      gm3.gandimail.net.
```
You can retrieve this records using domain details API.
In case of domain registered at gandi and when you use livedns nameservers, when you have the correct right to write on livedns zone, this records are automatically added.
For external domain, you must change the zone of your domain from your registrar web admin or API, when it provides it.
Validate your DNS records.
Several times, we check your domain zone in order to validate your mailbox.
But you can also manually launch a check using this API. This call is asynchronous.
To check the response the validated or not validated records use domain details API:
```
{
   "dkim": true,
   "mx": true,
   "spf": true,
   "txt": true,
   "internal": false
}
```
For the records dkim, mx, spf, txt:
- false => record is not valid yet.
- true => record is valid.
For the flag internal:
- internal=true => domain registered at Gandi.
- internal=false => domain registered at another registrar.

Request

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
- config_name ⁠string
  Specify the config of the product (standard/premium).
- email ⁠string
- password ⁠string
  Minimum length: 8
  Maximum length: 200
  Password of the mailbox.
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.
- duration_month ⁠integer
  One of: 1, 12
  The duration of the subscription 1 or 12 month(s).
Example - Create a mailbox standard for mensual subscription:
```
{
  "duration_month": 1,
  "config_name": "standard",
  "email": "hello@domain.com",
  "password": "fds678fdsDdsç!è"
}
```
Example - Create a mailbox premium for annual subscription:
```
{
  "duration_month": 12,
  "config_name": "premium",
  "email": "premium@domain.com",
  "password": "4f56&dsqf4s"
}
```
Example - Create a mailbox with aliases.:
```
{
  "duration_month": 12,
  "config_name": "premium",
  "email": "hi@domain.com",
  "password": "4f56&dsqf4s",
  "aliases": [
    "contact",
    "redir"
  ]
}
```

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 detail ¶

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

get Get mailbox detail ¶

Information about the detail of the mailbox , refundable possibility with the following properties:
This method allows you to access mailbox details
You will be able to get all details of the mailbox:
Name of the mailbox, creation date, expiration date, update date, domain_part, local part,
State of the mailbox options : antispam , quota allowed/used etc.

Request

URI Parameters

- email ⁠string
  The email address

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:
- address ⁠string
  Complete address of mailbox
- antispam ⁠boolean
  Antispam is enabled
- config ⁠object
  Mailbox configuration
  With the following properties:
  - label ⁠string
    Label of configuration
  - name ⁠string
    Technical name of configuration
  - quota_kb ⁠integer
    Quota in Kb
  - uuid ⁠string
    Configuration ID
- created_at ⁠datetime
  Creation date
- data_access ⁠boolean
  Information about access
- domain_part ⁠string
  Domain name
- expires_at ⁠datetime
  Expiry date
- internal_domain ⁠boolean
  Information about internal domain
- last_paid_duration ⁠integer
  Duration of last subscription
- local_part ⁠string
  Mailbox login
- owner ⁠object
  Information about owner
  With the following properties:
  - id ⁠string
    UUID's owner
  - name ⁠string
    Owner's name
- quota ⁠integer
  Quota allowed
- quota_used ⁠integer
  Quota used
- updated_at ⁠datetime
  Updated date
- uuid ⁠string
  Mailbox ID
Optional
- aliases ⁠array[ string ]
  secondary emails of a mailbox
- autorenew ⁠object
  Object with info about autorenew, can be null
  With the following properties:
  - duration ⁠integer
    One of: 1, 12
    Duration for renew
  - duration_type ⁠string
    One of: "m", "y"
    Month or Year for renewal duration
  - sharing_id ⁠string
    Organization will be billed
- issues ⁠array
  Array with potentials issues
- responder ⁠object
  Information about responder's state
  With the following properties:
  - ends_at ⁠datetime
    Responder end date
  - message ⁠string
    Responder message
  - starts_at ⁠datetime
    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:
- 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 mailbox ¶

Update your mailbox (upgrade/downgrade, update password, aliases, enable/disable autorenew, etc.).

Request

URI Parameters

- email ⁠string
  The email address

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
  Default: true
  Enable or disable antispam.
- autorenew ⁠object
  With the following properties:
  Required
  - activated ⁠boolean
    Specify true to enable autorenew, false to disable it.
  - duration ⁠integer
    One of: 1, 12
    Duration for autorenew in month(s).
- config_name ⁠string
  One of: "standard", "premium"
  You can change the offer of your mailbox updating your config_name it can be standard (10GB) or premium (50 GB).
- password ⁠string
  Minimum length: 8
  Maximum length: 200
  Update your password : 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:
  Required
  - activated ⁠boolean
    Default: false
    ⁠default false / true is the responder is activated
  Optional
  - ends_at ⁠datetime
    responder end date
  - message ⁠string
    responder message
  - starts_at ⁠datetime
    responder start date
Example - Update mailbox password:
```
{
  "password": "xXXXxx4f56&dsqf4sXXxx"
}
```
Example - Change offer to premium:
```
{
  "config_name": "premium"
}
```
Example - Change offer to standard:
```
{
  "config_name": "standard"
}
```
Example - Enable automatic responder:
```
{
  "responder": {
    "activated": true,
    "starts_at": "2025-04-20T09:00:00Z",
    "ends_at": "2025-05-07T19:00:00Z",
    "message": "Out of office"
  }
}
```
Example - Disable automatic responder:
```
{
  "responder": {
    "activated": false
  }
}
```
Example - Update aliases:
```
{
  "aliases": [
    "hello",
    "contact"
  ]
}
```

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

- email ⁠string
  The email address

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

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:
- 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 mailbox ¶

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

post Renew a mailbox ¶

You can renew a mailbox for 1 or 12 months.

Request

URI Parameters

- email ⁠string
  The email address

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.

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

Buy mailbox and list all available products ¶

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

post Buy new mailbox ¶

This route creates new slot.
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_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
- config_name ⁠string
  One of: "standard", "premium"
  Specify the name of the product (standard/premium).
- duration_month ⁠integer
  One of: 1, 12
  The duration of the subscription 1 or 12 month(s).
- quantity ⁠integer
  The quantity of slots to purchase.
Optional
- autorenew ⁠boolean
  Default: false
  true to enable the autorenewal.
Example - buy 2 standard mailboxes with mensual subscription:
```
{
  "config_name": "standard",
  "duration_month": 1,
  "quantity": 2
}
```
Example - buy premium mailbox with annual subscription and activate autorenew:
```
{
  "config_name": "premium",
  "duration_month": 12,
  "quantity": 1,
  "autorenew": true
}
```

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

get Lists all buyable product ¶

This route returns a list of all the products buyable by your account if your are logged.

Request

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

Headers

- Total-Count ⁠integer
  Total number of items.

Body

application/json
⁠array
Of items of type:
- object
  With the following properties:
  - config ⁠array
    List config apply to this product
    Of items of type:
    object
    With the following properties:
    label ⁠string
    name ⁠string
    uuid ⁠string
    UUID
  - config_name ⁠string
  - description ⁠string
  - label ⁠string
  - prices ⁠array
    List of prices
    Of items of type:
    object
    With the following properties:
    currency ⁠string
    duration_unit ⁠string
    max_duration ⁠integer
    min_duration ⁠integer
    normal_price_after_taxes ⁠number
    normal_price_before_taxes ⁠number
    price_after_taxes ⁠number
    price_before_taxes ⁠number
  - taxes ⁠array
    List of taxes
    Of items of type:
    object
    With the following properties:
    name ⁠string
    Tax name
    name_label ⁠string
    Tax name label
    rate ⁠number
    Rate value
    type ⁠string
  - uuid ⁠string
    Product id

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

Get mailboxes quotas. ¶

https://api.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_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
⁠array
Of items of type:
- object
  With the following properties:
  - annually ⁠object
    Quota for mailboxes paid in annually subscription.
    With the following properties:
    available ⁠integer
    The count of mailboxes available to create mailbox.
    total ⁠integer
    The total represents mailboxes available to create mailbox and mailbox already used.
    used ⁠integer
    The count of mailboxes already used.
  - config_name ⁠string
    Configuration name of the mailbox.
  - label ⁠string
    Label of the offer.
  - monthly ⁠object
    Quota for mailboxes paid in monthly subscription.
    With the following properties:
    available ⁠integer
    The count of mailboxes available to create mailbox.
    total ⁠integer
    The total represents mailboxes available to create mailbox and mailbox already used.
    used ⁠integer
    The count of mailboxes already used.
  - quota ⁠string
    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:
- 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

Listing slots ¶

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

get Lists all your slots ¶

You can list all the slots attached to your account.
It means that you can know all the available slots for all the organizations you depend on You will be able to obtain, among other things, the following details of slots by using this.

Request

Query String

Optional
- config_name ⁠string
  Filter the list by configuration name
- expires_at_gte ⁠datetime
  Slot expiration date.
- expires_at_lte ⁠datetime
  Slot expiration date.
- last_paid_duration ⁠integer
  One of: 1, 12
  Filters the list by last paid duration
- 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.
- refundable ⁠string
  One of: "true", "false"
  Filter the list by slots that are refundable
- sharing_id ⁠string
  Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.
- sort_by ⁠string
  One of: "refund_expires_at", "-refund_expires_at"
  Default: "refund_expires_at"
  Used to specify how you want the results sorted.
- webhosting_pack ⁠boolean
  Filter the list by slot linked to a webhosting pack

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.
Optional
- Link ⁠string
  Links to next and last page.

Body

application/json
⁠array
Of items of type:
- object
  With the following properties:
  - config ⁠object
    Information on the configuration applied to this slot
    With the following properties:
    label ⁠string
    Commercial label of configuration
    name ⁠string
    Internal name of configuration
    uuid ⁠string
    Config id
  - refund_info ⁠object
    Information about the refundable process, may be false if there no refundable possibility
    With the following properties:
    currency ⁠string
    Refund currency
    price ⁠number
    Refund amout
    refund_expires_at ⁠datetime
    This is the date on which refund is possible
  - refundable ⁠boolean
    If this slot can be refundable
  - uuid ⁠string
    Slot id
  - webhosting_pack ⁠boolean
    If this slot is linked to a webhosting pack
  Optional
  - autorenew ⁠object
    Status of autorenew on the slot, may be false if there is no active autorenew
    With the following properties:
    duration_month ⁠integer
    One of: 1, 12
    Duration in months to be used for autorenewal
    sharing_id ⁠string
    Sharing who paid for this autorenewal process
  - expires_at ⁠datetime
    When the slot expires
  - last_paid_duration ⁠integer
    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,
    "webhosting_pack": false
  }
]
```

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 detail ¶

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

get Get slot detail ¶

This method allows you to access to slot details

Request

URI Parameters

- slot_id ⁠string
  Identifier of the slot, an 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:
- config ⁠object
  Information on the configuration applied to this slot
  With the following properties:
  - label ⁠string
    Commercial label of configuration
  - name ⁠string
    Internal name of configuration
  - uuid ⁠string
    Config id
- refund_info ⁠object
  Information about the refundable process, may be false if there no refundable possibility
  With the following properties:
  - currency ⁠string
    Refund currency
  - price ⁠number
    Refund amout
  - refund_expires_at ⁠datetime
    This is the date on which refund is possible
- refundable ⁠boolean
  If this slot can be refundable
- uuid ⁠string
  Slot id
- webhosting_pack ⁠boolean
  If this slot is linked to a webhosting pack
Optional
- autorenew ⁠object
  Status of autorenew on the slot, may be false if there is no active autorenew
  With the following properties:
  - duration_month ⁠integer
    One of: 1, 12
    Duration in months to be used for autorenewal
  - sharing_id ⁠string
    Sharing who paid for this autorenewal process
- expires_at ⁠datetime
  When the slot expires
- last_paid_duration ⁠integer
  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:
- 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 API (BETA version)

Introduction ¶

Listing domains and get information about them ¶

get Lists all your domains ¶

Request

Query String

Optional

Headers

Required

Responses

200

Headers

Optional

Body

application/json

403

Body

application/json

401

Body

application/json

403

Body

application/json

Secured by

Http Authorization Scheme

Headers

Required

Examples

Domain detail ¶

get Get domain detail ¶

Request

URI Parameters

Headers

Required

Responses

200

Body

application/json

Optional

403

Body

application/json

401

Body

application/json

403

Body

application/json

Secured by

Http Authorization Scheme

Headers

Required

Examples

Validate configuration ¶

post Validate configuration ¶

Request

URI Parameters

Headers

Required

Body

application/json

Required

Responses

202

Headers

Optional

Body

application/json

403

Body

application/json

401

Body

application/json

403

Body

application/json

Secured by

Http Authorization Scheme