--- updatedAt: 2026-08-27T03:04:17.000Z agentTools: projectIndex: https://docs.aurorasendcloud.com/llms.txt --- # Add API_USER Create an API_USER (POST only; official description 'Same as GET method' refers to parameter passing, the OpenAPI method is POST). Tips: 1. To enable click-tracking, you need to make sure the bound domain has passed "cname" configuration validation. 2. When trackDomainName is the system default tracking domain name (track2.sendcloud.net), reading tracking and click tracking cannot be enabled — the server forces open=0 and click=0 (APIUserController:283-290). This also applies when trackDomainName is omitted. 3. Unsubscribe tracking is forcibly enabled (1) for free accounts regardless of the unsubscribe parameter (APIUserController:225-227). 4. An account may hold at most 10 NORMAL API_USERs (Constant.MAX_CATEGORY_COUNT); exceeding returns 41112 unless the account is whitelisted. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Email", "version": "1.0.0", "description": "Revised snapshot of official v1.4 API_USER OpenAPI, synced to asc-api source behavior (APIUserController / APIUserEntityChecker / CategoryServiceImpl). Revision notes: A1 update newName required=false (source checkNewName canNull=true; omitting it keeps the current name). A2 response cType/emailType are strings ('test'/'Non-test', 'trigger'/'batch' — Category.getCategoryTypeDes/getEmailTypeDes), not integers; official update response typed them as integer enums. A3 success message casing 'Request successful' (StatusCode.GLOBAL_SUCCESS). A4 400 error-code tables added for all 3 operations (none documented before; no method restriction is declared — the framework accepts any HTTP method on these paths; HTTP status stays 200, failure is carried by statusCode + result=false). A5 domainName/trackDomainName double length constraint: 4-255 overall AND each label 1-48 chars (RegExpValidator.DOMAIN_REGEX; exposed by 165 No.8104). A6 name/newName pattern ^[A-Za-z0-9_][A-Za-z0-9_@.-]{5,63}$. A7 conditional semantics: free-account unsubscribe forced to 1, default track domain forces open=0/click=0, add count limit 10 (41112), bound domain must exist under the caller (41108), non-default trackDomainName must exist with CNAME passed/todo (41018/41019). A8 update semantics: name must be an existing NORMAL API_USER owned by the caller (41121), newName unique (41130), rebinding domain must be non-test (41123) and verified (41124). A9 list filters are exact-match SQL equals with status=1 only, no pagination." }, "servers": [ { "url": "https://api.aurorasendcloud.com/", "description": "Singapore Region\n- Base URL: https://api.aurorasendcloud.com/\n" }, { "url": "https://api-us.aurorasendcloud.com/", "description": "US (Silicon Valley) Region\n- Base URL: https://api-us.aurorasendcloud.com/\n" }, { "url": "https://api-hk.aurorasendcloud.com/", "description": "CN (Hong Kong) Region\n- Base URL: https://api-hk.aurorasendcloud.com/\n" } ], "tags": [ { "name": "API_USER", "description": "API_USER management operations" } ], "paths": { "/api/apiuser/add": { "post": { "summary": "Add API_USER", "description": "Create an API_USER (POST only; official description 'Same as GET method' refers to parameter passing, the OpenAPI method is POST).\nTips:\n 1. To enable click-tracking, you need to make sure the bound domain has passed \"cname\" configuration validation.\n 2. When trackDomainName is the system default tracking domain name (track2.sendcloud.net), reading tracking and click tracking cannot be enabled — the server forces open=0 and click=0 (APIUserController:283-290). This also applies when trackDomainName is omitted.\n 3. Unsubscribe tracking is forcibly enabled (1) for free accounts regardless of the unsubscribe parameter (APIUserController:225-227).\n 4. An account may hold at most 10 NORMAL API_USERs (Constant.MAX_CATEGORY_COUNT); exceeding returns 41112 unless the account is whitelisted.", "operationId": "add-api-user", "tags": [ "API_USER" ], "security": [ { "apiUser": [], "apiKey": [] } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_][A-Za-z0-9_@.-]{5,63}$", "maxLength": 64, "minLength": 6, "description": "API_USER name: 6-64 chars, must start with a letter/digit/underscore; may contain A-Z a-z 0-9 _ @ . - (Category.CATEGORY_PATTERN). Must be unique; duplicates fail creation with 41119 + 'API_USER already exists'.", "example": "test_apiuser" }, "emailType": { "type": "integer", "enum": [ 0, 1 ], "description": "Email type: 0 (Trigger), 1 (Batch). Non-integer or out-of-enum values return 41102.", "example": 1 }, "domainName": { "type": "string", "minLength": 4, "maxLength": 255, "pattern": "^([a-z0-9A-Z][a-z0-9A-Z\\-]{0,46}[a-z0-9A-Z]{0,1}\\.)+([a-z0-9A-Z]+)$", "description": "API_USER bound domain name: total length 4-255 AND each label 1-48 chars. Must be an existing domain owned by the caller (41108); test domains and unverified domains are rejected inside creation (41119 with service message).", "example": "delong.com" }, "trackDomainName": { "type": "string", "minLength": 4, "maxLength": 255, "pattern": "^([a-z0-9A-Z][a-z0-9A-Z\\-]{0,46}[a-z0-9A-Z]{0,1}\\.)+([a-z0-9A-Z]+)$", "description": "API_USER bound tracking domain. When omitted or equal to the default (track2.sendcloud.net): defaults to the system tracking domain and forces open=0, click=0. Otherwise must be an existing tracking domain of the caller with CNAME status passed or todo (41018/41019).", "example": "track2.sendcloud.net" }, "unsubscribePageId": { "type": "integer", "minimum": 1, "maximum": 2147483646, "description": "Unsubscribe page ID: integer in [1, 2147483646] (0, negative, >= 2147483647 or non-integer return 41113). Must reference an existing unsubscribe page owned by the caller, otherwise 41112.", "example": 166 }, "open": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "Whether to enable open-tracking: 0 (disable), 1 (enable); disable by default. Non-{0,1} integer or non-integer returns 41114. Forced to 0 when the tracking domain is the default one.", "example": 1 }, "click": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "Whether to enable click-tracking: 0 (disable), 1 (enable); disable by default. Non-{0,1} integer or non-integer returns 41116. Forced to 0 when the tracking domain is the default one.", "example": 0 }, "unsubscribe": { "type": "integer", "enum": [ 0, 1 ], "default": 1, "description": "Whether to enable unsubscribe-tracking: 0 (disable), 1 (enable); enabled by default. Non-{0,1} integer or non-integer returns 41118. Forced to 1 for free accounts (server-side, reflected in the response).", "example": 1 } }, "required": [ "name", "emailType", "domainName" ] } } } }, "responses": { "200": { "description": "Request successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Request successful" }, "result": { "type": "boolean", "example": true }, "info": { "type": "object", "properties": { "data": { "type": "object", "description": "Created API_USER snapshot. nameKey is the plaintext API key generated for this API_USER — returned only once, on creation.", "properties": { "name": { "type": "string", "description": "API_USER name" }, "nameKey": { "type": "string", "description": "Plaintext API_KEY of the created API_USER (only returned by add; store it, it cannot be retrieved again)", "example": "********" }, "cType": { "type": "string", "enum": [ "test", "Non-test" ], "description": "API_USER type descriptor string (source returns Category.getCategoryTypeDes())", "example": "Non-test" }, "emailType": { "type": "string", "enum": [ "trigger", "batch" ], "description": "Email type descriptor string (source returns Category.getEmailTypeDes())", "example": "trigger" }, "domainName": { "type": "string", "description": "API_USER bound domain" }, "trackDomainName": { "type": "string", "description": "The tracking domain name bound to API_USER", "example": "track2.sendcloud.net" }, "click": { "type": "integer", "enum": [ 0, 1 ], "description": "Whether click-tracking is enabled (post server-side forcing)", "example": 1 }, "open": { "type": "integer", "enum": [ 0, 1 ], "description": "Whether open-tracking is enabled (post server-side forcing)", "example": 1 }, "unsubscribe": { "type": "integer", "enum": [ 0, 1 ], "description": "Whether unsubscribe-tracking is enabled (post server-side forcing: 1 for free accounts)", "example": 1 } } } } } } } } } }, "400": { "description": "Business failure. HTTP status is 200 in the actual response body convention; the codes below are the statusCode values returned with result=false.", "content": { "application/json": { "examples": { "40005": { "summary": "GLOBAL_AUTH_FAILED — apiUser/apiKey missing or invalid", "value": { "statusCode": 40005, "message": "Authentication failed", "result": false } }, "41018": { "summary": "TRACK_DOMAIN_NON_EXISTS — trackDomainName not found among the caller's tracking domains", "value": { "statusCode": 41018, "message": "track domain non-exists", "result": false } }, "41019": { "summary": "TRACK_DOMAIN_NOT_CONFIGURED — tracking domain exists but CNAME status is neither passed nor todo", "value": { "statusCode": 41019, "message": "track domain CNAME record not configured", "result": false } }, "41101": { "summary": "APIUSER_EMAIL_TYPE_NOTEMPTY — emailType missing", "value": { "statusCode": 41101, "message": "emailType cannot be an empty string", "result": false } }, "41102": { "summary": "APIUSER_EMAIL_TYPE_FORMAT_ERROR — emailType non-integer or not in {0,1}", "value": { "statusCode": 41102, "message": "emailType does not conform to the rules", "result": false } }, "41105": { "summary": "APIUSER_DOMAIN_NAME_NOTEMPTY — domainName missing", "value": { "statusCode": 41105, "message": "domainName cannot be an empty string", "result": false } }, "41106": { "summary": "APIUSER_DOMAIN_NAME_FORMAT_ERROR — domainName fails domain regex (e.g. a label longer than 48 chars)", "value": { "statusCode": 41106, "message": "domainName does not match the rule", "result": false } }, "41107": { "summary": "APIUSER_DOMAIN_NAME_LENGTH_EXCEEDED — domainName shorter than 4 or longer than 255", "value": { "statusCode": 41107, "message": "domainName should be 4-255 characters long", "result": false } }, "41108": { "summary": "APIUSER_DOMAIN_NAME_ERROR — domainName is not an existing domain of the caller", "value": { "statusCode": 41108, "message": "The domain name to which domainName does not exist", "result": false } }, "41109": { "summary": "APIUSER_USERINFO_NOT_EXISTS — user info missing for the authenticated account", "value": { "statusCode": 41109, "message": "User information does not exist", "result": false } }, "41110": { "summary": "APIUSER_NAME_NOTEMPTY — name missing", "value": { "statusCode": 41110, "message": "name cannot be an empty string", "result": false } }, "41111": { "summary": "APIUSER_NAME_FORMAT_ERROR — name fails ^[A-Za-z0-9_][A-Za-z0-9_@.-]{5,63}$", "value": { "statusCode": 41111, "message": "name does not match the rule , name is a string of 6-64 length , can only contain (AZ, az, 0-9, _,-,.,@)", "result": false } }, "41112": { "summary": "APIUSER_UNSUBSCRIBE_PAGE_ID_NOT_EXIST — unsubscribePageId does not reference an existing page of the caller (code shared with APIUSER_MAX_COUNT_EXCEEDED)", "value": { "statusCode": 41112, "message": "The unsubscribe Page does not exist", "result": false } }, "41113": { "summary": "APIUSER_UNSUBSCRIBE_PAGE_ID_FORMAT_ERROR — unsubscribePageId non-integer, <=0 or >=2147483647 (code shared with APIUSER_OPEN_NOTEMPTY)", "value": { "statusCode": 41113, "message": "unsubscribePageId format error", "result": false } }, "41114": { "summary": "APIUSER_OPEN_FORMAT_ERROR — open non-integer or not in {0,1} (code shared with APIUSER_UNSUBSCRIBE_PAGE_ID_NOT_EMPTY)", "value": { "statusCode": 41114, "message": "open does not match the rule", "result": false } }, "41116": { "summary": "APIUSER_CLICK_FORMAT_ERROR — click non-integer or not in {0,1}", "value": { "statusCode": 41116, "message": "click does not match the rule", "result": false } }, "41118": { "summary": "APIUSER_UNSUBSCRIBE_FORMAT_ERROR — unsubscribe non-integer or not in {0,1}", "value": { "statusCode": 41118, "message": "unsubscribe does not match the rule", "result": false } }, "41119": { "summary": "APIUSER_CREATE_FAILED — creation rejected by the service layer; message carries the service detail (e.g. 'API_USER already exists', 'domain does not exist', 'Normal API_USER cannot bind test domain names', 'API_USER cannot bind to an unauthenticated domain name')", "value": { "statusCode": 41119, "message": "apiUser creation failed. API_USER already exists", "result": false } }, "41128": { "summary": "APIUSER_TRACK_DOMAIN_NAME_FORMAT_ERROR — trackDomainName fails domain regex", "value": { "statusCode": 41128, "message": "trackDomainName does not match the rule", "result": false } }, "41129": { "summary": "APIUSER_TRACK_DOMAIN_NAME_LENGTH_EXCEEDED — trackDomainName shorter than 4 or longer than 255", "value": { "statusCode": 41129, "message": "trackDomainName should be 4-255 characters long", "result": false } }, "41112max": { "summary": "APIUSER_MAX_COUNT_EXCEEDED — account already holds 10 NORMAL API_USERs and is not whitelisted (shares code 41112)", "value": { "statusCode": 41112, "message": "apiUser not exceed a 10", "result": false } } } } } } } } } }, "components": { "securitySchemes": { "apiUser": { "type": "apiKey", "in": "query", "name": "apiUser", "description": "API user name for authentication" }, "apiKey": { "type": "apiKey", "in": "query", "name": "apiKey", "description": "API key for authentication" } } } } ``` # Sibling pages * [Get API\_USER List](https://docs.aurorasendcloud.com/reference/get-api-user-list.md) * [Update API\_USER](https://docs.aurorasendcloud.com/reference/update-api-user.md)