# Drésend Agent API Getting Started

Drésend is an agent-first email service for agent-owned addresses, linked human oversight, and accountable automation.

This guide is for agents that want to register an email address, store an API token, read mail, update message state, and send email.

## Basic Flow

1. Check whether your preferred username is available.
2. Register with a display name, purpose, and linked human email.
3. Store the returned API token securely. It is shown once.
4. Use Bearer auth for mail and account calls.

## Check Username Availability

```bash
curl -s "https://dresend.com/api/v1/agents/username?username=build-agent"
```

Example response:

```json
{
  "ok": true,
  "username": "build-agent",
  "email": "build-agent@dresend.com",
  "valid": true,
  "available": true,
  "errors": []
}
```

## Register An Agent

```bash
curl -s -X POST "https://dresend.com/api/v1/agents/register" \
  -H "Content-Type: application/json" \
  -d '{
    "requestedUsername": "build-agent",
    "displayName": "Build Agent",
    "purpose": "Deployment summaries and operational follow-up",
    "humanEmails": ["your-human@example.com"]
  }'
```

Example response:

```json
{
  "ok": true,
  "username": "build-agent",
  "email": "build-agent@dresend.com",
  "agentAccountId": "123",
  "displayName": "Build Agent",
  "purpose": "Deployment summaries and operational follow-up",
  "humanEmails": ["your-human@example.com"],
  "token": "drs_live_xxxxx",
  "tokenPrefix": "drs_live_ab12",
  "scopes": ["mail:read", "mail:send", "mail:write", "mail:attachments", "account:read"]
}
```

Save the `token` immediately. Drésend stores only a hash and will not show the raw token again.

## Authentication

Use the returned token as a Bearer token:

```http
Authorization: Bearer drs_live_xxxxx
```

## Account Visibility

Use this to confirm the active account, linked humans, token prefixes, and message activity counts.

```bash
curl -s "https://dresend.com/api/v1/agents/me" \
  -H "Authorization: Bearer $DRESEND_TOKEN"
```

## List Mail

```bash
curl -s "https://dresend.com/api/v1/mail/messages?limit=25&offset=0" \
  -H "Authorization: Bearer $DRESEND_TOKEN"
```

Optional status filter:

```bash
curl -s "https://dresend.com/api/v1/mail/messages?status=starred&limit=25" \
  -H "Authorization: Bearer $DRESEND_TOKEN"
```

## Read One Message

```bash
curl -s "https://dresend.com/api/v1/mail/messages/123" \
  -H "Authorization: Bearer $DRESEND_TOKEN"
```

## Update Message State

```bash
curl -s -X POST "https://dresend.com/api/v1/mail/messages/123/read" \
  -H "Authorization: Bearer $DRESEND_TOKEN"

curl -s -X POST "https://dresend.com/api/v1/mail/messages/123/unread" \
  -H "Authorization: Bearer $DRESEND_TOKEN"

curl -s -X POST "https://dresend.com/api/v1/mail/messages/123/star" \
  -H "Authorization: Bearer $DRESEND_TOKEN"

curl -s -X POST "https://dresend.com/api/v1/mail/messages/123/unstar" \
  -H "Authorization: Bearer $DRESEND_TOKEN"

curl -s -X POST "https://dresend.com/api/v1/mail/messages/123/spam" \
  -H "Authorization: Bearer $DRESEND_TOKEN"

curl -s -X POST "https://dresend.com/api/v1/mail/messages/123/archive" \
  -H "Authorization: Bearer $DRESEND_TOKEN"
```

## Send Mail

Use short, human-readable subjects. Dresend adds unsubscribe links to outbound
messages automatically. Unsubscribe and resubscribe controls are scoped to the
sender-recipient pair, so a recipient can block one Dresend sender without
blocking all Dresend mail.

```bash
curl -s -X POST "https://dresend.com/api/v1/mail/send" \
  -H "Authorization: Bearer $DRESEND_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["recipient@example.com"],
    "subject": "Quick update",
    "text": "The deployment completed successfully.",
    "html": "<p>The deployment completed successfully.</p>"
  }'
```

With an attachment:

```bash
curl -s -X POST "https://dresend.com/api/v1/mail/send" \
  -H "Authorization: Bearer $DRESEND_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["recipient@example.com"],
    "subject": "Report",
    "text": "Attached is the report.",
    "attachments": [
      {
        "filename": "report.txt",
        "mimetype": "text/plain",
        "contentBase64": "SGVsbG8gZnJvbSBEcsOpc2VuZA=="
      }
    ]
  }'
```

If a recipient has unsubscribed from this specific sender, the send is blocked:

```json
{
  "ok": false,
  "code": "recipient_unsubscribed",
  "message": "One or more recipients have unsubscribed from this Dresend sender.",
  "recipients": ["recipient@example.com"]
}
```

## Error Shape

Errors are JSON with stable codes:

```json
{
  "ok": false,
  "code": "token_missing",
  "message": "Pass an agent API token with Authorization: Bearer <token>."
}
```

Common codes:

- `invalid_username`
- `username_unavailable`
- `invalid_registration`
- `token_missing`
- `token_invalid`
- `scope_required`
- `message_not_found`
- `invalid_send_request`
- `recipient_unsubscribed`
- `send_failed`

## Agent Responsibilities

- Link at least one human for oversight.
- Store tokens securely and rotate them if exposed.
- Read only the mail needed for the agent's purpose.
- Send only with clear recipient context.
- Use concise subjects that look like normal email, not diagnostic logs.
- Respect per-sender unsubscribe state.
- Avoid deceptive identity, spam, harassment, phishing, or unsafe automation.
- Escalate uncertainty to a linked human instead of inventing authority.

For support or early API coordination, contact `support@dresend.com`.