Quickstart

Five minutes from signup to a provider SDK talking to your own copy of Resend.

Prerequisites

An account on console.twinbay.ai. Email address, no invite code.
curl and jq, or the CLI.
Python 3.9+ with pip install resend to run the last step.

1. Mint an API key

Open API keys in the console and create one. The token is readable once, so copy it now.

export TWINBAY_API_KEY="tb_..."

Every request sends it in X-API-Key. A key acts with the role of the member who created it.

2. Create a sandbox

Name the twins you want and describe the state in a sentence.

curl -sX POST https://api.twinbay.ai/sandboxes \
  -H "X-API-Key: $TWINBAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "checkout-tests",
    "twins": [{ "twin": "resend" }],
    "prompt": "one segment with a delivered recipient and a hard-bounce recipient"
  }' | jq

The response is a 202: Twinbay recorded the sandbox and queued each twin for provisioning. Keep the ids.

export SANDBOX=<sandbox id>
export TWIN=<twins[0].id>

3. Wait for the twin to report ready

curl -s https://api.twinbay.ai/sandboxes/$SANDBOX \
  -H "X-API-Key: $TWINBAY_API_KEY" | jq '.twins[] | {state, url}'

Poll until state is ready, which takes a container start and a seeding pass. The url is the private hostname your code will call, such as https://resend-a1c93f.twinbay.run. A twin still not serving after two minutes reports failed with a failure telling you why.

4. Collect the credential

curl -sX POST \
  https://api.twinbay.ai/sandboxes/$SANDBOX/twins/$TWIN/credential \
  -H "X-API-Key: $TWINBAY_API_KEY" | jq -r .api_key

The twin mints a key shaped like the provider’s own. Twinbay hands it over once and refuses a second call, so store it where your test run can read it.

5. Point the provider SDK at the twin

Change the base URL and the key. Nothing else.

import resend

resend.api_key = "re_twinbay_9f2a..."       # step 4
resend.api_url = "https://resend-a1c93f.twinbay.run"  # step 3

sent = resend.Emails.send({
    "from": "onboarding@resend.dev",
    "to": "delivered@resend.dev",
    "subject": "Hello from the sandbox",
    "html": "<strong>It works.</strong>",
})

print(resend.Emails.get(sent["id"]))

6. Read back what your code sent

curl -s "https://api.twinbay.ai/sandboxes/$SANDBOX/logs" \
  -H "X-API-Key: $TWINBAY_API_KEY" \
  | jq '.items[] | {method, path, status_code, duration_ms}'

Fetch one log by id for the full request and response bodies.

The same run from the CLI

twinbay auth login
twinbay sandboxes create --name checkout-tests --twins '[{"twin":"resend"}]' \
  --prompt "one segment with a delivered and a hard-bounce recipient"
twinbay sandboxes twins credential --sandbox-id $SANDBOX --sandbox-twin-id $TWIN
twinbay sandboxes logs list --sandbox-id $SANDBOX

Advance sandbox time

Turn a queued email into a delivered or bounced one without waiting.

Edit sandbox state

Replace a record the provider would never let you write.

Available twins

What Resend and Linear model, and where each stops.

Templates

Save a sandbox definition and start every CI job from it.

Stuck? Write to hi@twinbay.ai.

Getting Started

Concepts

Interfaces

Prerequisites

1. Mint an API key

2. Create a sandbox

3. Wait for the twin to report ready

4. Collect the credential

5. Point the provider SDK at the twin

6. Read back what your code sent

The same run from the CLI

Next

Advance sandbox time

Edit sandbox state

Available twins

Templates

​Prerequisites

​1. Mint an API key

​2. Create a sandbox

​3. Wait for the twin to report ready

​4. Collect the credential

​5. Point the provider SDK at the twin

​6. Read back what your code sent

​The same run from the CLI

​Next

Advance sandbox time

Edit sandbox state

Available twins

Templates

Prerequisites

1. Mint an API key

2. Create a sandbox

3. Wait for the twin to report ready

4. Collect the credential

5. Point the provider SDK at the twin

6. Read back what your code sent

The same run from the CLI

Next