<img src="https://d5nxst8fruw4z.cloudfront.net/atrk.gif?account=lYCzn1QolK10N8" style="display:none" height="1" width="1" alt="">

Incoming Email Domains API

Overview

Incoming Email Domains are domains that GreenArrow Engine receives email at. Addresses at these domains are used for bounce processing, spam complaint processing, email forwarding, local mailbox delivery and SMTP AUTH.

Attributes

Incoming Email Domains

domain

hash

/

required


id

integer

/

read-only

An automatically generated identifier.

type

string

/

read-only

The type of domain represented by this record.

  • Is always incoming_email_domain for Incoming Email Domains
domain

string

/

required

The domain name of this Incoming Email Domain.

  • Must be from 1 to 200 characters in length
  • Must be a domain name: it must have dot-separated strings of only letters, numbers, and dashes. Dashes may not appear next to a dot. (For example “a-b.example.com” is valid, but “a-.example.com” and “a..example.com” are not valid.)
  • Must be unique (case-insensitive) across all Incoming Email Domains and Alias Domains
email_status

string

/

required

Determines how mail sent to this domain is handled.

  • May be: normal, disabled, or defer

Alias Domains

domain

hash

/

required


id

integer

/

read-only

An automatically generated identifier.

type

string

/

read-only

The type of domain represented by this record.

  • Is always alias_domain for Alias Domains
domain

string

/

required

The domain name of this Alias Domain.

  • Must be from 1 to 200 characters in length
  • Must be a domain name: it must have dot-separated strings of only letters, numbers, and dashes. Dashes may not appear next to a dot. (For example “a-b.example.com” is valid, but “a-.example.com” and “a..example.com” are not valid.)
  • Must be unique (case-insensitive) across all Incoming Email Domains and Alias Domains
incoming_email_domain

hash

/

read-only



Email received at the Alias Domain is delivered to the specified Incoming Email Domain.

id

integer

The id of the destination Incoming Email Domain.

domain

string

The domain of the destination Incoming Email Domain.

User Mailboxes

mailbox

hash

/

required


id

integer

/

read-only

An automatically generated identifier.

type

string

/

read-only

The type of Mailbox.

  • Is always user for User Mailboxes
localpart

string

/

required

The localpart of this user’s email address.

  • Must be unique (case-insensitive) across all types of users in its domain
  • Must contain only letters, numbers, dashes, underscores, pluses and dots
domain

hash

/

read-only



The Incoming Email Domain that this mailbox is at.

id

integer

/

read-only

An automatically generated identifier for the Incoming Email Domain record.

domain

string

/

read-only

The domain of the Incoming Email Domain for this mailbox.

is_wildcard

boolean

/

required

If this is true, then emails for both localpart@domain and localpart-*@domain.com are accepted.

delivery_mode

string

/

required

When a new email user is created, you have a few different options for how to deliver mail to that user:

  • Deliver to local mailbox (local) - Stores incoming mail on your GreenArrow Engine server in a Maildir that can be accessed via POP3. GreenArrow Engine’s POP3 server listens on port 110 by default.
  • Forward to another address (forward) - Provides the same options for incoming mail as you have when creating an email forwarder.
  • Deliver to local mailbox and forward (forward_and_local) - Combines the Deliver to local mailbox and Forward to another address options.
  • Follow dot-qmail delivery instructions (dotqmail) - Allows you to include the contents of a .qmail file, and have its logic processed for all incoming messages to this account.

  • May be: local, forward, forward_and_local, or dotqmail
dotqmail

string

/

default: null

The dot-qmail delivery instructions for messages received for this mailbox.

See the dot-qmail manual page for information on the format of these instructions.

  • If delivery_mode is dotqmail then this is a non-blank string
  • Otherwise, this is null
forward_to

array of strings

/

default: null

The email address(es) to forward mail to.

  • If delivery_mode is forward then this contains valid-looking email address(es)
  • Otherwise, this is null
password

string

/

required

The SMTP and POP3 password for this user.

  • Must be non-blank
locked

boolean

/

default: false

When this is true, this user cannot authenticate using POP3 or SMTP. Email will still be delivered to the user’s mailbox.

Forwarding Mailboxes

mailbox

hash

/

required


id

integer

/

read-only

An automatically generated identifier.

type

string

/

read-only

The type of Mailbox.

  • Is always forward for Forwarding Mailboxes
localpart

string

/

required

The localpart of this user’s email address.

  • Must be unique (case-insensitive) across all types of users in its domain
  • Must contain only letters, numbers, dashes, underscores, pluses and dots
domain

hash

/

read-only



The Incoming Email Domain that this forwarder is at.

id

integer

/

read-only

An automatically generated identifier for the Incoming Email Domain record.

domain

string

/

read-only

The domain for this forwarder.

is_wildcard

boolean

/

required

If this is true, then emails for both localpart@domain and localpart-*@domain.com are accepted.

forward_to

array of strings

/

default: null

The email address(es) to forward mail to.

  • Must contain valid-looking email address(es).

Bounce Mailboxes

mailbox

hash

/

required


id

integer

/

read-only

An automatically generated identifier.

type

string

/

read-only

The type of Mailbox.

  • Is always bounce_mailbox for Bounce Mailboxes
localpart

string

/

required

The localpart of this user’s email address.

We recommend that you keep the localpart of the bounce address to a maximum of 8 characters. Localparts longer than this may result in the Return-Path email address being longer than 64 characters and rejected by some mail servers.

  • Must be unique (case-insensitive) across all types of users in its domain
  • Must contain only letters, numbers, dashes, underscores, pluses and dots
domain

hash

/

read-only



The Incoming Email Domain that this mailbox is at.

id

integer

/

read-only

An automatically generated identifier for the Incoming Email Domain record.

domain

string

/

read-only

The domain of the Incoming Email Domain for this mailbox.

Spam Complaint Mailboxes

mailbox

hash

/

required


id

integer

/

read-only

An automatically generated identifier.

type

string

/

read-only

The type of Mailbox.

  • Is always scomp_mailbox for Spam Complaint Mailboxes
localpart

string

/

required

The localpart of this user’s email address.

  • Must be unique (case-insensitive) across all types of users in its domain
  • Must contain only letters, numbers, dashes, underscores, pluses and dots
domain

hash

/

read-only



The Incoming Email Domain that this mailbox is at.

id

integer

/

read-only

An automatically generated identifier for the Incoming Email Domain record.

domain

string

/

read-only

The domain of the Incoming Email Domain for this mailbox.

Domains

Get a List of Domains

GET /ga/api/v3/eng/incoming_email_domains
GET /ga/api/v3/eng/incoming_email_domains/{id}/alias_domains
GET /ga/api/v3/eng/alias_domains

Parameters

The following parameters are valid for any of the above endpoints:

page

integer

/

optional

The page number to retrieve. Page numbering starts at 0.

page_token

string

/

optional

The page_token can be used to retrieve the next page of results.

domain

string

/

optional

Filter the results to just a single domain name (case-insensitive).

Examples:

GET /ga/api/v3/eng/incoming_email_domains?page={page}
GET /ga/api/v3/eng/incoming_email_domains/{id}/alias_domains?page_token={page_token}
GET /ga/api/v3/eng/alias_domains?domain={domain}

Response

The response will contain a list of Domains in the following format.

domains

array of hashes


id

integer

An automatically generated identifier.

type

string

The type of domain represented by this record.

  • May be: incoming_email_domain or alias_domain
domain

string

The domain name of this Domain.

pagination

hash


page

integer

The page number of this result set. Page numbers start at 0.

per_page

integer

The number of records returned on each page.

num_pages

integer

The total number of pages in the result set.

num_records

integer

The total number of records that are in the result set.

next_page_token

string

A unique identifier that can be used to retrieve the next result set.

null is returned if this is the last page.

Example 1: Get a List of Incoming Email Domains

GET /ga/api/v3/eng/incoming_email_domains

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "domains": [
      {
        "id": 1,
        "type": "incoming_email_domain",
        "domain": "example-domain.com"
      },
      {
        "id": 2,
        "type": "incoming_email_domain",
        "domain": "second-domain.com"
      },
      {
        "id": 3,
        "type": "incoming_email_domain",
        "domain": "example-last-domain.com"
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 3,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 2: Get a List of Alias Domains for a Single Incoming Email Domain

GET /ga/api/v3/eng/incoming_email_domains/1/alias_domains

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "domains": [
      {
        "id": 4,
        "type": "alias_domain",
        "domain": "alias-1.com"
      },
      {
        "id": 5,
        "type": "alias_domain",
        "domain": "second-alias.com"
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 2,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 3: Get a List of Alias Domains

GET /ga/api/v3/eng/alias_domains

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "domains": [
      {
        "id": 4,
        "type": "alias_domain",
        "domain": "alias-1.com"
      },
      {
        "id": 5,
        "type": "alias_domain",
        "domain": "second-alias.com"
      },
      {
        "id": 6,
        "type": "alias_domain",
        "domain": "last-alias-domain.com"
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 3,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Get Details on a Domain

GET /ga/api/v3/eng/incoming_email_domains/{id}
GET /ga/api/v3/eng/alias_domains/{id}

Response

domain

hash

The attributes for this hash are defined in the Attributes section of this document.

Example 1: Get an Incoming Email Domain

GET /ga/api/v3/eng/incoming_email_domains/1

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "domain": {
      "id": 1,
      "type": "incoming_email_domain",
      "domain": "example-domain.com",
      "email_status": "normal"
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 2: Get an Alias Domain

GET /ga/api/v3/eng/alias_domains/4

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "domain": {
      "id": 4,
      "type": "alias_domain",
      "domain": "alias-1.com",
      "incoming_email_domain": {
        "id": 1,
        "domain": "example-domain.com"
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Create a Domain

POST /ga/api/v3/eng/incoming_email_domains
POST /ga/api/v3/eng/incoming_email_domains/{id}/alias_domains

Payload

domain

hash

/

required

An object as described in the Attributes section of this page.

All required fields must be present. Do not specify read-only fields.

Response

The response is the full Domain record as defined in the Attributes.

Example 1: Create an Incoming Email Domain

POST /ga/api/v3/eng/incoming_email_domains

{
  "domain": {
    "domain": "new-domain-1.com",
    "email_status": "disabled"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "domain": {
      "id": 7,
      "type": "incoming_email_domain",
      "domain": "new-domain-1.com",
      "email_status": "disabled"
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 2: Create an Alias Domain

POST /ga/api/v3/eng/incoming_email_domains/3/alias_domains

{
  "domain": {
    "domain": "new-alias-1.com"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "domain": {
      "id": 7,
      "type": "alias_domain",
      "domain": "new-alias-1.com",
      "incoming_email_domain": {
        "id": 3,
        "domain": "example-last-domain.com"
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Update a Domain

PUT /ga/api/v3/eng/incoming_email_domains/{id}
PUT /ga/api/v3/eng/alias_domains/{id}

Payload

domain

hash

/

required

This hash is described in the Attributes section of this page.

Response

The response is the full Domain record as defined Attributes section of this document.

Example 1: Update an Incoming Email Domain

PUT /ga/api/v3/eng/incoming_email_domains/2

{
  "domain": {
    "domain": "updated-domain-name.com",
    "email_status": "defer"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "domain": {
      "id": 2,
      "type": "incoming_email_domain",
      "domain": "updated-domain-name.com",
      "email_status": "defer"
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 2: Update an Alias Domain

PUT /ga/api/v3/eng/alias_domains/6

{
  "domain": {
    "domain": "updated-alias-name.com"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "domain": {
      "id": 6,
      "type": "alias_domain",
      "domain": "updated-alias-name.com",
      "incoming_email_domain": {
        "id": 2,
        "domain": "second-domain.com"
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Delete an Incoming Email Domain

DELETE /ga/api/v3/eng/incoming_email_domains/{id}
DELETE /ga/api/v3/eng/alias_domains/{id}

Response

The response is a standard success or error response.

Example

DELETE /ga/api/v3/eng/incoming_email_domains/3

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
  },
  "error_code": null,
  "error_messages": null
}

Mailboxes

Get a List of Mailboxes

GET /ga/api/v3/eng/incoming_email_domains/{domain_id}/mailboxes
GET /ga/api/v3/eng/incoming_email_domains/{domain_id}/mailboxes?page={page}
GET /ga/api/v3/eng/incoming_email_domains/{domain_id}/user_mailboxes
GET /ga/api/v3/eng/incoming_email_domains/{domain_id}/user_mailboxes?page_token={page_token}
GET /ga/api/v3/eng/incoming_email_domains/{domain_id}/forwarding_mailboxes
GET /ga/api/v3/eng/incoming_email_domains/{domain_id}/spam_complaint_mailboxes
GET /ga/api/v3/eng/incoming_email_domains/{domain_id}/bounce_mailboxes

Parameters

page

integer

/

optional

The page number to retrieve. Page numbering starts at 0.

page_token

string

/

optional

The page_token can be used to retrieve the next page of results.

Response

The response will contain a list of Users in the following format.

mailboxes

array of hashes


id

integer

An automatically generated identifier.

type

string

The type of Mailbox.

  • May be: user, forward, bounce_mailbox, or scomp_mailbox
localpart

string

The localpart of this mailbox’s email address.

is_wildcard

boolean

If this is true, then emails for both localpart@domain and localpart-*@domain.com are accepted.

pagination

hash


page

integer

The page number of this result set. Page numbers start at 0.

per_page

integer

The number of records returned on each page.

num_pages

integer

The total number of pages in the result set.

num_records

integer

The total number of records that are in the result set.

next_page_token

string

A unique identifier that can be used to retrieve the next result set.

null is returned if this is the last page.

Example 1: List all Mailboxes on the Domain

GET /ga/api/v3/eng/incoming_email_domains/1/mailboxes

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailboxes": [
      {
        "id": 7,
        "type": "user",
        "localpart": "test_user1",
        "is_wildcard": false
      },
      {
        "id": 8,
        "type": "user",
        "localpart": "test_user2",
        "is_wildcard": false
      },
      {
        "id": 10,
        "type": "forward",
        "localpart": "test_forward1",
        "is_wildcard": false
      },
      {
        "id": 11,
        "type": "forward",
        "localpart": "test_forward2",
        "is_wildcard": true
      },
      {
        "id": 13,
        "type": "scomp_mailbox",
        "localpart": "test_scomp1",
        "is_wildcard": false
      },
      {
        "id": 14,
        "type": "scomp_mailbox",
        "localpart": "test_scomp2",
        "is_wildcard": false
      },
      {
        "id": 16,
        "type": "bounce_mailbox",
        "localpart": "test_bounce1",
        "is_wildcard": false
      },
      {
        "id": 17,
        "type": "bounce_mailbox",
        "localpart": "test_bounce2",
        "is_wildcard": false
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 8,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 2: List only User Mailboxes on the Domain

GET /ga/api/v3/eng/incoming_email_domains/1/user_mailboxes

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailboxes": [
      {
        "id": 7,
        "type": "user",
        "localpart": "test_user1",
        "is_wildcard": false
      },
      {
        "id": 8,
        "type": "user",
        "localpart": "test_user2",
        "is_wildcard": false
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 2,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 3: List Only Forwarding Mailboxes on the Domain

GET /ga/api/v3/eng/incoming_email_domains/1/forwarding_mailboxes

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailboxes": [
      {
        "id": 10,
        "type": "forward",
        "localpart": "test_forward1",
        "is_wildcard": false
      },
      {
        "id": 11,
        "type": "forward",
        "localpart": "test_forward2",
        "is_wildcard": true
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 2,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 4: List Only Bounce Mailboxes on the Domain

GET /ga/api/v3/eng/incoming_email_domains/1/bounce_mailboxes

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailboxes": [
      {
        "id": 16,
        "type": "bounce_mailbox",
        "localpart": "test_bounce1",
        "is_wildcard": false
      },
      {
        "id": 17,
        "type": "bounce_mailbox",
        "localpart": "test_bounce2",
        "is_wildcard": false
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 2,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 5: List Only Spam Complaint Mailboxes on the Domain

GET /ga/api/v3/eng/incoming_email_domains/1/spam_complaint_mailboxes

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailboxes": [
      {
        "id": 13,
        "type": "scomp_mailbox",
        "localpart": "test_scomp1",
        "is_wildcard": false
      },
      {
        "id": 14,
        "type": "scomp_mailbox",
        "localpart": "test_scomp2",
        "is_wildcard": false
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 2,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Get Details on a Mailbox

GET /ga/api/v3/eng/mailboxes/{id}

Response

The response will contain details on the requested record.

mailbox

hash

The attributes for this hash are defined in the Attributes section of this document.

Example 1: Get a User Mailbox

GET /ga/api/v3/eng/mailboxes/7

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailbox": {
      "id": 7,
      "type": "user",
      "localpart": "test_user1",
      "domain": {
        "id": 1,
        "domain": "example-domain.com"
      },
      "is_wildcard": false,
      "delivery_mode": "local",
      "dotqmail": null,
      "forward_to": null,
      "password": "secret-password",
      "locked": false
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 2: Get a Forwarding Mailbox

GET /ga/api/v3/eng/mailboxes/10

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailbox": {
      "id": 10,
      "type": "forward",
      "localpart": "test_forward1",
      "domain": {
        "id": 1,
        "domain": "example-domain.com"
      },
      "is_wildcard": false,
      "forward_to": [
        "destination@example.com"
      ]
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 3: Get a Spam Complaint Mailbox

GET /ga/api/v3/eng/mailboxes/13

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailbox": {
      "id": 13,
      "type": "scomp_mailbox",
      "localpart": "test_scomp1",
      "domain": {
        "id": 1,
        "domain": "example-domain.com"
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 4: Get a Bounce Mailbox

GET /ga/api/v3/eng/mailboxes/16

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailbox": {
      "id": 16,
      "type": "bounce_mailbox",
      "localpart": "test_bounce1",
      "domain": {
        "id": 1,
        "domain": "example-domain.com"
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Create a Mailbox

POST /ga/api/v3/eng/incoming_email_domains/{domain_id}/user_mailboxes
POST /ga/api/v3/eng/incoming_email_domains/{domain_id}/forwarding_mailboxes
POST /ga/api/v3/eng/incoming_email_domains/{domain_id}/spam_complaint_mailboxes
POST /ga/api/v3/eng/incoming_email_domains/{domain_id}/bounce_mailboxes

Payload

mailbox

hash

/

required

An object as described in the Attributes section of this page. Use the definition for the kind of user you want to create.

All required fields must be present. Do not specify read-only fields.

Example 1: Create a User Mailbox

POST /ga/api/v3/eng/incoming_email_domains/2/user_mailboxes

{
  "mailbox": {
    "localpart": "new-user",
    "is_wildcard": true,
    "password": "new-secret-password",
    "delivery_mode": "forward_and_local",
    "forward_to": [
      "new-destination@example.com",
      "second@example.com"
    ]
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailbox": {
      "id": 19,
      "type": "user",
      "localpart": "new-user",
      "domain": {
        "id": 2,
        "domain": "second-domain.com"
      },
      "is_wildcard": true,
      "delivery_mode": "forward_and_local",
      "dotqmail": null,
      "forward_to": [
        "new-destination@example.com",
        "second@example.com"
      ],
      "password": "new-secret-password",
      "locked": false
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 2: Create a Forwarding Mailbox

POST /ga/api/v3/eng/incoming_email_domains/2/forwarding_mailboxes

{
  "mailbox": {
    "localpart": "new-forward",
    "forward_to": [
      "new-forwarding-destination@example.com"
    ],
    "is_wildcard": true
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailbox": {
      "id": 19,
      "type": "forward",
      "localpart": "new-forward",
      "domain": {
        "id": 2,
        "domain": "second-domain.com"
      },
      "is_wildcard": true,
      "forward_to": [
        "new-forwarding-destination@example.com"
      ]
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 3: Create a Spam Complaint Mailbox

POST /ga/api/v3/eng/incoming_email_domains/2/spam_complaint_mailboxes

{
  "mailbox": {
    "localpart": "new-scomp"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailbox": {
      "id": 19,
      "type": "scomp_mailbox",
      "localpart": "new-scomp",
      "domain": {
        "id": 2,
        "domain": "second-domain.com"
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 4: Create a Bounce Mailbox

POST /ga/api/v3/eng/incoming_email_domains/2/bounce_mailboxes

{
  "mailbox": {
    "localpart": "new-bounce"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailbox": {
      "id": 19,
      "type": "bounce_mailbox",
      "localpart": "new-bounce",
      "domain": {
        "id": 2,
        "domain": "second-domain.com"
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Update a Mailbox

PUT /ga/api/v3/eng/mailboxes/{id}

Payload

mailbox

hash

/

required

An object as described in the Attributes section of this page. Use the definition for the kind of user you are updating.

Example 1: Update a User Mailbox

PUT /ga/api/v3/eng/mailboxes/7

{
  "mailbox": {
    "localpart": "test_user1_updated",
    "is_wildcard": true,
    "delivery_mode": "forward_and_local",
    "forward_to": [
      "updated-destination@example.com"
    ],
    "password": "secret-password-updated",
    "locked": true
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailbox": {
      "id": 7,
      "type": "user",
      "localpart": "test_user1_updated",
      "domain": {
        "id": 1,
        "domain": "example-domain.com"
      },
      "is_wildcard": true,
      "delivery_mode": "forward_and_local",
      "dotqmail": null,
      "forward_to": [
        "updated-destination@example.com"
      ],
      "password": "secret-password-updated",
      "locked": true
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 2: Update a Forwarding Mailbox

PUT /ga/api/v3/eng/mailboxes/10

{
  "mailbox": {
    "forward_to": [
      "updated-forwarding-destination@example.com"
    ],
    "is_wildcard": true
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailbox": {
      "id": 10,
      "type": "forward",
      "localpart": "test_forward1",
      "domain": {
        "id": 1,
        "domain": "example-domain.com"
      },
      "is_wildcard": true,
      "forward_to": [
        "updated-forwarding-destination@example.com"
      ]
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 3: Update a Spam Complaint Mailbox

PUT /ga/api/v3/eng/mailboxes/13

{
  "mailbox": {
    "localpart": "new-localpart"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailbox": {
      "id": 13,
      "type": "scomp_mailbox",
      "localpart": "new-localpart",
      "domain": {
        "id": 1,
        "domain": "example-domain.com"
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Example 4: Update a Bounce Mailbox

PUT /ga/api/v3/eng/mailboxes/16

{
  "mailbox": {
    "localpart": "new-bounce-localpart"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "mailbox": {
      "id": 16,
      "type": "bounce_mailbox",
      "localpart": "new-bounce-localpart",
      "domain": {
        "id": 1,
        "domain": "example-domain.com"
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Delete a Mailbox

DELETE /ga/api/v3/eng/mailboxes/{id}

References made to Bounce Mailboxes from GreenArrow Studio will not prevent deletion of the Bounce Mailbox, but may in the future. Deleting a Bounce Mailbox that is used by a scheduled/in-progress GreenArrow Studio campaign will cause the campaign to either not send or send with the deleted address.

Response

The response is a standard success or error response.

Example

DELETE /ga/api/v3/eng/mailboxes/7

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
  },
  "error_code": null,
  "error_messages": null
}