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

- domain ⁠string
  Domain name.

Query String

Optional
- destination ⁠string
  Filters the list by a destination pattern.
  Example: *@toto.net
  Example: john.doe@toto*
- page ⁠integer
  Default: 1
  Minimum: 1
  Which result page to retrieve. If the number is greater than the last page, an empty list is returned.
- per_page ⁠integer
  Minimum: 1
  How many items to display per page.
- sort_by ⁠string
  One of: "source", "-source", "destination", "-destination"
  Default: "source"
  Result sorting field.
- source ⁠string
  Filters the list by a source pattern.
  Example: *lice
  Example: alice

Headers

Required
- Authorization ⁠string
  The Authorization header must start with Apikey, followed by the user's API Key.
  Example: Apikey your-api-key
Optional
- Accept ⁠string
  When passed text/csv value, this route will return a CSV-formatted response.

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

text/csv
⁠any
CSV-formatted response.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

401

Bad authentication attempt because of a wrong API Key.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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
- Authorization ⁠string
  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

- domain ⁠string
  Domain name.

Headers

Required
- Authorization ⁠string
  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
- destinations ⁠array[ string ]
  A list of email addresses.
- source ⁠string
  The source email address.
Example:
```
{
  "source": "alice",
  "destinations": [
    "alice.doe@example.org",
    "ruth@example.org"
  ]
}
```

Responses

201

The resource has been created.

Headers

Optional
- Location ⁠string

Body

application/json
⁠object
With the following properties:
- message ⁠string
  Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

401

Bad authentication attempt because of a wrong API Key.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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
- Authorization ⁠string
  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

- domain ⁠string
  Domain name.
- source ⁠string

Headers

Required
- Authorization ⁠string
  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
- destinations ⁠array[ string ]
  A list of email addresses.
Example:
```
{
  "destinations": [
    "alice@example.org"
  ]
}
```

Responses

202

The request has been accepted.

Headers

Optional
- Location ⁠string

Body

application/json
⁠object
With the following properties:
- message ⁠string
  Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

401

Bad authentication attempt because of a wrong API Key.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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
- Authorization ⁠string
  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

- domain ⁠string
  Domain name.
- source ⁠string

Headers

Required
- Authorization ⁠string
  The Authorization header must start with Apikey, followed by the user's API Key.
  Example: Apikey your-api-key

Responses

202

The request has been accepted.

Headers

Optional
- Location ⁠string

Body

application/json
⁠object
With the following properties:
- message ⁠string
  Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

401

Bad authentication attempt because of a wrong API Key.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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
- Authorization ⁠string
  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

- domain ⁠string
  Domain name.

Query String

Optional
- <created_at ⁠datetime
  Slot creation date.
- ~login ⁠string
  Filters the list by a login pattern.
  Example: *lice
  Example: alic*
- antispam ⁠boolean
  Antispam is enabled or disabled
- login ⁠string
  Filters the list by exact login.
- mailbox_type ⁠string
  One of: "standard", "premium"
- 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 Apikey, followed by the user's API Key.
  Example: Apikey your-api-key
Optional
- Accept ⁠string
  When passed text/csv value, this route will return a CSV-formatted response.

Responses

200

A paginated list of the domain's mailboxes.

Headers

- Total-Count ⁠integer
  Total number of items.
Optional
- Link ⁠string
  Links to next and last page.

Body

application/json

⁠array

Of items of type:

object
With the following properties:
- address ⁠string
  Full email address
- alias_count ⁠integer
  Default: 0
- antispam ⁠boolean
  Antispam is enabled
- domain ⁠string
  Domain name
- href ⁠string
  Link to mailbox details
- id ⁠string
  Mailbox ID
- login ⁠string
  Mailbox login
- mailbox_type ⁠string
  One of: "standard", "premium", "free"
- quota_used ⁠integer
  Default: 0

Example:

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

text/csv
⁠any
CSV-formatted response.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

401

Bad authentication attempt because of a wrong API Key.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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
- Authorization ⁠string
  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

- domain ⁠string
  Domain name.

Headers

Required
- Authorization ⁠string
  The Authorization header must start with Apikey, followed by the user's API Key.
  Example: Apikey your-api-key
Optional
- Dry-Run ⁠integer
  If this header's value is 1 the request's parameters will only be checked; the operation will not actually be performed.

Body

application/json
⁠object
With the following properties:
Required
- login ⁠string
  Minimum length: 1
- mailbox_type ⁠string
  One of: "standard", "premium"
- password ⁠string
  Minimum length: 8
  Maximum length: 200
  Mailbox password.
  Must contain between 8 and 200 characters, containing at least 1 upper-case letter, 3 numbers, and a special character.
  You can also send a hashed password in SHA512-CRYPT ie: $6$xxxx$yyyy
Optional
- aliases ⁠array
  Of items of type:
  - string
    A local-part (what comes before the "@") of an email address. It can contain a wildcard "*" before or after at least two characters to redirect everything thats matches the local-part pattern.
- antispam ⁠boolean
  Default: true
  Enable antispam
Example:
```
{
  "login": "alice",
  "mailbox_type": "standard",
  "password": "a*6@Xk86cPR2kcZ@qPAi",
  "aliases": [
    "bob",
    "bob*"
  ]
}
```

Responses

200

Dry-Run response. You will get this response when you send your request. with a Dry-Run: 1 header.

Headers

Optional
- Warning ⁠string
  Warning message

Body

application/json
⁠object
With the following properties:
- status ⁠string
  One of: "success", "error"
  Response status.
Optional
- errors ⁠array
  A list of all the errors encountered during validation.
  Of items of type:
  - object
    With the following properties:
    description ⁠string
    Error message.
    location ⁠string
    One of: "header", "path", "querystring", "body"
    The field's location in the HTTP response.
    name ⁠string
    The xpath of the field.

202

The request has been accepted.

Headers

Optional
- Location ⁠string

Body

application/json
⁠object
With the following properties:
- message ⁠string
  Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

401

Bad authentication attempt because of a wrong API Key.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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
- Authorization ⁠string
  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

- domain ⁠string
  Domain name.
- mailbox_id ⁠string
  Mailbox ID, of type UUID

Headers

Required
- Authorization ⁠string
  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:
- address ⁠string
  Full email address
- aliases ⁠array
  Default: []
  Mailbox alias list
  Of items of type:
  - string
    A local-part (what comes before the "@") of an email address. It can contain a wildcard "*" before or after at least two characters to redirect everything thats matches the local-part pattern.
- antispam ⁠boolean
  Antispam is enabled
- domain ⁠string
  Domain name
- href ⁠string
  Link to mailbox details
- id ⁠string
  Mailbox ID
- login ⁠string
  Mailbox login
- mailbox_type ⁠string
  One of: "standard", "premium", "free"
- quota_used ⁠integer
  Default: 0
Optional
- alias_count ⁠integer
  Default: 0
- fallback_email ⁠string
  Fallback email addresse
- responder ⁠object
  With the following properties:
  Optional
  - enabled ⁠boolean
    Default: false
    true if the responder is activated
  - ends_at ⁠datetime
    responder end date
  - message ⁠string
    responder message
  - starts_at ⁠datetime
    responder start date
Example:
```
{
  "domain": "mailbox-api-test-1.fr",
  "responder": {
    "message": "",
    "enabled": false
  },
  "mailbox_type": "standard",
  "login": "alice",
  "quota_used": 0,
  "antispam": true,
  "aliases": [
    "bob",
    "bob*"
  ],
  "address": "alice@example.net",
  "href": "https://api.test/api/v5/email/example.net/066743e5-96e4-4a1d-9195-8b8a700a8a79",
  "id": "066743e5-96e4-4a1d-9195-8b8a700a8a79"
}
```

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

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
- Authorization ⁠string
  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

- domain ⁠string
  Domain name.
- mailbox_id ⁠string
  Mailbox ID, of type UUID

Headers

Required
- Authorization ⁠string
  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
- aliases ⁠array
  Of items of type:
  - string
    A local-part (what comes before the "@") of an email address. It can contain a wildcard "*" before or after at least two characters to redirect everything thats matches the local-part pattern.
- antispam ⁠boolean
  Enable or disable antispam
- login ⁠string
- password ⁠string
  Minimum length: 8
  Maximum length: 200
  Mailbox password.
  Must contain between 8 and 200 characters, containing at least 1 upper-case letter, 3 numbers, and a special character.
  You can also send a hashed password in SHA512-CRYPT ie: $6$xxxx$yyyy
- responder ⁠object
  With the following properties:
  Optional
  - enabled ⁠boolean
    Default: false
    true if the responder is activated
  - ends_at ⁠datetime
    responder end date
  - message ⁠string
    responder message
  - starts_at ⁠datetime
    responder start date
Example - Update a mailbox password:
```
{
  "password": "lGv6KLZhbCgcX8pMK9Vx6mqrZC8vk84L"
}
```
Example - Activate responder:
```
{
  "responder": {
    "enabled": true,
    "message": "Out of office",
    "starts_at": "2019-07-10T18:00:01Z",
    "ends_at": "2019-07-26T09:00:01Z"
  }
}
```
Example - Setup aliases:
```
{
  "aliases": [
    "bob",
    "bob*"
  ]
}
```

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

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
- Authorization ⁠string
  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

- domain ⁠string
  Domain name.
- mailbox_id ⁠string
  Mailbox ID, of type UUID

Headers

Required
- Authorization ⁠string
  The Authorization header must start with Apikey, followed by the user's API Key.
  Example: Apikey your-api-key

Responses

202

The request has been accepted.

Headers

Optional
- Location ⁠string

Body

application/json
⁠object
With the following properties:
- message ⁠string
  Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

401

Bad authentication attempt because of a wrong API Key.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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
- Authorization ⁠string
  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

- domain ⁠string
  Domain name.
- mailbox_id ⁠string
  Mailbox ID, of type UUID

Headers

Required
- Authorization ⁠string
  The Authorization header must start with Apikey, followed by the user's API Key.
  Example: Apikey your-api-key

Responses

202

The request has been accepted.

Headers

Optional
- Location ⁠string

Body

application/json
⁠object
With the following properties:
- message ⁠string
  Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

401

Bad authentication attempt because of a wrong API Key.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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
- Authorization ⁠string
  The Authorization header must start with Apikey, followed by the user's API Key.
  Example: Apikey your-api-key

Mailbox type management ¶

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

- domain ⁠string
  Domain name.
- mailbox_id ⁠string
  Mailbox ID, of type UUID

Query String

Optional
- sharing_id ⁠string
  Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.

Headers

Required
- Authorization ⁠string
  The Authorization header must start with Apikey, followed by the user's API Key.
  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
- mailbox_type ⁠string
  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
- 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

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
- Authorization ⁠string
  The Authorization header must start with Apikey, followed by the user's API Key.
  Example: Apikey your-api-key

Migrate from packmail to the new mailbox offer ¶

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

get Show migration details ¶

You need to use this route to get the migration token. This route returns the count of Standard (3GB) and Premium (50GB) purchased mailboxes.
Also returns the count of mailboxes included with the domain and free.

Request

URI Parameters

- domain ⁠string

Query String

Optional
- sharing_id ⁠string
  Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.

Headers

Required
- Authorization ⁠string
  The Authorization header must start with Apikey, followed by the user's API Key.
  Example: Apikey your-api-key

Responses

200

Body

application/json
⁠object
With the following properties:
- currency ⁠string
  Currency used.
- forward_count ⁠integer
  Total number of forwards.
- free_mailboxes ⁠integer
  Total number of free mailboxes.
- included_mailboxes ⁠integer
  Total number of included mailboxes (offered with the domain).
- info ⁠array
  Details of the mailbox migration.
  Of items of type:
  - object
    With the following properties:
    login ⁠string
    Email login.
    offer_v2 ⁠string
    Mailbox type, it could be standard(3Gb) or premium (50Gb).
    price_v2 ⁠number
    Yearly mailbox price.
    price_v2_m ⁠number
    Monthly mailbox price.
    quota ⁠number
    Quota of the mailbox before migration.
    quota_v2 ⁠number
    Quota of the mailbox after migration.
    usage ⁠number
    Quota used.
- packmail ⁠boolean
  Return True if the offer is still packmail.
- price_v1 ⁠number
  Total price before mailbox migration.
- price_v2 ⁠number
  Total price after mailbox migration.
- quota_v1 ⁠number
  Quota before mailbox migration.
- token ⁠string
  The token needed to migrate.
- usage_v1 ⁠number
  Quota used.
Example:
```
{
  "packmail": true,
  "included_mailboxes": 5,
  "free_mailboxes": 2,
  "forward_count": 0,
  "info": [
    {
      "login": "mb1",
      "offer_v2": "standard",
      "price_v2": 4.2,
      "price_v2_m": 0.35,
      "quota": 0,
      "usage": 2097152,
      "quota_v2": 3145728
    }
  ],
  "currency": "EUR",
  "price_v1": 12,
  "price_v2": 4.2,
  "quota_v1": 3145728,
  "usage_v1": 1887436,
  "token": "fa647dadedaeae4e6a3551e16907f36abe029ddc"
}
```

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

401

Bad authentication attempt because of a wrong API Key.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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
- Authorization ⁠string
  The Authorization header must start with Apikey, followed by the user's API Key.
  Example: Apikey your-api-key

post Launch migration ¶

Post on this route with the appropriate token to launch the mail migration, use GET /migration/{domain} to retrieve the token.

Request

URI Parameters

- domain ⁠string

Query String

Optional
- sharing_id ⁠string
  Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.

Headers

Required
- Authorization ⁠string
  The Authorization header must start with Apikey, followed by the user's API Key.
  Example: Apikey your-api-key

Body

application/json
⁠object
With the following properties:
Required
- token ⁠string
  The token needed to migrate.
Example:
```
{
  "token": "fa647dadedaeae4e6a3551e16907f36abe029ddc"
}
```

Responses

202

The request has been accepted.

Headers

Optional
- Location ⁠string

Body

application/json
⁠object
With the following properties:
- message ⁠string
  Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

401

Bad authentication attempt because of a wrong API Key.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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
- Authorization ⁠string
  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

- domain ⁠string

Headers

Required
- Authorization ⁠string
  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:
- antispam ⁠string
  One of: "active", "inactive", "mixed"
  Antispam status on the domain. Note that a mixed value means that some mailboxes use the antispam while others don't.
- dkim ⁠string
  One of: "active", "inactive"
  DKIM status on the domain.
- status ⁠string
  One of: "active", "inactive"
  Offer status
- version ⁠integer
  One of: 1, 2
  Offer version
Example:
```
{
  "status": "active",
  "version": 2,
  "antispam": "active",
  "dkim": "active"
}
```

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

401

Bad authentication attempt because of a wrong API Key.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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
- Authorization ⁠string
  The Authorization header must start with Apikey, followed by the user's API Key.
  Example: Apikey your-api-key

patch Update global email options ¶

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

Request

URI Parameters

- domain ⁠string

Headers

Required
- Authorization ⁠string
  The Authorization header must start with Apikey, followed by the user's API Key.
  Example: Apikey your-api-key

Body

application/json
⁠object
With the following properties:
Required
- antispam ⁠string
  One of: "active", "inactive"
  Enable or disable the antispam at the domain's level.
- dkim ⁠string
  One of: "active", "inactive"
  Enable or disable DKIM on this domain.

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

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
- Authorization ⁠string
  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

- domain ⁠string

Headers

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

Example:

[
  {
    "status": "inactive",
    "capacity": 3072,
    "mailbox_type": "standard",
    "refundable": false,
    "id": 123,
    "href": "https://api.test/v5/email/slots/mailbox-api-test-1.fr/123",
    "created_at": "2019-01-15T13:20:01Z"
  },
  {
    "status": "active",
    "capacity": 3072,
    "mailbox_type": "standard",
    "refundable": false,
    "id": 124,
    "href": "https://api.test/v5/email/slots/mailbox-api-test-1.fr/124",
    "created_at": "2019-01-15T13:20:01Z"
  }
]

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

401

Bad authentication attempt because of a wrong API Key.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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
- Authorization ⁠string
  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

- domain ⁠string

Query String

Optional
- sharing_id ⁠string
  Sharing ID. Organization ID used as a filter or as a billing identifier. See the reference.

Headers

Required
- Authorization ⁠string
  The Authorization header must start with Apikey, followed by the user's API Key.
  Example: Apikey your-api-key

Body

application/json
⁠object
With the following properties:
Required
- mailbox_type ⁠string
  One of: "standard", "premium"
  Type of mailbox this slot can handle.
Example:
```
{
  "mailbox_type": "standard"
}
```

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

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
- Authorization ⁠string
  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

- domain ⁠string
- slot_id ⁠integer
  Slot ID.

Headers

Required
- Authorization ⁠string
  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:
- capacity ⁠integer
  Slot capacity (in MB).
- created_at ⁠datetime
  Slot creation date.
- href ⁠string
  Link to slot details
- id ⁠integer
  Slot ID.
- mailbox_type ⁠string
  Type of mailbox this slot can handle.
- refundable ⁠boolean
  true if this slot is refundable
- status ⁠string
  Slot status.
Optional
- refund_amount ⁠number
  Refunded amount if you delete this slot now.
- refund_currency ⁠string
  Refund currency.
Example:
```
{
  "status": "inactive",
  "capacity": 51200,
  "refund_amount": 16.16,
  "mailbox_type": "premium",
  "refundable": true,
  "refund_currency": "EUR",
  "id": 125,
  "href": "http://api.test/v5/email/slots/mailbox-api-test-1.fr/125",
  "created_at": "2019-04-08T08:48:41Z"
}
```

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

401

Bad authentication attempt because of a wrong API Key.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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
- Authorization ⁠string
  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

- domain ⁠string
- slot_id ⁠integer
  Slot ID.

Headers

Required
- Authorization ⁠string
  The Authorization header must start with Apikey, followed by the user's API Key.
  Example: Apikey your-api-key

Responses

202

The request has been accepted.

Headers

Optional
- Location ⁠string

Body

application/json
⁠object
With the following properties:
- message ⁠string
  Confirmation message.

403

Access to the resource is denied. Mainly due to a lack of permissions to access it.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

401

Bad authentication attempt because of a wrong API Key.

Body

application/json
⁠object
With the following properties:
- cause ⁠string
- code ⁠integer
- message ⁠string
- object ⁠string

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
- Authorization ⁠string
  The Authorization header must start with Apikey, followed by the user's API Key.
  Example: Apikey your-api-key

Email API

Introduction ¶

Manage your forwarding addresses ¶

get List forwarding addresses ¶

Request

URI Parameters

Query String

Optional

Headers

Required

Optional

Responses

200

Headers

Optional

Body

application/json

text/csv

403

Body

application/json

401

Body

application/json

Secured by

Authentication with API Key

Headers

Required

Examples

post Create a forwarding address ¶

Request

URI Parameters

Headers

Required

Body

application/json

Required

Responses

201

Headers

Optional

Body

application/json

403

Body

application/json

401

Body

application/json

Secured by

Authentication with API Key

Headers

Required

Examples

Forwarding address details ¶

put Update a forwarding address ¶

Request

URI Parameters

Headers

Required

Body

application/json

Required

Responses

202

Headers

Optional

Body

application/json

403

Body

application/json

401

Body

application/json

Secured by

Authentication with API Key

Headers

Required

Examples