Subaccounts

Mailgun supports the creation, modification, and deletion of subaccounts. A subaccount is a child account of a parent account. The parent account can have multiple subaccounts. The subaccounts are created and managed by the parent account.

Get a single subaccount

get/v5/accounts/subaccounts/{subaccount_id}

Fetch the details of a single subaccount

SecuritybasicAuth
Request
path Parameters
subaccount_id
required
string

The ID of the subaccount

Responses
200

A 200 response

Response Schema: application/json
object
id
string

The ID of the subaccount

name
string

The name of the subaccount

created_at
string

The date when the account was created

updated_at
string

The date when the account was last updated

status
string

The status of the subaccount

Enum Value Description
disabled

Account is disabled

open

Account is open

closed

Account is closed

object
404

A 404 response

Request samples 
Response samples 
application/json
{
  • "subaccount": {
    • "id": "123",
    • "name": "My subaccount",
    • "created_at": "Wed, 06 Nov 2024 19:48:29 GMT",
    • "updated_at": "Wed, 28 May 2025 20:03:05 GMT",
    • "status": "open"
    }
}
List all subaccounts
get/v5/accounts/subaccounts
Fetch all subaccounts


SecuritybasicAuth 
Request 
query Parameters
sort
string
Sort order


 Enum Value Description
asc
Sort by ascending order of name field


desc
Sort by descending order of name field


 
filter
string
Name of account to filter by


 
limit
integer  [ 1 .. 1000 ] 
 Default:  10
Number of subaccounts to return


 
skip
integer
 Default:  0
Number of subaccounts to skip


 
enabled
boolean
Indicate to include only enabled or disabled subaccounts


 
Responses 
200
A 200 response


Response Schema: application/json
Array of objects
 
total
integer
The total number of subaccounts


 
Request samples 
Response samples 
application/json
{
  • "subaccounts": [
    • {
      }
    ],
  • "total": 1
}
Create a subaccount
post/v5/accounts/subaccounts
Create a subaccount


SecuritybasicAuth 
Request 
query Parameters
name
required
string
The name of the subaccount


 
Responses 
200
Successfully created a subaccount


Response Schema: application/json
object
 
id
string
The ID of the subaccount


 
name
string
The name of the subaccount


 
created_at
string
The date when the account was created


 
updated_at
string
The date when the account was last updated


 
status
string
The status of the subaccount


 Enum Value Description
disabled
Account is disabled


open
Account is open


closed
Account is closed


 
object
 
400
Error response


Request samples 
Response samples 
application/json
{
  • "subaccount": {
    • "id": "123",
    • "name": "My subaccount",
    • "created_at": "Wed, 06 Nov 2024 19:48:29 GMT",
    • "updated_at": "Wed, 28 May 2025 20:03:05 GMT",
    • "status": "open"
    }
}
Delete a subaccount
delete/v5/accounts/subaccounts
Delete a subaccount


SecuritybasicAuth 
Request 
header Parameters
X-Mailgun-On-Behalf-Of
required
string
The ID of the subaccount


 
Responses 
200
A 200 response


Response Schema: application/json
message
string
Response message


 
400
Bad request


403
Forbidden


Request samples 
Response samples 
application/json
{
  • "message": "Subaccount successfully deleted"
}
Disable a subaccount
post/v5/accounts/subaccounts/{subaccount_id}/disable
Disable a subaccount


SecuritybasicAuth 
Request 
path Parameters
subaccount_id
required
string
The ID of the subaccount


 
query Parameters
reason
string
The reason for disabling the subaccount


 
note
string
A note for the subaccount


 
Responses 
200
Subaccount disabled successfully


Response Schema: application/json
object
 
id
string
The ID of the subaccount


 
name
string
The name of the subaccount


 
created_at
string
The date when the account was created


 
updated_at
string
The date when the account was last updated


 
status
string
The status of the subaccount


 Enum Value Description
disabled
Account is disabled


open
Account is open


closed
Account is closed


 
object
 
400
Subaccount is already disabled


404
Not found


Request samples 
Response samples 
application/json
{
  • "subaccount": {
    • "id": "123",
    • "name": "My subaccount",
    • "created_at": "Wed, 06 Nov 2024 19:48:29 GMT",
    • "updated_at": "Wed, 28 May 2025 20:03:05 GMT",
    • "status": "disabled"
    }
}
Enable a subaccount
post/v5/accounts/subaccounts/{subaccount_id}/enable
Enable a subaccount


SecuritybasicAuth 
Request 
path Parameters
subaccount_id
required
string
The ID of the subaccount


 
Responses 
200
Subaccount enabled successfully


Response Schema: application/json
object
 
id
string
The ID of the subaccount


 
name
string
The name of the subaccount


 
created_at
string
The date when the account was created


 
updated_at
string
The date when the account was last updated


 
status
string
The status of the subaccount


 Enum Value Description
disabled
Account is disabled


open
Account is open


closed
Account is closed


 
object
 
400
Cannot enable due to limit reached


404
Not found


Request samples 
Response samples 
application/json
{
  • "subaccount": {
    • "id": "123",
    • "name": "My subaccount",
    • "created_at": "Wed, 06 Nov 2024 19:48:29 GMT",
    • "updated_at": "Wed, 28 May 2025 20:03:05 GMT",
    • "status": "open"
    }
}
Get current custom sending limit
get/v5/accounts/subaccounts/{subaccount_id}/limit/custom/monthly
Fetch the details of custom sending limit on the account


SecuritybasicAuth 
Request 
path Parameters
subaccount_id
required
string
The ID of the subaccount


 
Responses 
200
A 200 response


Response Schema: application/json
limit
number
The custom limit set for the account


 
current
number
The number of messages already sent


 
period
string
The timeframe for which the limit applies - m for months, d for days, h for hours


 
400
Bad request


403
Forbidden


404
A 404 response


Request samples 
Response samples 
application/json
{
  • "limit": 10000,
  • "current": 0,
  • "period": "1m"
}
Set a custom sending limit
put/v5/accounts/subaccounts/{subaccount_id}/limit/custom/monthly
Set a custom sending limit


SecuritybasicAuth 
Request 
path Parameters
subaccount_id
required
string
The ID of the subaccount


 
query Parameters
limit
required
number
The limit to set


 
Responses 
200
Successfully set the sending limit


Response Schema: application/json
success
boolean
Indicates success of request


 
400
Error response


Request samples 
Response samples 
application/json
{
  • "success": true
}
Delete a custom sending limit
delete/v5/accounts/subaccounts/{subaccount_id}/limit/custom/monthly
Delete a custom sending limit


SecuritybasicAuth 
Request 
path Parameters
subaccount_id
required
string
The ID of the subaccount


 
Responses 
200
Successfully deleted the sending limit


Response Schema: application/json
success
boolean
Indicates success of request


 
400
Error response


Request samples 
Response samples 
application/json
{
  • "success": true
}
Update subaccount feature
put/v5/accounts/subaccounts/{subaccount_id}/features
Update subaccount feature


SecuritybasicAuth 
Request 
path Parameters
subaccount_id
required
string
The ID of the subaccount


 
Request Body schema: application/x-www-form-urlencoded
object
 
object
 
object
 
object
 
Responses 
200
Successfully updated subaccount features


Response Schema: application/json
object
 
property name*
additional property
any
 
400
Error response


404
Not found


Request samples 
application/x-www-form-urlencoded
Response samples 
application/json
{
  • "features": {
    • "validations": {
      }
    }
}
Cookie PolicyGDPR Email ComplianceAcceptable Use PolicyTerms of ServicePrivacy Policy
© 2024 Sinch Mailgun. All rights reserved.