Email API

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

Gandi Email Mailbox Management API

Introduction

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

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

A mailbox is:

  • attached to what we refer to as a "slot". Consequently, it is necessary to have at least one slot available before you can create a new mailbox. By default, 2 slots are included for free with each domain registered at Gandi. Additional slots must therefore be purchased in the event that a greater number of mailboxes is desired.
  • linked to a specific domain name, and therefore bound to the domain's end date. Consequently, mailboxes must be billed and renewed simultaneously with their corresponding domain, an operation that is performed automatically when a domain name renewal has been requested.
  • available as one of two different types: Standard (with 3GB of storage), or Premium (with 50GB of storage)

Manage your forwarding addresses

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

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

get List forwarding addresses

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

Request

URI Parameters
    • domainstring
      Domain name.
Query String
  • Optional
    • pageinteger

      Default: 1

      Minimum: 1

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

      Minimum: 1

      How many items to display per page.
    • sort_bystring

      One of: "source", "-source"

      Default: "source"

      Result sorting field.
    • sourcestring
      Filters the list by a source pattern.
      Example: *lice
      Example: alice
Headers
  • Required
    • Authorizationstring
      The Authorization header must start with Apikey, followed by the user's API Key.
      Example: Apikey your-api-key

Responses

200

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

    Of items of type:

    • object

      With the following properties:

      • destinationsarray[ string ]
        A list of email addresses.
      • hrefstring
        URL to forwarding address
      • sourcestring
        The source email address.

403

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

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

post Create a forwarding address

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

Request

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

    With the following properties:

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

Responses

201

Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

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

Forwarding address details

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

put Update a forwarding address

This route replaces a forwarding address' destinations.

Request

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

    With the following properties:

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

Responses

202

Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

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

delete Delete a forwarding address

This route deletes a forwarding address.

Request

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

Responses

202

Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

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

Manage your mailboxes

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

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

get List mailboxes

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

Request

URI Parameters
    • domainstring
      Domain name.
Query String
  • Optional
    • ~loginstring
      Filters the list by a login pattern.
      Example: *lice
      Example: alic*
    • loginstring
      Filters the list by exact login.
    • pageinteger

      Default: 1

      Minimum: 1

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

      Minimum: 1

      How many items to display per page.
    • sort_bystring

      One of: "login", "-login"

      Default: "login"

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

Responses

200

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

    Of items of type:

    • object

      With the following properties:

      • addressstring
        Full email address
      • domainstring
        Domain name
      • hrefstring
        Link to mailbox details
      • idstring
        Mailbox ID
      • loginstring
        Mailbox login
      • mailbox_typestring

        One of: "standard", "premium", "free"

      • quota_usedinteger

        Default: 0

    Example:
    [
      {
        "domain": "example.net",
        "login": "alice",
        "address": "alice@example.net",
        "id": "066743e5-96e4-4a1d-9195-8b8a700a8a79",
        "mailbox_type": "standard",
        "quota_used": 1200,
        "href": "https://api.test/api/v5/email/example.net/066743e5-96e4-4a1d-9195-8b8a700a8a79"
      }
    ]

403

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

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

post Create a new mailbox

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

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

Request

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

    With the following properties:

    Required
    • loginstring

      Minimum length: 1

    • mailbox_typestring

      One of: "standard", "premium"

    • 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: {SHA512-CRYPT}$6$xxxx$yyyy

    Optional
    • aliasesarray

      Of items of type:

      • string
        A local-part (what comes before the "@") of an email address. It can contain a wildcard "*" before or after at least two characters to redirect everything thats matches the local-part pattern.
    Example:
    {
      "login": "alice",
      "mailbox_type": "standard",
      "password": "a*6@Xk86cPR2kcZ@qPAi",
      "aliases": [
        "bob",
        "bob*"
      ]
    }

Responses

200

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

    With the following properties:

    • statusstring

      One of: "success", "error"

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

      Of items of type:

      • object

        With the following properties:

        • descriptionstring
          Error message.
        • locationstring

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

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

202

Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

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

Mailbox details

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

get Retrieve a mailbox

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

Request

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

Responses

200

Body
  • application/json
    object

    With the following properties:

    • addressstring
      Full email address
    • aliasesarray

      Default: []

      Mailbox alias list

      Of items of type:

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

      One of: "standard", "premium", "free"

    • quota_usedinteger

      Default: 0

    Optional
    • fallback_emailstring
      Fallback email addresse
    • responderobject

      With the following properties:

      Optional
      • enabledboolean

        Default: false

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

403

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

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

patch Update a mailbox

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

Request

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

    With the following properties:

    Optional
    • aliasesarray

      Of items of type:

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

      Minimum length: 8

      Maximum length: 200

      Mailbox password.

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

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

    • responderobject

      With the following properties:

      Optional
      • enabledboolean

        Default: false

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

Responses

202

Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

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

delete Delete a mailbox

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

Request

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

Responses

202

Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

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

Mailbox content management

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

delete Purge a mailbox

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

Request

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

Responses

202

Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

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

Mailbox type manangement

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

patch Upgrade or downgrade a mailbox offer

This method allows you to update a mailbox offer. Depending on the current mailbox offer, there are different scenario:

  • From standard to premium:
    If the current slot is a free one, a new premium slot is created and used for the mailbox. Otherwise, the slot is upgraded to premium.

  • From premium to standard:
    If a free slot is available, the premium slot is destroyed (and refunded) and the free one is used for the mailbox. Otherwise, the slot is downgraded to standard.

Request

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

    With the following properties:

    Required
    • mailbox_typestring

      One of: "standard", "premium"

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

Responses

200

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

    With the following properties:

    • statusstring

      One of: "success", "error"

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

      Of items of type:

      • object

        With the following properties:

        • descriptionstring
          Error message.
        • locationstring

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

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

202

Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

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

Offer details

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

get Retrieve current email offer

This route returns the current status of your mailbox offer.

Request

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

Responses

200

Body
  • application/json
    object

    With the following properties:

    • statusstring

      One of: "active", "inactive"

      Offer status
    • versioninteger

      One of: 1, 2

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

403

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

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

Manage slots

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

get List existing mailbox slots

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

Request

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

Responses

200

Body
  • application/json
    array

    Of items of type:

    • object

      With the following properties:

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

403

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

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

post Create a new mailbox slot

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

Request

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

    With the following properties:

    Required
    • mailbox_typestring

      One of: "standard", "premium"

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

Responses

202

Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

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

Slot details

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

get Get slot details

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

Request

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

Responses

200

Body
  • application/json
    object

    With the following properties:

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

403

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

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

delete Refund a slot

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

Request

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

Responses

202

Headers
  • Optional
    • Locationstring
Body
  • application/json
    object

    With the following properties:

    • messagestring
      Confirmation message.

403

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

401

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

    With the following properties:

    • causestring
    • codeinteger
    • messagestring
    • objectstring

Secured by

Authentication with API Key

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