Sinkron

Sinkron enables AI agents to own permanent email addresses and manage inboxes programmatically via CLI and Python SDK.

authentication model: SINKRON_TOKEN is self-issued by the Sinkron platform, generated once by the Sinkron backend when sinkron register is run, printed to the CLI, and never again retrievable. no third-party OAuth. existing agents reuse their token from prior registration.

official website: https://www.sinkron.id source: https://github.com/zororaka00/sinkron pypi: https://pypi.org/project/sinkron/

---

intent

use this skill when you need to give an AI agent a permanent, recoverable email address and the ability to check, search, and manage its inbox programmatically. sinkron is the foundation for agent-to-human and agent-to-service email workflows where message history must persist across agent restarts. register once, reuse the token forever. the skill handles registration, inbox queries, message retrieval, deletion, and health monitoring via both CLI and Python SDK.

---

inputs

environment variables (required)

• SINKRON_TOKEN: self-issued credential from sinkron backend. obtained by running sinkron register --username USER --name NAME once. the backend prints the token exactly once in the response. store immediately in a secret manager or restricted env var. never hard-code, never log. rotate after suspected exposure.

external connections

• sinkron backend api: reachable at https://api.sinkron.id or equivalent (implicit in CLI/SDK). requires internet connectivity. subject to rate limits and availability windows. agent must be able to reach the api without proxy restrictions unless configured.

system requirements

• python 3.8+
• sinkron python package version 1.0.2 (pinned, never unpinned)
• bash or shell for CLI use (optional if using python sdk only)
• secret manager or secure env var storage for token

optional: python sdk setup

import os
from sinkron import SinkronClient

token = os.getenv("SINKRON_TOKEN")
client = SinkronClient(token=token)

---

procedure

step 1: verify package provenance and install

input: none (first-time setup)

sub-steps:

1. open https://www.sinkron.id and confirm it matches the expected project.
2. visit https://github.com/zororaka00/sinkron and review the source code for unexpected network callbacks or obfuscated logic.
3. open https://pypi.org/project/sinkron/ and confirm package owner is @zororaka00.
4. in an isolated environment (container or vm), download and inspect the package:

   pip download sinkron==1.0.2 --no-deps -d /tmp/sinkron-inspect
   unzip /tmp/sinkron-inspect/sinkron-1.0.2-*.whl
   

   review all .py files for suspicious code.
5. if provenance cannot be confirmed, stop. do not install.

output: confirmed package identity, isolated test environment ready.

---

step 2: install sinkron with pinned version

input: confirmed package provenance from step 1

sub-steps:

1. install via pip with explicit version pin:

   pip install sinkron==1.0.2
   

   or via uv:

   uv tool install sinkron==1.0.2
   

2. validate installation:

   sinkron --help
   

   if --help returns command list, installation succeeded.

output: sinkron CLI available in PATH, python SDK importable as from sinkron import SinkronClient.

---

step 3: register agent (new agents only) or retrieve prior token

input: none (registration) or prior SINKRON_TOKEN from secure storage (existing agents)

sub-steps for new agents:

1. decide on a unique USERNAME and friendly NAME for the agent.
2. run in a non-logged, non-shared environment (local machine, trusted ci/cd secret context):

   sinkron register --username MYAGENT --name "My Agent"
   

3. sinkron backend responds with:

   Registration successful.
   username: MYAGENT
   email:    MYAGENT@sinkron.id
   token:    snk_xxxxxxxxxxxxxxxxxxxxxxxx
   

4. copy the token immediately.
5. clear shell history:

   history -c
   # or on macOS/bash: unset HISTFILE
   

6. store token in secure location (see step 4).

sub-steps for existing agents:

1. retrieve SINKRON_TOKEN from your secret manager or restricted env var.
2. set it in current session:

   export SINKRON_TOKEN="snk_..."
   

output: SINKRON_TOKEN available in $SINKRON_TOKEN environment variable, token stored securely.

---

step 4: store and protect the token

input: SINKRON_TOKEN from step 3 registration output

sub-steps:

1. never store in source code, logs, or version control.
2. store in one of these:
   • secret manager (aws secrets manager, hashicorp vault, github secrets, etc.)
   • restricted .env file (gitignore'd, readable by ci/cd only)
   • ci/cd secret manager (github actions secrets, gitlab ci variables, etc.)
3. on local development, set via shell without logging:

   read -s SINKRON_TOKEN  # input without echoing
   export SINKRON_TOKEN
   

4. in ci/cd pipelines, inject as secret:

   # github actions example
   env:
     SINKRON_TOKEN: ${{ secrets.SINKRON_TOKEN }}
   

5. rotate token immediately after any suspected exposure (logged, shared terminal, etc.).

output: token stored securely, never visible in logs or version control.

---

step 5: verify agent identity (optional, recommended)

input: SINKRON_TOKEN from step 3, agent USERNAME

sub-steps:

1. run:

   sinkron agent MYAGENT
   

2. expected output:

   username: MYAGENT
   email:    MYAGENT@sinkron.id
   status:   active
   

output: agent identity confirmed, email address known.

---

step 6: check platform health before operations

input: SINKRON_TOKEN environment variable set

sub-steps:

1. run:

   sinkron health
   

2. expected output:

   status: healthy
   uptime: 99.5%
   

   or equivalent success signal.
3. if health check fails (network error, platform down, auth failure), stop and retry after 5+ minutes.

output: sinkron backend confirmed reachable and operational.

---

step 7: fetch inbox with pagination (safe inbox access)

input: SINKRON_TOKEN set, platform healthy from step 6

sub-steps:

1. fetch first page:

   sinkron inbox --page 1
   

2. expected output:

   {
     "messages": [
       { "id": "1", "from": "noreply@example.com", "subject": "...", "date": "2025-01-15T..." },
       ...
     ],
     "page": 1,
     "total": 42,
     "per_page": 10
   }
   

3. to search instead of paginating:

   sinkron inbox --search "keyword" --page 1
   

4. always use --page N to avoid large transfers. default page size is ~10 messages.

output: list of messages with metadata (id, from, subject, date). empty list if inbox is empty.

---

step 8: retrieve a specific message (optional)

input: message ID from step 7, SINKRON_TOKEN set

sub-steps:

1. run:

   sinkron message 1
   

2. expected output:

   {
     "id": "1",
     "from": "noreply@example.com",
     "to": "MYAGENT@sinkron.id",
     "subject": "Confirmation",
     "body": "Click here to confirm...",
     "date": "2025-01-15T10:30:00Z",
     "html": false
   }
   

output: full message body and metadata.

---

step 9: safe deletion of messages (never blind bulk delete)

input: message IDs from step 7, SINKRON_TOKEN set

sub-steps:

1. fetch inbox and review IDs (step 7).
2. identify messages to delete (e.g., spam, old alerts).
3. delete by explicit id list:

   sinkron delete-messages --ids 1,2,3
   

4. expected output:

   deleted: 3 messages
   

5. never run sinkron delete-inbox --force without reviewing contents first.
6. if full inbox deletion is necessary:

   sinkron inbox --page 1  # review
   sinkron delete-inbox --force  # only after confirmation
   

output: specified messages deleted. inbox state confirmed.

---

step 10: python sdk integration (programmatic use)

input: SINKRON_TOKEN environment variable set, sinkron package installed

example workflow:

import os
from sinkron import SinkronClient

# initialize once per runtime
token = os.getenv("SINKRON_TOKEN")
if not token:
    raise EnvironmentError("SINKRON_TOKEN not set")

client = SinkronClient(token=token)

# fetch inbox with pagination
messages = client.inbox(page=1)
print(f"inbox has {len(messages)} messages")

# search
alerts = client.inbox(search="alert", page=1)
for msg in alerts:
    print(f"{msg['id']}: {msg['subject']}")

# retrieve single message
msg = client.message(id=1)
print(msg['body'])

# delete messages
client.delete_messages(ids=[1, 2, 3])

# check health
health = client.health()
print(f"platform status: {health['status']}")

output: parsed message objects, operation results, no raw api responses.

---

decision points

decision 1: new agent vs. existing agent

• if this is the first time the agent is being set up: run sinkron register --username USER --name NAME (step 3, new agents sub-steps). the backend issues a token. store it securely.
• else (agent was registered previously): retrieve SINKRON_TOKEN from your secret manager. skip registration.

decision 2: platform health check failure

• if sinkron health returns status: healthy: proceed to inbox operations (step 7).
• else (health check fails, network error, platform down, auth error): wait 5+ minutes and retry. if failure persists after 3 retries, escalate to sinkron support. do not proceed with operations.

decision 3: empty inbox

• if sinkron inbox --page 1 returns messages: [] (empty list): inbox is empty. no messages to delete or review. this is not an error.
• else (messages present): proceed to step 8 or 9 (retrieve, delete, or search).

decision 4: missing or expired token

• if SINKRON_TOKEN environment variable is not set: prompt user to retrieve token from secure storage or run sinkron register (new agents). exit with error code 1.
• else (token is set): attempt api operation. if api returns 401 (unauthorized), token is expired or invalid. prompt user to reregister or rotate token.

decision 5: safe deletion confirmation

• if user runs sinkron delete-messages --ids 1,2,3 with explicit ids: delete only those messages. no confirmation prompt (ids are explicit).
• else if user runs sinkron delete-inbox --force: this is destructive. automation should only reach this after explicitly logging the message ids and confirming intent. never run without review.
• else (no deletion command): inbox is unchanged.

decision 6: rate limits and retries

• if api returns 429 (too many requests): implement exponential backoff (wait 2s, 4s, 8s, etc.). retry up to 3 times. if still failing, fail loudly with rate limit message.
• else (api returns success or 4xx/5xx other than 429): fail immediately with error message. do not retry on auth errors (401, 403) or invalid input (400).

decision 7: network timeout

• if request times out after 30s: assume platform is unreachable. fail with "network error, sinkron backend unreachable" message. do not retry automatically in cli. python sdk may implement exponential backoff at caller's discretion.
• else (request completes): return result.

decision 8: python sdk vs. cli

• if integrating sinkron into a larger python application or workflow: use python sdk (step 10). initialize client once, reuse across operations.
• else (shell scripts, devops automation, one-off commands): use cli (steps 1-9). each cli invocation is stateless.

---

output contract

success state for each procedure step:

step	output format	location	notes
step 1	confirmation (visual)	stdout	"provenance verified" or equivalent user confirmation
step 2	cli help text	stdout	sinkron --help returns command list (exit code 0)
step 3 (new)	token string	stdout (once), then secure storage	snk_xxxxxxxxxxxxxxxxxxxxxxxx format, 32+ chars
step 3 (existing)	none (token already stored)	environment variable SINKRON_TOKEN	silent success, no output required
step 4	none (token stored)	secret manager or .env file	token never appears in logs, version control, or cli output
step 5	json object	stdout	{"username": "...", "email": "...", "status": "active"}
step 6	json object	stdout	{"status": "healthy", "uptime": "..."}
step 7	json array of message objects	stdout	{"messages": [...], "page": 1, "total": N, "per_page": 10}
step 8	json object (single message)	stdout	{"id": "...", "from": "...", "subject": "...", "body": "...", "date": "..."}
step 9	plain text confirmation	stdout	deleted: N messages
step 10 (python sdk)	parsed python objects	sdk return values	list of dicts or single dict, no raw json

null/empty cases:

• empty inbox: messages: [] (valid, not an error).
• invalid message id: api returns 404. cli returns error message "message not found".
• invalid token: api returns 401. cli returns "unauthorized: check SINKRON_TOKEN".

---

outcome signal

the skill worked if you observe all of the following:

1. installation confirmed: sinkron --help displays command list with no errors (exit code 0).

2. agent registered or token verified: sinkron agent USERNAME returns agent metadata (username, email, status). email is in format USERNAME@sinkron.id.

3. platform reachable: sinkron health returns status: healthy or equivalent success message.

4. inbox accessible: sinkron inbox --page 1 returns a json object with messages array, page number, and total count. may be empty (valid) but must be valid json structure.

5. operations are idempotent: running the same operation twice (e.g., fetch inbox, delete message by id) produces the same result both times. no side effects or state drift.

6. tokens are never logged: inspect shell history, ci logs, application logs. confirm SINKRON_TOKEN never appears.

7. python sdk initializes without error:

   from sinkron import SinkronClient
   client = SinkronClient(token=os.getenv("SINKRON_TOKEN"))
   messages = client.inbox(page=1)  # returns list of dicts
   

   no exceptions, client object is usable.

8. deletion is safe and traceable: after sinkron delete-messages --ids 1,2,3, those exact ids no longer appear in sinkron inbox --page 1. no surprise deletions.

9. errors are explicit: auth failures (401), network errors (timeout, unreachable), and invalid input (400) produce readable error messages with remediation hints (e.g., "check SINKRON_TOKEN", "retry after platform recovery").

10. workflow is repeatable: run the same agent, inbox, and deletion commands from different machines or times. results are consistent. agent email address is permanent.

---

credits: original author @zororaka00 (web3 hungry). enriched for implexa quality standards with explicit decision logic, edge case handling, and output contracts.