AWS SQS ExecModule

Overview

AwsSqsModule connects ValkyrAI workflows to Amazon Simple Queue Service through the bundled AWS SDK v2 client. It covers n8n's core SQS producer and consumer use cases while adding queue discovery, attributes, strict region-to-queue routing, verified IntegrationAccount credentials, annotation-backed Workflow Studio discovery, bounded outputs, and explicit replay boundaries.

The connector implements six operations:

• queue discovery: list_queues, get_queue_attributes
• message production: send_message
• message consumption: receive_messages, change_message_visibility, delete_message

Queue creation, queue deletion, policy mutation, permission changes, dead-letter replay, tagging, and queue purge are intentionally outside this first governed surface.

Usage

1. Create a dedicated AWS IAM principal scoped to the exact queues and SQS actions the workflow needs.
2. Store its access key ID and secret access key in an AWS IntegrationAccount, verify the account, and keep it in READY status.
3. Add AwsSqsModule to a workflow and bind the account through ExecModuleConfig.authConfig.integrationAccount.
4. Set operation, region, and the exact operation-specific queue, message, receipt, or pagination fields.
5. Preserve returned message IDs, receipt handles, and AWS request IDs. Reconcile provider state before replaying any ambiguous message operation.

Never place AWS credentials in mapped input, message attributes, logs, or examples. Credential-like input fields are rejected before provider access.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the six documented operations.
region	string	Every execution	None	AWS region syntax such as us-west-2; custom endpoints are not accepted.
queueUrl	string	All except list_queues	None	Exact HTTPS URL for the configured region, 12-digit account, and queue name.
queueNamePrefix	string	Optional list_queues	None	1-80 letters, numbers, hyphens, or underscores.
messageBody	string	send_message	None	1 byte through 1 MiB using the SQS-supported Unicode ranges.
messageAttributes	object	Optional send_message	{}	At most ten String attributes; AWS/Amazon reserved prefixes are rejected.
delaySeconds	integer	Optional standard-queue send	0	0-900; per-message delay is rejected for FIFO queues.
messageGroupId	string	FIFO send_message	None	Required for .fifo queues; 1-128 bytes.
messageDeduplicationId	string	Optional FIFO send	None	1-128 bytes; use unless content-based deduplication is configured.
receiptHandle	string	delete_message, change_message_visibility	None	Opaque receipt from the most recent receive, at most 8,192 characters.
visibilityTimeout	integer	Receive or visibility change	30	0-43,200 seconds.
maxMessages	integer	receive_messages	1	1-10 messages.
waitTimeSeconds	integer	receive_messages	0	0-20 seconds.
receiveAttemptId	string	Optional FIFO receive	None	FIFO only; 1-128 bytes.
nextToken	string	Optional list resume point	None	Opaque AWS continuation, at most 4,096 characters.
limit	integer	list_queues	100	1-10,000 queues; each provider request asks for at most 1,000.
returnAll	boolean	list_queues	false	Follow fixed-provider pages until exhaustion or limit.
confirmDelete	boolean	delete_message	false	Must be explicitly true before acknowledging/deleting a message.

Outputs

Every execution returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
attempts	integer	Always	Provider calls, including discovery retries and pages.
data	object	Attributes or mutation success	Queue attributes, send receipt, delete receipt, or visibility receipt.
items	array	List or receive success	Bounded queue URLs or received messages.
count	integer	List or receive success	Number of returned items.
hasMore	boolean	Queue-list success	Whether another provider page exists.
nextToken	string	Another queue page exists	Opaque continuation for a later execution.
requestId	string	AWS supplies one	Bounded provider reference for reconciliation and support.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Received message items contain the provider messageId, opaque receiptHandle, body, body checksum, and bounded String/binary message attributes. Receipt handles and message bodies are confidential workflow data; do not log or forward them to unapproved destinations.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / SQS
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Grant only the actions used by the workflow:

• sqs:ListQueues for list_queues
• sqs:GetQueueAttributes for get_queue_attributes
• sqs:SendMessage for send_message
• sqs:ReceiveMessage for receive_messages
• sqs:ChangeMessageVisibility for visibility extensions or releases
• sqs:DeleteMessage for confirmed acknowledgement

Restrict resource-scoped actions to the exact queue ARNs. ListQueues is the only operation here that AWS does not resource-scope. The current connector supports a long-lived access-key pair. Temporary session credentials, role assumption, cross-account role chaining, VPC/custom endpoints, and caller-supplied credentials are deferred.

Configuration

The awsAccount relationship is the only credential configuration. Operation, region, queue, message, receipt, and list controls belong in module parameters or mapped input; read retries use the normalized retry policy.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-sqs-production"
  },
  "retryPolicy": {
    "maxAttempts": 3
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"send_message\",\"region\":\"us-west-2\",\"queueUrl\":\"https://sqs.us-west-2.amazonaws.com/123456789012/agent-work\"}"
  }
}

The relationship value is illustrative. Persisted workflows bind the generated IntegrationAccount relationship, never plaintext credentials.

Operations

Operation	Provider behavior	Side effect and retry behavior
list_queues	Lists region queues with optional prefix and opaque token pagination.	Read-only; transient failures retry within the configured bound.
get_queue_attributes	Reads all attributes of one exact queue.	Read-only; transient failures retry. Approximate counts are eventually consistent.
send_message	Sends one bounded standard or FIFO message.	External write; exactly one provider attempt.
receive_messages	Long-polls for up to ten messages and returns receipt handles.	Changes message visibility; exactly one provider attempt.
change_message_visibility	Changes one received message's visibility timeout.	External state change; exactly one provider attempt.
delete_message	Permanently acknowledges one receipt.	Destructive; requires confirmDelete=true; exactly one provider attempt.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing or invalid region, queue URL, message, receipt, bound, FIFO option, or confirmation.	No	Correct the named input; no provider request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or missing key material.	No	Repair and bind the AWS account.
AWS_SQS_HTTP_400	Invalid queue, receipt, message content, FIFO option, or throttled request.	Provider-dependent	Inspect the current queue and receipt state; do not blindly replay writes.
AWS_SQS_HTTP_403	IAM denies the action.	No	Grant only the missing action on the intended queue.
AWS_SQS_HTTP_404	Queue is absent or invisible.	No	Verify region, account, and exact queue URL.
AWS_SQS_HTTP_429 / 503	Transient provider pressure.	Yes for discovery only	Discovery can retry; reconcile all message operations before replay.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Yes for discovery only	Treat message operation outcomes as ambiguous.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve queue, message, receipt, and request IDs for reconciliation.

Provider exception text is not copied into output, preventing credential echoes and unbounded error payloads.

Example

Send a correlated work item to a standard queue:

{
  "operation": "send_message",
  "region": "us-west-2",
  "queueUrl": "https://sqs.us-west-2.amazonaws.com/123456789012/agent-work",
  "messageBody": "{\"jobId\":\"job-123\",\"action\":\"enrich_customer\"}",
  "messageAttributes": {
    "correlationId": "workflow-2026-09-04-job-123",
    "tenant": "acme"
  },
  "delaySeconds": 0
}

Expected result shape:

{
  "status": "success",
  "operation": "send_message",
  "attempts": 1,
  "requestId": "aws-request-reference",
  "data": {
    "messageId": "provider-message-id",
    "bodyMd5": "provider-checksum",
    "attributesMd5": "provider-checksum"
  }
}

Notes

• Pagination: list_queues preserves AWS tokens as opaque values. returnAll=true follows only the region-derived SQS endpoint and stops at limit or 10,000 queues.
• Rate limits: HTTP 408, 429, 500, 502, 503, and 504 plus network failures can retry only for list_queues and get_queue_attributes, bounded by RetryPolicy.maxAttempts from 1 through 5. AWS SDK retries are disabled so module accounting and single-attempt message behavior remain deterministic.
• API limits: message bodies and the aggregate send attribute envelope are bounded at 1 MiB. Receive batches are limited to ten messages and a 5 MiB body envelope. Long polling is capped at 20 seconds and visibility at 12 hours.
• Idempotency: standard-queue sends have no universal provider idempotency key. FIFO sends may use messageDeduplicationId, but callers must still reconcile ambiguous responses. A FIFO receiveAttemptId can deduplicate receive attempts only within AWS's provider window; this module never retries receive automatically.
• Destructive behavior: delete_message permanently acknowledges the message identified by the receipt handle and requires explicit confirmation. Purge and queue deletion are not exposed.
• Queue semantics: delivery is at least once, standard queues can reorder messages, receipt handles change across receives, and approximate queue counts are eventually consistent. Consumers must be idempotent.
• Data handling: message bodies, attributes, and receipt handles are confidential. The module never logs request or response bodies.
• Provider verification boundary: deterministic tests cover validation, fixed routing, account isolation, request mapping, pagination, retry boundaries, normalization, redaction, registration, FIFO guards, and deletion confirmation. Live AWS behavior remains unverified until an authorized SQS credential and reviewed test queue are supplied.
• Functional reference: n8n's AWS SQS integration centers on sending messages to and consuming messages from SQS queues. ValkyrAI adds queue discovery and attributes, strict endpoint validation, verified IntegrationAccount enforcement, bounded output, explicit acknowledgement, and conservative single-attempt semantics.
• Runtime boundary: merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsSqsModule through /v1/modules/metadata.

Related Documentation

• ExecModule catalog
• AWS Lambda ExecModule
• AWS S3 ExecModule
• AWS Fargate Launch ExecModule
• Integration Account Console