Scoped SMS and TOTP for agents

An agent connection can use the phone numbers and TOTP devices allowed by its permissions and resource scope. The operator provisions and assigns resources; the running agent discovers what it can access with agentGetCapabilities and the channel-specific listing operations.

Assign phone numbers before the agent runs

Provision numbers through the dashboard or account API and assign the intended numbers to the agent connection. A scoped agent's phone listing returns only active assigned numbers. Phone provisioning is an operator action, separate from an agent reading or replying to SMS.

GET /agent/phone-numbers

List assigned phone numbers

Returns only active phone numbers explicitly assigned to this agent connection.

API reference Swagger UI operation

Request, parameters, and responses

Query parameters

Name	Type	Required	Description
`page`	`integer:int32`	No
`size`	`integer:int32`	No
`sort`	`enum: ASC \| DESC`	No	Values: ASC, DESC
`search`	`string`	No

Responses

Status	Schema	Description
`200`	`PageAgentPhoneNumber`	OK

HTTP and SDK snippets

HTTP

GET /agent/phone-numbers?page=value&size=value&sort=ASC HTTP/1.1
Host: api.mailslurp.com
x-api-key: YOUR_API_KEY
Accept: application/json

cURL

curl -X GET "https://api.mailslurp.com/agent/phone-numbers?page=value&size=value&sort=ASC" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

JavaScript SDK

import { Configuration, AgentControllerApi } from "mailslurp-client";

const config = new Configuration({ apiKey: "YOUR_API_KEY" });
const agentController = new AgentControllerApi(config);
const request = {
  "page": null,
  "size": null,
  "sort": "ASC"
};

const result = await agentController.agentGetPhoneNumbers(request);

Python SDK

import mailslurp_client
from mailslurp_client.api.agent_controller_api import AgentControllerApi

configuration = mailslurp_client.Configuration()
configuration.api_key["x-api-key"] = "YOUR_API_KEY"

with mailslurp_client.ApiClient(configuration) as api_client:
    agentController = AgentControllerApi(api_client)
    result = agentController.agent_get_phone_numbers(page=NaN, size=NaN, sort="ASC")

GET /agent/phone-numbers/{phoneNumberId}/sms

List received SMS for an assigned phone number

API reference Swagger UI operation

Request, parameters, and responses

Path parameters

Name	Type	Required	Description
`phoneNumberId`	`string:uuid`	Yes

Query parameters

Name	Type	Required	Description
`page`	`integer:int32`	No
`size`	`integer:int32`	No
`sort`	`enum: ASC \| DESC`	No	Values: ASC, DESC
`since`	`string:date-time`	No
`before`	`string:date-time`	No
`search`	`string`	No
`favourite`	`boolean`	No

Responses

Status	Schema	Description
`200`	`PageSmsProjection`	OK

HTTP and SDK snippets

HTTP

GET /agent/phone-numbers/00000000-0000-4000-8000-000000000000/sms?page=value&size=value&sort=ASC HTTP/1.1
Host: api.mailslurp.com
x-api-key: YOUR_API_KEY
Accept: application/json

cURL

curl -X GET "https://api.mailslurp.com/agent/phone-numbers/00000000-0000-4000-8000-000000000000/sms?page=value&size=value&sort=ASC" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

JavaScript SDK

import { Configuration, AgentControllerApi } from "mailslurp-client";

const config = new Configuration({ apiKey: "YOUR_API_KEY" });
const agentController = new AgentControllerApi(config);
const request = {
  "phoneNumberId": "00000000-0000-4000-8000-000000000000",
  "page": null,
  "size": null,
  "sort": "ASC"
};

const result = await agentController.agentGetReceivedSmsMessages(request);

Python SDK

import mailslurp_client
from mailslurp_client.api.agent_controller_api import AgentControllerApi

configuration = mailslurp_client.Configuration()
configuration.api_key["x-api-key"] = "YOUR_API_KEY"

with mailslurp_client.ApiClient(configuration) as api_client:
    agentController = AgentControllerApi(api_client)
    result = agentController.agent_get_received_sms_messages("00000000-0000-4000-8000-000000000000", page=NaN, size=NaN, sort="ASC")

Keep SMS read/history permissions separate from SMS send permission. Replying requires both because the agent reads an inbound message before sending its response. An email role or inbox assignment alone should not be assumed to grant phone access; check capabilities and the assigned resources.

Read and reply within scope

List the assigned phones and select the intended phone ID.
List its received SMS or message threads, using a time boundary when following a new action.
Retrieve the selected message and verify that it belongs to the intended workflow.
Reply only when the connection has the required permission and the application authorizes the response.
Inspect sent history and activity to confirm the outcome.

GET /agent/phone-numbers/{phoneNumberId}/message-threads

List SMS threads

API reference Swagger UI operation

Request, parameters, and responses

Path parameters

Name	Type	Required	Description
`phoneNumberId`	`string:uuid`	Yes

Query parameters

Name	Type	Required	Description
`page`	`integer:int32`	No
`size`	`integer:int32`	No

Responses

Status	Schema	Description
`200`	`PagePhoneMessageThreadProjection`	OK

HTTP and SDK snippets

HTTP

GET /agent/phone-numbers/00000000-0000-4000-8000-000000000000/message-threads?page=value&size=value HTTP/1.1
Host: api.mailslurp.com
x-api-key: YOUR_API_KEY
Accept: application/json

cURL

curl -X GET "https://api.mailslurp.com/agent/phone-numbers/00000000-0000-4000-8000-000000000000/message-threads?page=value&size=value" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

JavaScript SDK

import { Configuration, AgentControllerApi } from "mailslurp-client";

const config = new Configuration({ apiKey: "YOUR_API_KEY" });
const agentController = new AgentControllerApi(config);
const request = {
  "phoneNumberId": "00000000-0000-4000-8000-000000000000",
  "page": null,
  "size": null
};

const result = await agentController.agentGetPhoneMessageThreads(request);

Python SDK

import mailslurp_client
from mailslurp_client.api.agent_controller_api import AgentControllerApi

configuration = mailslurp_client.Configuration()
configuration.api_key["x-api-key"] = "YOUR_API_KEY"

with mailslurp_client.ApiClient(configuration) as api_client:
    agentController = AgentControllerApi(api_client)
    result = agentController.agent_get_phone_message_threads("00000000-0000-4000-8000-000000000000", page=NaN, size=NaN)

POST /agent/phone-numbers/{phoneNumberId}/sms/{smsId}/reply

Reply to received SMS

API reference Swagger UI operation

Request, parameters, and responses

Path parameters

Name	Type	Required	Description
`phoneNumberId`	`string:uuid`	Yes
`smsId`	`string:uuid`	Yes

Query parameters

Name	Type	Required	Description
`expectedConversationVersion`	`integer:int64`	No
`expectedLatestMessageId`	`string:uuid`	No

Header parameters

Name	Type	Required	Description
`Idempotency-Key`	`string`	No

Request body (required)

SmsReplyOptions application/json

Field	Type	Required	Description
`body`	`string`	Yes

Request example

{
  "body": "Hello from MailSlurp"
}

Responses

Status	Schema	Description
`201`	`SentSmsDto`	Created

HTTP and SDK snippets

HTTP

POST /agent/phone-numbers/00000000-0000-4000-8000-000000000000/sms/00000000-0000-4000-8000-000000000000/reply?expectedConversationVersion=value&expectedLatestMessageId=00000000-0000-4000-8000-000000000000 HTTP/1.1
Host: api.mailslurp.com
x-api-key: YOUR_API_KEY
Accept: application/json
Content-Type: application/json

{
  "body": "Hello from MailSlurp"
}

cURL

curl -X POST "https://api.mailslurp.com/agent/phone-numbers/00000000-0000-4000-8000-000000000000/sms/00000000-0000-4000-8000-000000000000/reply?expectedConversationVersion=value&expectedLatestMessageId=00000000-0000-4000-8000-000000000000" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"body":"Hello from MailSlurp"}'

JavaScript SDK

import { Configuration, AgentControllerApi } from "mailslurp-client";

const config = new Configuration({ apiKey: "YOUR_API_KEY" });
const agentController = new AgentControllerApi(config);
const request = {
  "phoneNumberId": "00000000-0000-4000-8000-000000000000",
  "smsId": "00000000-0000-4000-8000-000000000000",
  "expectedConversationVersion": null,
  "expectedLatestMessageId": "00000000-0000-4000-8000-000000000000",
  "smsReplyOptions": {
    "body": "Hello from MailSlurp"
  }
};

const result = await agentController.agentReplyToSms(request);

Python SDK

import mailslurp_client
from mailslurp_client.api.agent_controller_api import AgentControllerApi

configuration = mailslurp_client.Configuration()
configuration.api_key["x-api-key"] = "YOUR_API_KEY"

with mailslurp_client.ApiClient(configuration) as api_client:
    agentController = AgentControllerApi(api_client)
    sms_reply_options = {
      "body": "Hello from MailSlurp"
    }
    result = agentController.agent_reply_to_sms("00000000-0000-4000-8000-000000000000", "00000000-0000-4000-8000-000000000000", expected_conversation_version=NaN, expected_latest_message_id="00000000-0000-4000-8000-000000000000", sms_reply_options)

POST /agent/phone-numbers/{phoneNumberId}/sms

Send SMS from an assigned phone number

API reference Swagger UI operation

Request, parameters, and responses

Path parameters

Name	Type	Required	Description
`phoneNumberId`	`string:uuid`	Yes

Query parameters

Name	Type	Required	Description
`expectedConversationVersion`	`integer:int64`	No
`expectedLatestMessageId`	`string:uuid`	No

Header parameters

Name	Type	Required	Description
`Idempotency-Key`	`string`	No

Request body (required)

SmsSendOptions application/json

Field	Type	Required	Description
`to`	`string`	Yes
`body`	`string`	Yes

Request example

{
  "to": "+15551234567",
  "body": "Hello from MailSlurp"
}

Responses

Status	Schema	Description
`201`	`SentSmsDto`	Created

HTTP and SDK snippets

HTTP

POST /agent/phone-numbers/00000000-0000-4000-8000-000000000000/sms?expectedConversationVersion=value&expectedLatestMessageId=00000000-0000-4000-8000-000000000000 HTTP/1.1
Host: api.mailslurp.com
x-api-key: YOUR_API_KEY
Accept: application/json
Content-Type: application/json

{
  "to": "+15551234567",
  "body": "Hello from MailSlurp"
}

cURL

curl -X POST "https://api.mailslurp.com/agent/phone-numbers/00000000-0000-4000-8000-000000000000/sms?expectedConversationVersion=value&expectedLatestMessageId=00000000-0000-4000-8000-000000000000" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"to":"+15551234567","body":"Hello from MailSlurp"}'

JavaScript SDK

import { Configuration, AgentControllerApi } from "mailslurp-client";

const config = new Configuration({ apiKey: "YOUR_API_KEY" });
const agentController = new AgentControllerApi(config);
const request = {
  "phoneNumberId": "00000000-0000-4000-8000-000000000000",
  "expectedConversationVersion": null,
  "expectedLatestMessageId": "00000000-0000-4000-8000-000000000000",
  "smsSendOptions": {
    "to": "+15551234567",
    "body": "Hello from MailSlurp"
  }
};

const result = await agentController.agentSendSms(request);

Python SDK

import mailslurp_client
from mailslurp_client.api.agent_controller_api import AgentControllerApi

configuration = mailslurp_client.Configuration()
configuration.api_key["x-api-key"] = "YOUR_API_KEY"

with mailslurp_client.ApiClient(configuration) as api_client:
    agentController = AgentControllerApi(api_client)
    sms_send_options = {
      "to": "+15551234567",
      "body": "Hello from MailSlurp"
    }
    result = agentController.agent_send_sms("00000000-0000-4000-8000-000000000000", expected_conversation_version=NaN, expected_latest_message_id="00000000-0000-4000-8000-000000000000", sms_send_options)

For supervised SMS conversations, use the SMS claim, renewal and handoff operations. Do not reuse email conversation IDs or assume an email claim also reserves a phone.

POST /agent/sms-conversations/{conversationId}/claims

Acquire an SMS conversation claim

API reference Swagger UI operation

Request, parameters, and responses

Path parameters

Name	Type	Required	Description
`conversationId`	`string:uuid`	Yes

Request body (required)

AcquireAgentConversationClaimOptions application/json

Field	Type	Required
`workerId`	`string`	Yes
`leaseSeconds`	`integer:int32`	Yes
`expectedVersion`	`integer:int64`	No

Request example

{
  "workerId": "00000000-0000-4000-8000-000000000000",
  "leaseSeconds": 1,
  "expectedVersion": 1
}

Responses

Status	Schema	Description
`201`	`AgentConversationClaimDto`	Created

HTTP and SDK snippets

HTTP

POST /agent/sms-conversations/00000000-0000-4000-8000-000000000000/claims HTTP/1.1
Host: api.mailslurp.com
x-api-key: YOUR_API_KEY
Accept: application/json
Content-Type: application/json

{
  "workerId": "00000000-0000-4000-8000-000000000000",
  "leaseSeconds": 1,
  "expectedVersion": 1
}

cURL

curl -X POST "https://api.mailslurp.com/agent/sms-conversations/00000000-0000-4000-8000-000000000000/claims" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"workerId":"00000000-0000-4000-8000-000000000000","leaseSeconds":1,"expectedVersion":1}'

JavaScript SDK

import { Configuration, AgentControllerApi } from "mailslurp-client";

const config = new Configuration({ apiKey: "YOUR_API_KEY" });
const agentController = new AgentControllerApi(config);
const request = {
  "conversationId": "00000000-0000-4000-8000-000000000000",
  "acquireAgentConversationClaimOptions": {
    "workerId": "00000000-0000-4000-8000-000000000000",
    "leaseSeconds": 1,
    "expectedVersion": 1
  }
};

const result = await agentController.agentClaimSmsConversation(request);

Python SDK

import mailslurp_client
from mailslurp_client.api.agent_controller_api import AgentControllerApi

configuration = mailslurp_client.Configuration()
configuration.api_key["x-api-key"] = "YOUR_API_KEY"

with mailslurp_client.ApiClient(configuration) as api_client:
    agentController = AgentControllerApi(api_client)
    acquire_agent_conversation_claim_options = {
      "workerId": "00000000-0000-4000-8000-000000000000",
      "leaseSeconds": 1,
      "expectedVersion": 1
    }
    result = agentController.agent_claim_sms_conversation("00000000-0000-4000-8000-000000000000", acquire_agent_conversation_claim_options)

PUT /agent/sms-conversations/{conversationId}/claims/{claimId}

Renew an SMS conversation claim

API reference Swagger UI operation

Request, parameters, and responses

Path parameters

Name	Type	Required	Description
`conversationId`	`string:uuid`	Yes
`claimId`	`string:uuid`	Yes

Request body (required)

RenewAgentConversationClaimOptions application/json

Field	Type	Required	Description
`leaseSeconds`	`integer:int32`	Yes

Request example

{
  "leaseSeconds": 1
}

Responses

Status	Schema	Description
`200`	`AgentConversationClaimDto`	OK

HTTP and SDK snippets

HTTP

PUT /agent/sms-conversations/00000000-0000-4000-8000-000000000000/claims/00000000-0000-4000-8000-000000000000 HTTP/1.1
Host: api.mailslurp.com
x-api-key: YOUR_API_KEY
Accept: application/json
Content-Type: application/json

{
  "leaseSeconds": 1
}

cURL

curl -X PUT "https://api.mailslurp.com/agent/sms-conversations/00000000-0000-4000-8000-000000000000/claims/00000000-0000-4000-8000-000000000000" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"leaseSeconds":1}'

JavaScript SDK

import { Configuration, AgentControllerApi } from "mailslurp-client";

const config = new Configuration({ apiKey: "YOUR_API_KEY" });
const agentController = new AgentControllerApi(config);
const request = {
  "conversationId": "00000000-0000-4000-8000-000000000000",
  "claimId": "00000000-0000-4000-8000-000000000000",
  "renewAgentConversationClaimOptions": {
    "leaseSeconds": 1
  }
};

const result = await agentController.agentRenewSmsClaim(request);

Python SDK

import mailslurp_client
from mailslurp_client.api.agent_controller_api import AgentControllerApi

configuration = mailslurp_client.Configuration()
configuration.api_key["x-api-key"] = "YOUR_API_KEY"

with mailslurp_client.ApiClient(configuration) as api_client:
    agentController = AgentControllerApi(api_client)
    renew_agent_conversation_claim_options = {
      "leaseSeconds": 1
    }
    result = agentController.agent_renew_sms_claim("00000000-0000-4000-8000-000000000000", "00000000-0000-4000-8000-000000000000", renew_agent_conversation_claim_options)

POST /agent/sms-conversations/{conversationId}/handoffs

Request human review for an SMS conversation

API reference Swagger UI operation

Request, parameters, and responses

Path parameters

Name	Type	Required	Description
`conversationId`	`string:uuid`	Yes

Request body (required)

CreateAgentSmsConversationHandoffOptions application/json

Field	Type	Required
`reasonCode`	`string`	Yes
`reason`	`string`	No
`priority`	`enum: LOW \| NORMAL \| HIGH \| URGENT`	Yes
`sourceSmsId`	`string:uuid`	No
`expectedVersion`	`integer:int64`	No

Request example

{
  "reasonCode": "value",
  "priority": "LOW",
  "reason": "value",
  "sourceSmsId": "00000000-0000-4000-8000-000000000000",
  "expectedVersion": 1
}

Responses

Status	Schema	Description
`201`	`AgentConversationHandoffDto`	Created

HTTP and SDK snippets

HTTP

POST /agent/sms-conversations/00000000-0000-4000-8000-000000000000/handoffs HTTP/1.1
Host: api.mailslurp.com
x-api-key: YOUR_API_KEY
Accept: application/json
Content-Type: application/json

{
  "reasonCode": "value",
  "priority": "LOW",
  "reason": "value",
  "sourceSmsId": "00000000-0000-4000-8000-000000000000",
  "expectedVersion": 1
}

cURL

curl -X POST "https://api.mailslurp.com/agent/sms-conversations/00000000-0000-4000-8000-000000000000/handoffs" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"reasonCode":"value","priority":"LOW","reason":"value","sourceSmsId":"00000000-0000-4000-8000-000000000000","expectedVersion":1}'

JavaScript SDK

import { Configuration, AgentControllerApi } from "mailslurp-client";

const config = new Configuration({ apiKey: "YOUR_API_KEY" });
const agentController = new AgentControllerApi(config);
const request = {
  "conversationId": "00000000-0000-4000-8000-000000000000",
  "createAgentSmsConversationHandoffOptions": {
    "reasonCode": "value",
    "priority": "LOW",
    "reason": "value",
    "sourceSmsId": "00000000-0000-4000-8000-000000000000",
    "expectedVersion": 1
  }
};

const result = await agentController.agentRequestSmsHandoff(request);

Python SDK

import mailslurp_client
from mailslurp_client.api.agent_controller_api import AgentControllerApi

configuration = mailslurp_client.Configuration()
configuration.api_key["x-api-key"] = "YOUR_API_KEY"

with mailslurp_client.ApiClient(configuration) as api_client:
    agentController = AgentControllerApi(api_client)
    create_agent_sms_conversation_handoff_options = {
      "reasonCode": "value",
      "priority": "LOW",
      "reason": "value",
      "sourceSmsId": "00000000-0000-4000-8000-000000000000",
      "expectedVersion": 1
    }
    result = agentController.agent_request_sms_handoff("00000000-0000-4000-8000-000000000000", create_agent_sms_conversation_handoff_options)

Use an authenticator device

For applications using TOTP, list or find an agent-accessible device, then generate a code for the authorized authentication step. With the appropriate permissions, agent-managed devices can be created from a base32 secret or an otpauth URL.

GET /agent/totp/devices

List agent-accessible TOTP devices

API reference Swagger UI operation

Request, parameters, and responses

Query parameters

Name	Type	Required	Description
`page`	`integer:int32`	No
`size`	`integer:int32`	No
`sort`	`enum: ASC \| DESC`	No	Values: ASC, DESC
`issuer`	`string`	No
`username`	`string`	No

Responses

Status	Schema	Description
`200`	`PageTotpDeviceProjection`	OK

HTTP and SDK snippets

HTTP

GET /agent/totp/devices?page=value&size=value&sort=ASC HTTP/1.1
Host: api.mailslurp.com
x-api-key: YOUR_API_KEY
Accept: application/json

cURL

curl -X GET "https://api.mailslurp.com/agent/totp/devices?page=value&size=value&sort=ASC" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

JavaScript SDK

import { Configuration, AgentControllerApi } from "mailslurp-client";

const config = new Configuration({ apiKey: "YOUR_API_KEY" });
const agentController = new AgentControllerApi(config);
const request = {
  "page": null,
  "size": null,
  "sort": "ASC"
};

const result = await agentController.agentGetTotpDevices(request);

Python SDK

import mailslurp_client
from mailslurp_client.api.agent_controller_api import AgentControllerApi

configuration = mailslurp_client.Configuration()
configuration.api_key["x-api-key"] = "YOUR_API_KEY"

with mailslurp_client.ApiClient(configuration) as api_client:
    agentController = AgentControllerApi(api_client)
    result = agentController.agent_get_totp_devices(page=NaN, size=NaN, sort="ASC")

POST /agent/totp/devices/otp-auth-url

Create an agent-managed TOTP device from an OTP Auth URL

API reference Swagger UI operation

Request, parameters, and responses

Request body (required)

CreateTotpDeviceOtpAuthUrlOptions application/json

Field	Type	Required	Description
`otpAuthUrl`	`string`	Yes	OTP Auth URI for connecting a TOTP device.
`name`	`string`	No	Name for labeling the TOTP device
`username`	`string`	No	Optional username for the TOTP device
`issuer`	`string`	No	Optional issuer override for the TOTP device
`digits`	`integer:int32`	No	Optional number of digits in TOTP code
`period`	`integer:int32`	No	Optional period in seconds for TOTP code expiration
`algorithm`	`string`	No	Optional algorithm override

Request example

{
  "otpAuthUrl": "otpauth://totp/your-app:contact%40mailslurp.dev?secret=LJCTOYKGGBAWCMSHJRZGITCVLIXCG4JY&issuer=your-app&algorithm=SHA1&digits=6&period=30",
  "name": "Example name",
  "username": "Example name",
  "issuer": "value",
  "digits": 6,
  "period": 30
}

Responses

Status	Schema	Description
`201`	`TotpDeviceDto`	Created

HTTP and SDK snippets

HTTP

POST /agent/totp/devices/otp-auth-url HTTP/1.1
Host: api.mailslurp.com
x-api-key: YOUR_API_KEY
Accept: application/json
Content-Type: application/json

{
  "otpAuthUrl": "otpauth://totp/your-app:contact%40mailslurp.dev?secret=LJCTOYKGGBAWCMSHJRZGITCVLIXCG4JY&issuer=your-app&algorithm=SHA1&digits=6&period=30",
  "name": "Example name",
  "username": "Example name",
  "issuer": "value",
  "digits": 6,
  "period": 30
}

cURL

curl -X POST "https://api.mailslurp.com/agent/totp/devices/otp-auth-url" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"otpAuthUrl":"otpauth://totp/your-app:contact%40mailslurp.dev?secret=LJCTOYKGGBAWCMSHJRZGITCVLIXCG4JY&issuer=your-app&algorithm=SHA1&digits=6&period=30","name":"Example name","username":"Example name","issuer":"value","digits":6,"period":30}'

JavaScript SDK

import { Configuration, AgentControllerApi } from "mailslurp-client";

const config = new Configuration({ apiKey: "YOUR_API_KEY" });
const agentController = new AgentControllerApi(config);
const request = {
  "createTotpDeviceOtpAuthUrlOptions": {
    "otpAuthUrl": "otpauth://totp/your-app:contact%40mailslurp.dev?secret=LJCTOYKGGBAWCMSHJRZGITCVLIXCG4JY&issuer=your-app&algorithm=SHA1&digits=6&period=30",
    "name": "Example name",
    "username": "Example name",
    "issuer": "value",
    "digits": 6,
    "period": 30
  }
};

const result = await agentController.agentCreateTotpDeviceForOtpAuthUrl(request);

Python SDK

import mailslurp_client
from mailslurp_client.api.agent_controller_api import AgentControllerApi

configuration = mailslurp_client.Configuration()
configuration.api_key["x-api-key"] = "YOUR_API_KEY"

with mailslurp_client.ApiClient(configuration) as api_client:
    agentController = AgentControllerApi(api_client)
    create_totp_device_otp_auth_url_options = {
      "otpAuthUrl": "otpauth://totp/your-app:contact%40mailslurp.dev?secret=LJCTOYKGGBAWCMSHJRZGITCVLIXCG4JY&issuer=your-app&algorithm=SHA1&digits=6&period=30",
      "name": "Example name",
      "username": "Example name",
      "issuer": "value",
      "digits": 6,
      "period": 30
    }
    result = agentController.agent_create_totp_device_for_otp_auth_url(create_totp_device_otp_auth_url_options)

GET /agent/totp/devices/{id}/code

Generate a code for an agent-managed TOTP device

API reference Swagger UI operation

Request, parameters, and responses

Path parameters

Name	Type	Required	Description
`id`	`string:uuid`	Yes

Query parameters

Name	Type	Required	Description
`at`	`string:date-time`	No
`minSecondsUntilExpire`	`integer:int32`	No	Minimum remaining code lifetime. The request may wait for the next period when needed.

Responses

Status	Schema	Description
`200`	`TotpDeviceCodeDto`	OK

HTTP and SDK snippets

HTTP

GET /agent/totp/devices/00000000-0000-4000-8000-000000000000/code?at=2026-06-21T00%3A00%3A00.000Z&minSecondsUntilExpire=value HTTP/1.1
Host: api.mailslurp.com
x-api-key: YOUR_API_KEY
Accept: application/json

cURL

curl -X GET "https://api.mailslurp.com/agent/totp/devices/00000000-0000-4000-8000-000000000000/code?at=2026-06-21T00%3A00%3A00.000Z&minSecondsUntilExpire=value" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

JavaScript SDK

import { Configuration, AgentControllerApi } from "mailslurp-client";

const config = new Configuration({ apiKey: "YOUR_API_KEY" });
const agentController = new AgentControllerApi(config);
const request = {
  "id": "00000000-0000-4000-8000-000000000000",
  "at": "2026-06-21T00:00:00.000Z",
  "minSecondsUntilExpire": null
};

const result = await agentController.agentGenerateTotpDeviceCode(request);

Python SDK

import mailslurp_client
from mailslurp_client.api.agent_controller_api import AgentControllerApi

configuration = mailslurp_client.Configuration()
configuration.api_key["x-api-key"] = "YOUR_API_KEY"

with mailslurp_client.ApiClient(configuration) as api_client:
    agentController = AgentControllerApi(api_client)
    result = agentController.agent_generate_totp_device_code("00000000-0000-4000-8000-000000000000", at="2026-06-21T00:00:00.000Z", min_seconds_until_expire=NaN)

Treat the enrollment secret and generated code as credentials. Keep them out of shared logs, generate a fresh code near the submission step and verify the application's authenticated state. See TOTP testing for the enrollment and verification flow.

Choose the correct credential

Use a scoped agent key for the operations documented here. An account key belongs in a separate provisioning service when account-level setup is required. For browser-test suites using ordinary account APIs, see SMS waits and phone pool leases. Check the connected MCP client's available tool list before assuming every REST operation is exposed as an MCP tool.

Build with MailSlurp

Connect & learn

Scoped SMS and TOTP for agents

Assign phone numbers before the agent runs

Read and reply within scope

Use an authenticator device

Choose the correct credential

The complete email and SMS toolkit.