Skip to main content
The Courier endpoints allow administrators to view and monitor messages sent by Ory Kratos, including emails and SMS messages for recovery, verification, and authentication flows.

​
List courier messages

curl -X GET "https://{project}.projects.oryapis.com/admin/courier/messages?status=sent&page_size=50" \
  -H "Authorization: Bearer ory_at_..."
List all courier messages with optional filtering by status and recipient.

​
Query parameters

​
page_size
integer
default:"250"
Number of messages per page (min: 1, max: 1000).
​
page_token
string
Token for the next page of results. Use the value from the Link header in previous responses.
​
status
string
Filter messages by delivery status:
  • queued: Message is waiting to be sent
  • sent: Message was successfully delivered
  • processing: Message is currently being sent
  • abandoned: Message delivery was abandoned after retries
​
recipient
string
Filter messages by recipient email address or phone number.

​
Response

Returns an array of message objects:
​
id
string
Message UUID.
​
type
string
Message delivery channel:
  • email: Email message
  • phone: SMS message
​
status
string
Current delivery status: queued, sent, processing, or abandoned.
​
recipient
string
Email address or phone number of the recipient.
​
subject
string
Email subject line (empty for SMS).
​
body
string
Message body content.
​
template_type
string
The template used for this message:
  • recovery_valid: Valid recovery email/SMS
  • recovery_invalid: Invalid recovery attempt notification
  • recovery_code_valid: Recovery code message
  • recovery_code_invalid: Invalid recovery code notification
  • verification_valid: Valid verification email/SMS
  • verification_invalid: Invalid verification attempt
  • verification_code_valid: Verification code message
  • verification_code_invalid: Invalid verification code
  • login_code_valid: Login code message
  • registration_code_valid: Registration code message
​
send_count
integer
Number of delivery attempts made.
​
channel
string
The delivery channel used.
​
created_at
string
Timestamp when the message was created (RFC3339 format).
​
updated_at
string
Timestamp of the last status update.
​
dispatches
array
Array of delivery attempts.

​
Example response

[
  {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "type": "email",
    "status": "sent",
    "recipient": "[email protected]",
    "subject": "Recover access to your account",
    "body": "Please use this link to recover your account...",
    "template_type": "recovery_valid",
    "send_count": 1,
    "channel": "email",
    "created_at": "2026-03-03T10:00:00Z",
    "updated_at": "2026-03-03T10:00:05Z",
    "dispatches": [
      {
        "id": "f1e2d3c4-b5a6-7890-1234-567890fedcba",
        "message_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "status": "success",
        "created_at": "2026-03-03T10:00:05Z",
        "updated_at": "2026-03-03T10:00:05Z"
      }
    ]
  }
]

​
Error responses

  • 400: Invalid query parameters

​
Get a courier message

curl -X GET https://{project}.projects.oryapis.com/admin/courier/messages/{id} \
  -H "Authorization: Bearer ory_at_..."
Retrieve details of a specific courier message by its ID.

​
Path parameters

​
id
string
required
The message UUID.

​
Response

Returns a single message object with the same structure as the list endpoint.

​
Error responses

  • 400: Invalid message ID format
  • 404: Message not found

​
Understanding message statuses

​
Queued

The message is in the queue waiting to be processed and sent. Common reasons:
  • Message was just created
  • Courier service is processing other messages
  • Rate limiting is in effect

​
Processing

The message is currently being sent to the delivery provider. What happens:
  • Message is being transmitted to email/SMS gateway
  • Waiting for delivery confirmation

​
Sent

The message was successfully delivered. Important notes:
  • For email: Accepted by recipient’s mail server (not necessarily delivered to inbox)
  • For SMS: Accepted by SMS gateway (not necessarily delivered to device)

​
Abandoned

The message delivery was abandoned after multiple failed attempts. Common reasons:
  • Invalid recipient address
  • Temporary delivery failures exceeded retry limit
  • Email server rejection
  • SMS gateway errors

​
Message templates

Kratos uses different templates for various message types:

​
Recovery messages

  • recovery_valid: Valid recovery link/code
  • recovery_invalid: Notification of invalid recovery attempt
  • recovery_code_valid: Recovery code for code-based recovery
  • recovery_code_invalid: Invalid code notification

​
Verification messages

  • verification_valid: Valid verification link/code
  • verification_invalid: Invalid verification attempt
  • verification_code_valid: Verification code
  • verification_code_invalid: Invalid code notification

​
Authentication messages

  • login_code_valid: One-time login code
  • registration_code_valid: Registration verification code

​
Best practices

​
Monitoring message delivery

Track delivery rates: 
# Get sent messages
curl "https://{project}.projects.oryapis.com/admin/courier/messages?status=sent"

# Get abandoned messages
curl "https://{project}.projects.oryapis.com/admin/courier/messages?status=abandoned"
Calculate delivery success rate:
  • Monitor the ratio of sent vs abandoned messages
  • Track send_count to identify retry patterns
  • Review dispatch errors for abandoned messages

​
Debugging delivery issues

Check for specific recipient: 
curl "https://{project}.projects.oryapis.com/admin/courier/[email protected]"
Review dispatch attempts:
  • Check the dispatches array for error details
  • Look for patterns in failed deliveries
  • Verify recipient addresses are valid

​
Troubleshooting common issues

Messages stuck in queued:
  • Check courier service configuration
  • Verify SMTP/SMS gateway credentials
  • Review rate limiting settings
High abandonment rate:
  • Validate email addresses at registration
  • Check sender reputation and SPF/DKIM records
  • Review SMS gateway configuration
  • Ensure recipient addresses are properly formatted
Messages not arriving:
  • Check spam folders (for email)
  • Verify sender domain configuration
  • Review message templates for compliance
  • Check recipient’s provider restrictions

​
Configuration

Configure courier delivery in your Kratos configuration: 
courier:
  smtp:
    connection_uri: smtp://username:[email protected]:587
    from_address: [email protected]
    from_name: "My Application"
  
  sms:
    enabled: true
    from: "+1234567890"
    provider: twilio
    
  template_override_path: /path/to/email/templates

​
Audit and compliance

Use courier message logs for:
  • Audit trails: Track what communications were sent to users
  • Compliance: Prove notification delivery for regulatory requirements
  • Debugging: Investigate user reports of missing emails
  • Monitoring: Track system health and delivery rates
  • Security: Detect unusual messaging patterns or abuse

Build docs developers (and LLMs) love

Get started for freeTalk to us