Skip to content
Kirim.Email SMTP API

Create a new credential

POST
/api/domains/{domain}/credentials
curl --request POST \
  --url https://smtp-app.kirim.email/api/domains/example.com/credentials \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '{ "username": "myuser" }'

Create a new SMTP credential for a domain

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
domain
required
string
Example
example.com

Domain name that must be owned by the authenticated user. The domain must be verified and properly configured for email sending.

Request Bodyrequired

Section titled “Request Bodyrequired”

SMTP credential creation details

object
username
required

SMTP username

string
Example
myuser

Responses

Section titled “Responses”

201

Section titled “201”

Credential created successfully

Media typeapplication/json
object
success

Indicates if the request was successful

boolean
message

Human-readable success message

string
data

Created credential data and metadata

object
credential

SMTP credential object containing authentication details for email sending

object
id

Database auto-increment ID (internal use only)

integer
user_smtp_guid

Unique credential GUID used for API operations

string
username

SMTP username for authentication. Must be unique within the domain

string
created_at

Unix timestamp when the credential was created

integer
modified_at

Unix timestamp when the credential was last modified

integer
password

Generated password for the credential. Store this securely as it cannot be retrieved later

string
remote_synced

Whether the credential was successfully synchronized with the remote SMTP server

boolean
Example
{
  "success": true,
  "message": "Credential created successfully.",
  "data": {
    "credential": {
      "id": 1,
      "user_smtp_guid": "92703823-f3a4-48e2-8e87-7adf25454800",
      "username": "myuser",
      "created_at": 1640995200,
      "modified_at": 1640995200
    },
    "password": "generated-password",
    "remote_synced": true
  }
}

401

Section titled “401”

Unauthorized - Invalid or missing authentication credentials

Media typeapplication/json
object
success
boolean
message
string
Example
{
  "success": false,
  "message": "Unauthorized"
}

404

Section titled “404”

Credential not found

Media typeapplication/json
object
success
boolean
message
string
Example
{
  "success": false,
  "message": "Credential not found"
}

422

Section titled “422”

Validation Error - Invalid input data

Media typeapplication/json
object
success
boolean
message
string
errors

Field-specific validation errors

object
Example
{
  "success": false,
  "message": "Validation failed."
}

429

Section titled “429”

Too Many Requests - Rate limit exceeded. Retry after the specified time.

Media typeapplication/json
object
success
boolean
message
string
Example
{
  "success": false,
  "message": "Too many attempts. Please try again later."
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds until rate limit resets

X-RateLimit-Limit
integer

Maximum requests per minute

X-RateLimit-Remaining
integer

Remaining requests in current window

500

Section titled “500”

Server Error - Unexpected error occurred

Media typeapplication/json
object
success
boolean
message
string
Example
{
  "success": false,
  "message": "An error occurred while processing the request."
}