Mailbox API

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

Gandi Email Mailbox Management API (latest version)

Manage your mailboxes

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

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

Delete mailbox

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

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

Buy mailbox

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

Listing slots

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

      • 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
      • 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
      • expires_atdatetime
        When the slot expires
      • last_paid_durationinteger

        One of: 1, 12

        Duration of last paid renewal
      • 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
    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