Mailbox - Aya

The Mailbox system enables direct communication between profiles through conversations, messages, invitations, and special envelope types.

Overview

Mailbox features:

Profile-to-profile conversations (not user-to-user)
Multiple envelope types: messages, invitations, badges, passes
Threaded conversations with participants
Emoji reactions on messages
Read receipts and unread counts
System-generated notifications

Mailbox operates at the profile level. Users communicate via their individual profiles to other profiles (individual, organization, or community).

Conversations

Conversation Types

Direct

One-on-one profile conversations

System

Automated notifications from Aya platform

Creating a Conversation

Navigate to profile

Visit the profile you want to message

Click 'Send Message'

Opens compose dialog

Write message

Compose your message content

Send

Conversation created (if doesn’t exist)
Participants added automatically
Message delivered as envelope

Conversation Properties

{
  "id": "conversation-ulid",
  "kind": "direct",
  "title": null,
  "created_by_profile_id": "sender-profile-id",
  "participants": [
    {
      "profile_id": "sender-profile-id",
      "profile_slug": "alice",
      "profile_title": "Alice Smith"
    },
    {
      "profile_id": "recipient-profile-id",
      "profile_slug": "bob",
      "profile_title": "Bob Jones"
    }
  ],
  "last_envelope": {
    "kind": "message",
    "message": "Hey, how are you?",
    "created_at": "2025-03-01T10:30:00Z"
  },
  "unread_count": 1
}

Envelopes (Message Types)

Mailbox uses “envelopes” for all communication:

Message Envelopes

Standard messages:

{
  "kind": "message",
  "message": "Hello! Looking forward to collaborating.",
  "reply_to_id": null,
  "status": "pending"
}

Features:

Plain text content (Markdown support planned)
Optional reply_to_id for threading
Sender profile information
Timestamp and read status

Invitation Envelopes

Profile join invitations:

{
  "kind": "invitation",
  "status": "invitation_pending_response",
  "properties": {
    "invitation_kind": "profile_join",
    "referral_id": "referral-ulid",
    "profile_id": "org-profile-id",
    "profile_slug": "acme-corp",
    "profile_title": "Acme Corporation"
  }
}

Telegram group invitations:

{
  "kind": "invitation",
  "status": "invitation_pending_response",
  "properties": {
    "invitation_kind": "telegram_group",
    "telegram_chat_id": -1001234567890,
    "group_profile_slug": "dev-community",
    "group_name": "Dev Community Chat",
    "invite_link": "https://t.me/+XYZ123"
  }
}

Invitations have special statuses and can be accepted, rejected, or revoked.

Badge Envelopes

Achievement or recognition badges:

{
  "kind": "badge",
  "message": "Congratulations on your first contribution!",
  "status": "pending",
  "properties": {
    "badge_type": "first_contribution",
    "icon": "🎖️",
    "points_awarded": 50
  }
}

Badges can be displayed on profiles or in user achievements section (future feature).

Pass Envelopes

Access passes or tickets:

{
  "kind": "pass",
  "message": "Your VIP pass to DevConf 2025",
  "status": "pending",
  "properties": {
    "event_id": "event-ulid",
    "pass_type": "vip",
    "qr_code": "base64-encoded-qr"
  }
}

Passes can be redeemed at events or for special access.

Envelope Lifecycle

Statuses

Pending

Default status for messages and badges

Accepted

Invitation accepted by recipient

Rejected

Invitation declined by recipient

Revoked

Invitation cancelled by sender before acceptance

Redeemed

Pass or badge claimed/used

Status Transitions

Pending → Accepted   (user accepts invitation)
Pending → Rejected   (user declines invitation)
Pending → Revoked    (sender cancels invitation)
Pending → Redeemed   (user uses pass/badge)

Status changes are final and cannot be reversed. Accepting then revoking requires a new invitation.

Participants

Each conversation has participants:

Participant Properties

{
  "id": "participant-ulid",
  "conversation_id": "conversation-ulid",
  "profile_id": "profile-ulid",
  "last_read_at": "2025-03-01T10:00:00Z",
  "is_archived": false,
  "joined_at": "2025-02-15T09:00:00Z",
  "left_at": null
}

Participant Actions

Mark as read:

Updates last_read_at timestamp
Reduces unread count
Read receipts (visible to sender)

Archive conversation:

Sets is_archived: true
Conversation hidden from main inbox
Can be unarchived anytime

Leave conversation:

Sets left_at timestamp
No longer receives new messages
Cannot send new messages
Previous messages remain visible

Archive conversations to declutter inbox while preserving message history.

Emoji Reactions

Add emoji reactions to any envelope:

Allowed Reactions

❤️

Love

🔥

Fire

🎉

Party

👍🏻

Thumbs up

👋🏻

Wave

🙌🏻

Raised hands

🖖🏻

Vulcan salute

😂

Laugh

😮

Surprised

😢

Sad

😱

Scream

🙈

See no evil

👀

Eyes

Reaction set is curated for professional communication. Custom emoji support planned for future.

Adding Reactions

Hover over envelope

Reaction picker appears

Select emoji

Click emoji to add reaction

Reaction recorded

Stored with your profile ID
Displayed to all participants
Can add multiple reactions

Remove reaction

Click same emoji again to remove

Reaction Display

Reactions show:

Emoji icon
Count of users who reacted
Your profile highlighted if you reacted
Tooltip with reactor names on hover

Read Receipts

Sent

Envelope created and delivered

Read

Recipient viewed the envelope

Read status determined by:

Envelope created_at timestamp
Recipient’s last_read_at timestamp
If last_read_at ≥ created_at, envelope is read

Unread Counts

Each conversation tracks unread envelopes:

unread_count = COUNT(envelopes WHERE created_at > participant.last_read_at)

Displayed:

Badge on conversation list item
Notification count in app header
Push notification (if enabled)

Click conversation to mark all messages as read automatically.

System Messages

Aya generates system envelopes for automated notifications: Examples:

Welcome message on signup
Referral status updates
Membership level changes
Event reminders
Content moderation notices

Properties:

kind: "system"
No sender profile (sent by platform)
Cannot be replied to
Informational only

Invitation Workflows

Profile Join Invitation

Referral approved

Community voting completes positively

System creates invitation

Conversation created (if doesn’t exist)
Invitation envelope sent to candidate
Status: invitation_pending_response

Candidate reviews

Opens mailbox, sees invitation details

Candidate responds

Accept:

Status: invitation_accepted
Membership created with assigned level
Welcome message sent

Reject:

Status: invitation_rejected
Referral marked declined
No membership created

Telegram Group Invitation

User gains membership level

User promoted to level with Telegram access

System generates invite link

Bot creates unique invite link for group

Invitation sent

Envelope with telegram_group invitation sent to user’s mailbox

User accepts

Clicks invite link
Joins Telegram group
Status: invitation_accepted

Telegram invitations are automatically sent when users reach appropriate membership level. See Telegram Bot for setup.

Conversation Management

Inbox View

Conversations displayed with:

Participant profiles (avatars, names)
Last envelope preview
Timestamp of last activity
Unread count badge
Sorted by most recent activity

Filtering

All

All conversations including archived

Unread

Conversations with unread envelopes

Archived

Archived conversations

Search

Search within mailbox:

Search by participant name
Search message content
Filter by envelope type
Date range filtering

Notifications

Mailbox triggers notifications: In-app:

Badge count on mailbox icon
Conversation list highlights
Browser notifications (if permitted)

Push notifications:

Mobile push (future)
Email notifications (configurable)
Telegram bot notifications

Configure notification preferences to balance staying informed vs. notification fatigue.

Privacy & Security

Conversation Privacy

Conversations are private between participants
No public viewing of mailbox content
Admins cannot read conversations (unless participant)
End-to-end encryption planned for future

Blocking & Spam

Spam prevention:

Rate limiting on message creation
Abuse reporting
Automatic spam detection

Blocking users:

Block profile to prevent messages
Existing conversations remain visible
Blocked status not visible to blocker

Report abusive messages to moderators. Spam and harassment violate Terms of Service.

Callbacks & Integrations

Mailbox supports event callbacks: OnEnvelopeCreated:

Triggered when new envelope sent
Used for notifications
Can integrate with external services

OnEnvelopeAccepted:

Triggered when invitation accepted
Used for membership creation
Updates referral status

OnEnvelopeRejected:

Triggered when invitation rejected
Used for referral cleanup
Notifies referrer

Callbacks are best-effort. Failures are logged but don’t block envelope creation.

Best Practices

Effective Messaging

Be clear and concise
Use subject context (what are you messaging about?)
Reply to specific messages for threading
Use reactions for quick acknowledgment
Archive old conversations

Invitation Management

Review invitations promptly
Accept if genuinely interested
Politely decline if not a fit
Don’t ignore invitations (sender sees pending status)
Read invitation details before accepting

Conversation Organization

Archive completed conversations
Use descriptive conversation titles (future feature)
Mark as read to reduce clutter
Leave conversations you no longer need
Report spam immediately

Troubleshooting

Cannot send message

Verify recipient profile exists
Check you have individual profile (mailbox requires profile)
Ensure recipient hasn’t blocked you
Check rate limits (max 100 messages/hour)

Invitation not received

Check mailbox filters (not in archived)
Verify invitation was sent (check referral status)
Look in system conversations
Check notification settings

Reactions not working

Ensure using allowed emoji from curated list
Check internet connection
Refresh page
Clear browser cache

API Examples

Send Message

curl -X POST https://api.aya.is/mailbox/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_profile_id": "my-profile-id",
    "target_profile_id": "recipient-profile-id",
    "kind": "message",
    "message": "Hello from API!"
  }'

List Conversations

curl https://api.aya.is/mailbox/conversations?profile_id=my-profile-id \
  -H "Authorization: Bearer $TOKEN"

Add Reaction

curl -X POST https://api.aya.is/mailbox/envelopes/{envelope_id}/reactions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"emoji": "❤️"}'

Next Steps

Profiles

Set up profile for messaging

Communities

Join communities and receive invitations

Telegram Bot

Link Telegram for notifications

Bulletin Board

Configure content digests

User Features

Community Features

Integrations

​Overview

​Conversations

​Conversation Types

Direct

System

​Creating a Conversation

​Conversation Properties

​Envelopes (Message Types)

​Message Envelopes

​Invitation Envelopes

​Badge Envelopes

​Pass Envelopes

​Envelope Lifecycle

​Statuses

​Status Transitions

​Participants

​Participant Properties

​Participant Actions

​Emoji Reactions

​Allowed Reactions

❤️

🔥

🎉

👍🏻

👋🏻

🙌🏻

🖖🏻

😂

😮

😢

😱

🙈

👀

​Adding Reactions

​Reaction Display

​Read Receipts

Sent

Read

​Unread Counts

​System Messages

​Invitation Workflows

​Profile Join Invitation

​Telegram Group Invitation

​Conversation Management

​Inbox View

​Filtering

All

Unread

Archived

​Search

​Notifications

​Privacy & Security

​Conversation Privacy

​Blocking & Spam

​Callbacks & Integrations

​Best Practices

​Troubleshooting

​API Examples

​Send Message

​List Conversations

​Add Reaction

​Next Steps

Profiles

Communities

Telegram Bot

Bulletin Board

Build docs developers (and LLMs) love

Overview

Conversations

Conversation Types

Creating a Conversation

Conversation Properties

Envelopes (Message Types)

Message Envelopes

Invitation Envelopes

Badge Envelopes

Pass Envelopes

Envelope Lifecycle

Statuses

Status Transitions

Participants

Participant Properties

Participant Actions

Emoji Reactions

Allowed Reactions

Adding Reactions

Reaction Display

Read Receipts

Unread Counts

System Messages

Invitation Workflows

Profile Join Invitation

Telegram Group Invitation

Conversation Management

Inbox View

Filtering

Search

Notifications

Privacy & Security

Conversation Privacy

Blocking & Spam

Callbacks & Integrations

Best Practices

Troubleshooting

API Examples

Send Message

List Conversations

Add Reaction

Next Steps